Delen via

Logboekopname-API in Azure Monitor

  • Artikel

Met de Logboekopname-API in Azure Monitor kunt u gegevens verzenden naar een Log Analytics-werkruimte met behulp van een REST API-aanroep of clientbibliotheken. Met de API kunt u gegevens verzenden naar ondersteunde Azure-tabellen of naar aangepaste tabellen die u maakt. U kunt ook het schema van Azure-tabellen uitbreiden met aangepaste kolommen om aanvullende gegevens te accepteren.

Basisbewerking

Gegevens kunnen worden verzonden naar de Logboekopname-API vanuit elke toepassing die een REST API-aanroep kan maken. Dit kan een aangepaste toepassing zijn die u maakt, of het kan een toepassing of agent zijn die begrijpt hoe u gegevens naar de API verzendt. Hiermee geeft u een regel voor gegevensverzameling (DCR) op die de doeltabel en werkruimte en de referenties van een app-registratie met toegang tot de opgegeven DCR bevat. De gegevens worden verzonden naar een eindpunt dat is opgegeven door de DCR of naar een eindpunt voor gegevensverzameling (DCE) als u een privékoppeling gebruikt.

De gegevens die door uw toepassing naar de API worden verzonden, moeten worden opgemaakt in JSON en overeenkomen met de structuur die door de DCR wordt verwacht. Het hoeft niet per se overeen te komen met de structuur van de doeltabel, omdat de DCR een transformatie kan bevatten om de gegevens te converteren zodat deze overeenkomen met de structuur van de tabel. U kunt de doeltabel en werkruimte wijzigen door de DCR te wijzigen zonder de API-aanroep of brongegevens te wijzigen.

Diagram met een overzicht van de API voor logboekopname.

Configuratie

In de volgende tabel wordt elk onderdeel in Azure beschreven dat u moet configureren voordat u de API voor logboekopname kunt gebruiken.

Notitie

Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor een PowerShell-script waarmee de configuratie van deze onderdelen wordt geautomatiseerd.

Onderdeel Functie
App-registratie en -geheim De toepassingsregistratie wordt gebruikt om de API-aanroep te verifiëren. Het moet toestemming worden verleend aan de DCR die hieronder wordt beschreven. De API-aanroep bevat de id van de toepassing (client) en de map-id (tenant) van de toepassing en de waarde van een toepassingsgeheim.

Zie Een Microsoft Entra-toepassing en service-principal maken die toegang heeft tot resources en een nieuw toepassingsgeheim maken.
Tabel in Log Analytics-werkruimte De tabel in de Log Analytics-werkruimte moet bestaan voordat u er gegevens naar kunt verzenden. U kunt een van de ondersteunde Azure-tabellen gebruiken of een aangepaste tabel maken met behulp van een van de beschikbare methoden. Als u Azure Portal gebruikt om de tabel te maken, wordt de DCR voor u gemaakt, inclusief een transformatie als deze vereist is. Met een andere methode moet u de DCR handmatig maken zoals beschreven in de volgende sectie.

Zie Een aangepaste tabel maken.
Regel voor gegevensverzameling (DCR) Azure Monitor maakt gebruik van de regel voor gegevensverzameling (DCR) om inzicht te hebben in de structuur van de binnenkomende gegevens en wat u ermee moet doen. Als de structuur van de tabel en de binnenkomende gegevens niet overeenkomen, kan de DCR een transformatie bevatten om de brongegevens te converteren zodat deze overeenkomen met de doeltabel. U kunt de transformatie ook gebruiken om brongegevens te filteren en andere berekeningen of conversies uit te voeren.

Als u een aangepaste tabel maakt met behulp van Azure Portal, worden de DCR en de transformatie voor u gemaakt op basis van voorbeeldgegevens die u opgeeft. Als u een bestaande tabel gebruikt of een aangepaste tabel maakt met een andere methode, moet u de DCR handmatig maken met behulp van details in de volgende sectie.

Zodra uw DCR is gemaakt, moet u er toegang toe verlenen voor de toepassing die u in de eerste stap hebt gemaakt. Selecteer in het menu Monitor in Azure Portal regels voor gegevensverzameling en vervolgens de DCR die u hebt gemaakt. Selecteer Toegangsbeheer (IAM) voor de DCR en selecteer vervolgens Roltoewijzing toevoegen om de rol Monitoring Metrics Publisher toe te voegen.

Eindpunt

Het REST API-eindpunt voor de logboekopname-API kan een eindpunt voor gegevensverzameling (DCE) of het OPNAME-eindpunt voor DCR-logboeken zijn.

Het OPNAME-eindpunt voor DCR-logboeken wordt gegenereerd wanneer u een DCR maakt voor directe opname. Als u dit eindpunt wilt ophalen, opent u de DCR in de JSON-weergave in Azure Portal. Mogelijk moet u de API-versie wijzigen in de nieuwste versie om de eindpunten weer te geven.

Schermopname van het eindpunt voor logboekopname in een DCR.

Een DCE is alleen vereist wanneer u verbinding maakt met een Log Analytics-werkruimte via private link of als uw DCR het opname-eindpunt voor logboeken niet bevat. Dit kan het geval zijn als u een oudere DCR gebruikt of als u de DCR hebt gemaakt zonder de "kind": "Direct" parameter. Zie De regel voor gegevensverzameling (DCR) hieronder voor meer informatie.

Notitie

De logsIngestion accommodatie is toegevoegd op 31 maart 2024. Vóór deze datum was een DCE vereist voor de logboekopname-API. Eindpunten kunnen niet worden toegevoegd aan een bestaande DCR, maar u kunt bestaande DCR's blijven gebruiken met bestaande DCE's. Als u naar een DCR-eindpunt wilt gaan, moet u een nieuwe DCR maken om de bestaande te vervangen. Een DCR met eindpunten kan ook een DCE gebruiken. In dit geval kunt u kiezen of u de DCE- of DCR-eindpunten wilt gebruiken voor elk van de clients die de DCR gebruiken.

Regel voor gegevensverzameling (DCR)

Wanneer u een aangepaste tabel maakt in een Log Analytics-werkruimte met behulp van Azure Portal, wordt er een DCR gemaakt die kan worden gebruikt met de API voor logboekopname. Als u gegevens verzendt naar een tabel die al bestaat, moet u de DCR handmatig maken. Begin met de onderstaande voorbeeld-DCR en vervang waarden voor de volgende parameters in de sjabloon. Gebruik een van de methoden die worden beschreven in Regels voor gegevensverzameling maken en bewerken in Azure Monitor om de DCR te maken.

Parameter Description
region Regio om uw DCR te maken. Dit moet overeenkomen met de regio van de Log Analytics-werkruimte en de DCE als u er een gebruikt.
dataCollectionEndpointId Resource-id van uw DCE. Verwijder deze parameter als u het DCR-opnamepunt gebruikt.
streamDeclarations Wijzig de kolomlijst in de kolommen in uw binnenkomende gegevens. U hoeft de naam van de stream niet te wijzigen, omdat dit alleen moet overeenkomen met de streams naam in dataFlows.
workspaceResourceId Resource-id van uw Log Analytics-werkruimte. U hoeft de naam niet te wijzigen, omdat deze alleen moet overeenkomen met de destinations naam in dataFlows.
transformKql KQL-query die moet worden toegepast op de binnenkomende gegevens. Als het schema van de binnenkomende gegevens overeenkomt met het schema van de tabel, kunt u gebruiken source voor de transformatie die de binnenkomende gegevens ongewijzigd doorgeeft. Gebruik anders een query waarmee de gegevens worden getransformeerd zodat deze overeenkomen met het schema van de doeltabel.
outputStream De naam van de tabel om de gegevens te verzenden. Voeg voor een aangepaste tabel het voorvoegsel Custom-table-name<> toe. Voeg voor een ingebouwde tabel het voorvoegsel Microsoft-tabelnaam<> toe. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

Clientbibliotheken

Naast het maken van een REST API-aanroep kunt u de volgende clientbibliotheken gebruiken om gegevens te verzenden naar de logboekopname-API. Voor de bibliotheken zijn dezelfde onderdelen vereist die worden beschreven in Configuratie. Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor voorbeelden van elk van deze bibliotheken.

REST API-aanroep

Als u gegevens wilt verzenden naar Azure Monitor met een REST API-aanroep, voert u een POST-aanroep via HTTP uit. Details die vereist zijn voor deze aanroep, worden beschreven in deze sectie.

URI

De URI bevat de regio, het DCE- of DCR-opname-eindpunt, de DCR-id en de stroomnaam. Ook wordt de API-versie opgegeven.

De URI gebruikt de volgende indeling.

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Voorbeeld:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

De DCR Immutable ID wordt gegenereerd voor de DCR wanneer deze wordt gemaakt. U kunt deze ophalen op de overzichtspagina voor de DCR in Azure Portal.

Schermopname van een regel voor gegevensverzameling met de onveranderbare id.

Stream Name verwijst naar de stroom in de DCR die de aangepaste gegevens moet verwerken.

Kopteksten

In de volgende tabel worden die headers voor uw API-aanroep beschreven.

Koptekst Vereist? Beschrijving
Autorisatie Ja Bearer-token dat is verkregen via de clientreferentiestroom. Gebruik de tokendoelwaarde voor uw cloud:

Openbare Azure-cloud - https://monitor.azure.com
Microsoft Azure beheerd door 21Vianet-cloud - https://monitor.azure.cn
Azure US Government-cloud - https://monitor.azure.us
Inhoudstype Ja application/json
Content-Encoding Nee gzip
x-ms-client-request-id Nee Guid met tekenreeksindeling. Dit is een aanvraag-id die door Microsoft kan worden gebruikt voor probleemoplossingsdoeleinden.

Hoofdtekst

De hoofdtekst van de aanroep bevat de aangepaste gegevens die naar Azure Monitor moeten worden verzonden. De vorm van de gegevens moet een JSON-matrix met itemstructuur zijn die overeenkomt met de indeling die door de stream in de DCR wordt verwacht. Als het nodig is om één item binnen de API-aanroep te verzenden, moeten de gegevens worden verzonden als een matrix met één item.

Voorbeeld:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Zorg ervoor dat de aanvraagbody correct is gecodeerd in UTF-8 om problemen met gegevensoverdracht te voorkomen.

Opmerking

Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor een voorbeeld van de API-aanroep met behulp van PowerShell.

Ondersteunde tabellen

Gegevens die naar de opname-API worden verzonden, kunnen worden verzonden naar de volgende tabellen:

Tabellen Beschrijving
Aangepaste tabellen Elke aangepaste tabel die u in uw Log Analytics-werkruimte maakt. De doeltabel moet bestaan voordat u er gegevens naar kunt verzenden. Aangepaste tabellen moeten het _CL achtervoegsel hebben.
Azure-tabellen De volgende Azure-tabellen worden momenteel ondersteund. Andere tabellen kunnen aan deze lijst worden toegevoegd als ondersteuning voor deze tabellen wordt geïmplementeerd.

Notitie

Kolomnamen moeten beginnen met een letter en kunnen bestaan uit maximaal 45 alfanumerieke tekens en onderstrepingstekens (_). _ResourceId, , _ResourceIdid, _SubscriptionId, , TenantId, , Typeen Title UniqueIdzijn gereserveerde kolomnamen. Aangepaste kolommen die u aan een Azure-tabel toevoegt, moeten het achtervoegsel _CFhebben.

Limieten en beperkingen

Zie Azure Monitor-servicelimieten voor limieten met betrekking tot de Logboekopname-API.

Volgende stappen