Logboekgegevens naar Azure Monitor verzenden met de HTTP Data Collector-API (preview)

In dit artikel wordt beschreven hoe u de HTTP Data Collector-API gebruikt om logboekgegevens te verzenden naar Azure Monitor vanaf een REST API-client. Hierin wordt beschreven hoe u gegevens opmaken die worden verzameld door uw script of toepassing, hoe u deze opneemt in een aanvraag en deze aanvraag laat geautoriseerd door Azure Monitor. We bieden voorbeelden voor Azure PowerShell, C# en Python.

Notitie

De AZURE Monitor HTTP Data Collector-API is in openbare preview.

Concepten

U kunt de HTTP Data Collector-API gebruiken om logboekgegevens te verzenden naar een Log Analytics-werkruimte in Azure Monitor vanaf elke client die een REST API kan aanroepen. De client kan een runbook in Azure Automation zijn waarmee beheergegevens van Azure of een andere cloud worden verzameld, of het kan een alternatief beheersysteem zijn dat Gebruikmaakt van Azure Monitor om logboekgegevens te consolideren en te analyseren.

Alle gegevens in de Log Analytics-werkruimte worden opgeslagen als een record met een bepaald recordtype. U formatteert uw gegevens voor het verzenden naar de HTTP Data Collector-API als meerdere records in JavaScript Object Notation (JSON). Wanneer u de gegevens verzendt, wordt er een afzonderlijke record gemaakt in de opslagplaats voor elke record in de nettolading van de aanvraag.

Schermopname van het overzicht van HTTP Data Collector.

Een aanvraag maken

Als u de HTTP Data Collector-API wilt gebruiken, maakt u een POST-aanvraag die de gegevens bevat die u in JSON wilt verzenden. De volgende drie tabellen bevatten de kenmerken die vereist zijn voor elke aanvraag. Verderop in het artikel worden elk kenmerk in meer detail beschreven.

Aanvraag-URI

Kenmerk Eigenschap
Methode POST
URI <https:// CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01>
Inhoudstype application/json

URI-parameters aanvragen

Parameter Beschrijving
CustomerID De unieke id voor de Log Analytics-werkruimte.
Resource De naam van de API-resource: /api/logs.
API-versie De versie van de API die met deze aanvraag moet worden gebruikt. Momenteel is de versie 2016-04-01.

Aanvraagheaders

Header Description
Autorisatie De autorisatiehandtekening. Verderop in het artikel kunt u lezen hoe u een HMAC-SHA256-header maakt.
Log-Type Geef het recordtype op van de gegevens die worden verzonden. Het mag alleen letters, cijfers en het onderstrepingsteken (_) bevatten en mag niet langer zijn dan 100 tekens.
x-ms-date De datum waarop de aanvraag is verwerkt, in RFC 7234-indeling.
x-ms-AzureResourceId De resource-id van de Azure-resource waaraan de gegevens moeten worden gekoppeld. Hiermee wordt de eigenschap _ResourceId ingevuld en kunnen de gegevens worden opgenomen in resourcecontextquery's . Als dit veld niet is opgegeven, worden de gegevens niet opgenomen in resourcecontextquery's.
time-generated-field De naam van een veld in de gegevens dat de tijdstempel van het gegevensitem bevat. Als u een veld opgeeft, wordt de inhoud ervan gebruikt voor TimeGenerated. Als u dit veld niet opgeeft, is de standaardwaarde voor TimeGenerated de tijd waarop het bericht wordt opgenomen. De inhoud van het berichtveld moet de ISO 8601-indeling JJJJ-MM-DDThh:mm:ssZ volgen. De waarde Time Generated mag niet ouder zijn dan 2 dagen voor de ontvangsttijd of de tijd waarop het bericht wordt opgenomen, wordt gebruikt.

Autorisatie

Elke aanvraag voor de HTTP Data Collector-API van Azure Monitor moet een autorisatieheader bevatten. Als u een aanvraag wilt verifiëren, ondertekent u de aanvraag met de primaire of de secundaire sleutel voor de werkruimte die de aanvraag doet. Geef vervolgens die handtekening door als onderdeel van de aanvraag.

Dit is de indeling voor de autorisatieheader:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID is de unieke id voor de Log Analytics-werkruimte. Handtekening is een HMAC (Hash-based Message Authentication Code) die wordt samengesteld op basis van de aanvraag en vervolgens wordt berekend met behulp van het SHA256-algoritme. Vervolgens codeer je deze met behulp van Base64-codering.

Gebruik deze indeling om de SharedKey-handtekeningtekenreeks te coderen:

StringToSign = VERB + "\n" +
                  Content-Length + "\n" +
                  Content-Type + "\n" +
                  "x-ms-date:" + x-ms-date + "\n" +
                  "/api/logs";

Hier volgt een voorbeeld van een handtekeningtekenreeks:

POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs

Wanneer u de handtekeningtekenreeks hebt, codeert u deze met behulp van het algoritme HMAC-SHA256 op de tekenreeks met UTF-8-codering en codeert u het resultaat vervolgens als Base64. Gebruik deze indeling:

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

De voorbeelden in de volgende secties bevatten voorbeeldcode om u te helpen een autorisatieheader te maken.

Aanvraagbody

De hoofdtekst van het bericht moet zich in JSON bevinden. Deze moet een of meer records bevatten met de eigenschapsnaam en waardeparen in de volgende indeling. De naam van de eigenschap mag alleen letters, cijfers en het onderstrepingsteken (_) bevatten.

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

U kunt meerdere records samenvoegen in één aanvraag met behulp van de volgende indeling. Alle records moeten hetzelfde recordtype hebben.

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    },
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

Recordtype en eigenschappen

U definieert een aangepast recordtype wanneer u gegevens verzendt via de AZURE Monitor HTTP Data Collector-API. Op dit moment kunt u geen gegevens schrijven naar bestaande recordtypen die zijn gemaakt door andere gegevenstypen en oplossingen. Azure Monitor leest de binnenkomende gegevens en maakt vervolgens eigenschappen die overeenkomen met de gegevenstypen van de waarden die u invoert.

Elke aanvraag voor de Data Collector-API moet een logboektypeheader bevatten met de naam voor het recordtype. Het achtervoegsel _CL wordt automatisch toegevoegd aan de naam die u invoert om het te onderscheiden van andere logboektypen als een aangepast logboek. Als u bijvoorbeeld de naam MyNewRecordType invoert, maakt Azure Monitor een record met het type MyNewRecordType_CL. Dit zorgt ervoor dat er geen conflicten zijn tussen door de gebruiker gemaakte typenamen en namen die worden geleverd in de huidige of toekomstige Microsoft-oplossingen.

Om het gegevenstype van een eigenschap te identificeren, voegt Azure Monitor een achtervoegsel toe aan de eigenschapsnaam. Als een eigenschap een null-waarde bevat, wordt de eigenschap niet opgenomen in die record. Deze tabel bevat het gegevenstype van de eigenschap en het bijbehorende achtervoegsel:

Gegevenstype eigenschap Achtervoegsel
Tekenreeks _S
Booleaans _B
Dubbel _D
Datum/tijd _T
GUID (opgeslagen als een tekenreeks) _G

Notitie

Tekenreekswaarden die GUID's lijken te zijn, krijgen het achtervoegsel _g en zijn opgemaakt als een GUID, zelfs als de binnenkomende waarde geen streepjes bevat. Bijvoorbeeld: '8145d822-13a7-44ad-859c-36f31a84f6dd' en '8145d82213a744ad859c36f31a84f6dd" worden opgeslagen als "8145d822-13a7-44ad-859c-36f31a84f6dd". De enige verschillen tussen deze en een andere tekenreeks zijn de _g in de naam en het invoegen van streepjes als deze niet zijn opgegeven in de invoer.

Het gegevenstype dat Azure Monitor voor elke eigenschap gebruikt, is afhankelijk van het feit of het recordtype voor de nieuwe record al bestaat.

  • Als het recordtype niet bestaat, maakt Azure Monitor een nieuw record met behulp van de JSON-typedeductie om het gegevenstype voor elke eigenschap voor de nieuwe record te bepalen.
  • Als het recordtype bestaat, probeert Azure Monitor een nieuwe record te maken op basis van bestaande eigenschappen. Als het gegevenstype voor een eigenschap in de nieuwe record niet overeenkomt en niet kan worden geconverteerd naar het bestaande type, of als de record een eigenschap bevat die niet bestaat, maakt Azure Monitor een nieuwe eigenschap met het relevante achtervoegsel.

Met de volgende vermelding voor indienen wordt bijvoorbeeld een record gemaakt met drie eigenschappen: number_d, boolean_b en string_s:

Schermopname van voorbeeldrecord 1.

Als u deze volgende vermelding indient, waarbij alle waarden zijn opgemaakt als tekenreeksen, zouden de eigenschappen niet veranderen. U kunt de waarden converteren naar bestaande gegevenstypen.

Schermopname van voorbeeldrecord 2.

Maar als u deze volgende indiening doet, maakt Azure Monitor de nieuwe eigenschappen boolean_d en string_d. U kunt deze waarden niet converteren.

Schermopname van voorbeeldrecord 3.

Als u vervolgens de volgende vermelding indient voordat het recordtype wordt gemaakt, maakt Azure Monitor een record met drie eigenschappen: number_s, boolean_s en string_s. In dit item wordt elk van de beginwaarden opgemaakt als een tekenreeks:

Schermopname van voorbeeldrecord 4.

Gereserveerde eigenschappen

De volgende eigenschappen zijn gereserveerd en mogen niet worden gebruikt in een aangepast recordtype. U ontvangt een foutbericht als uw nettolading een van deze eigenschapsnamen bevat:

  • tenant
  • TimeGenerated
  • RawData

Gegevenslimieten

De gegevens die naar de Azure Monitor-API voor gegevensverzameling worden geplaatst, zijn onderhevig aan bepaalde beperkingen:

  • Maximaal 30 MB per post naar de Azure Monitor Data Collector-API. Dit is een limiet voor één bericht. Als de gegevens van één post groter zijn dan 30 MB, moet u de gegevens opsplitsen in kleinere segmenten en ze gelijktijdig verzenden.
  • Maximaal 32 kB voor veldwaarden. Als een veldwaarde groter is dan 32 kB, worden de gegevens afgekapt.
  • Aanbevolen maximum van 50 velden voor een bepaald type. Dit is een praktische limiet vanuit het oogpunt van bruikbaarheid en zoekervaring.
  • Tabellen in Log Analytics-werkruimten ondersteunen maximaal 500 kolommen (in dit artikel velden genoemd).
  • Maximaal 45 tekens voor kolomnamen.

Retourcodes

De HTTP-statuscode 200 betekent dat de aanvraag is ontvangen voor verwerking. Dit geeft aan dat de bewerking is voltooid.

De volledige set statuscodes die de service kan retourneren, wordt weergegeven in de volgende tabel:

Code Status Foutcode Description
200 OK De aanvraag is geaccepteerd.
400 Ongeldige aanvraag InactiveCustomer De werkruimte is gesloten.
400 Ongeldige aanvraag InvalidApiVersion De API-versie die u hebt opgegeven, wordt niet herkend door de service.
400 Ongeldige aanvraag InvalidCustomerId De opgegeven werkruimte-id is ongeldig.
400 Ongeldige aanvraag InvalidDataFormat Er is een ongeldige JSON verzonden. De hoofdtekst van het antwoord bevat mogelijk meer informatie over het oplossen van de fout.
400 Ongeldige aanvraag InvalidLogType Het opgegeven logboektype bevat speciale tekens of numerieke tekens.
400 Ongeldige aanvraag MissingApiVersion De API-versie is niet opgegeven.
400 Ongeldige aanvraag MissingContentType Het inhoudstype is niet opgegeven.
400 Ongeldige aanvraag MissingLogType Het vereiste waardelogboektype is niet opgegeven.
400 Ongeldige aanvraag UnsupportedContentType Het inhoudstype is niet ingesteld op application/json.
403 Verboden InvalidAuthorization De service kan de aanvraag niet verifiëren. Controleer of de werkruimte-id en de verbindingssleutel geldig zijn.
404 Niet gevonden De opgegeven URL is onjuist of de aanvraag is te groot.
429 Te veel aanvragen De service ondervindt een grote hoeveelheid gegevens uit uw account. Probeer de aanvraag later opnieuw.
500 Interne serverfout UnspecifiedError Er is een interne fout opgetreden in de service. Probeer de aanvraag opnieuw.
503 Service niet beschikbaar ServiceUnavailable De service is momenteel niet beschikbaar voor het ontvangen van aanvragen. Probeer uw aanvraag opnieuw.

Querygegevens

Als u een query wilt uitvoeren op gegevens die zijn verzonden door de HTTP-gegevensverzamelaar-API van Azure Monitor, zoekt u naar records waarvan type gelijk is aan de LogType-waarde die u hebt opgegeven en die u hebt toegevoegd aan _CL. Als u bijvoorbeeld MyCustomLog hebt gebruikt, retourneert u alle records met MyCustomLog_CL.

Voorbeeldaanvragen

In deze sectie vindt u voorbeelden die laten zien hoe u gegevens verzendt naar de AZURE Monitor HTTP Data Collector-API met behulp van verschillende programmeertalen.

Stel voor elk voorbeeld de variabelen voor de autorisatieheader als volgt in:

  1. Zoek in de Azure Portal uw Log Analytics-werkruimte.
  2. Selecteer Agents management.
  3. Selecteer rechts van Werkruimte-id het pictogram Kopiëren en plak de id als de waarde van de variabele Klant-id .
  4. Selecteer rechts van Primaire sleutel het pictogram Kopiëren en plak de id als de waarde van de variabele Gedeelde sleutel .

U kunt ook de variabelen voor het logboektype en de JSON-gegevens wijzigen.

# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  

# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"

# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""


# Create two records with the same set of properties to create
$json = @"
[{  "StringValue": "MyString1",
    "NumberValue": 42,
    "BooleanValue": true,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{   "StringValue": "MyString2",
    "NumberValue": 43,
    "BooleanValue": false,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@

# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
    $xHeaders = "x-ms-date:" + $date
    $stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource

    $bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
    $keyBytes = [Convert]::FromBase64String($sharedKey)

    $sha256 = New-Object System.Security.Cryptography.HMACSHA256
    $sha256.Key = $keyBytes
    $calculatedHash = $sha256.ComputeHash($bytesToHash)
    $encodedHash = [Convert]::ToBase64String($calculatedHash)
    $authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
    return $authorization
}

# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
    $method = "POST"
    $contentType = "application/json"
    $resource = "/api/logs"
    $rfc1123date = [DateTime]::UtcNow.ToString("r")
    $contentLength = $body.Length
    $signature = Build-Signature `
        -customerId $customerId `
        -sharedKey $sharedKey `
        -date $rfc1123date `
        -contentLength $contentLength `
        -method $method `
        -contentType $contentType `
        -resource $resource
    $uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"

    $headers = @{
        "Authorization" = $signature;
        "Log-Type" = $logType;
        "x-ms-date" = $rfc1123date;
        "time-generated-field" = $TimeStampField;
    }

    $response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
    return $response.StatusCode

}

# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType  

Alternatieven en overwegingen

Hoewel de Data Collector-API de meeste van uw behoeften moet dekken bij het verzamelen van vrije-vormgegevens in Azure-logboeken, hebt u mogelijk een alternatieve benadering nodig om enkele van de beperkingen van de API te overwinnen. De opties, inclusief belangrijke overwegingen, worden weergegeven in de volgende tabel:

Alternatieve Description Het meest geschikt voor
Aangepaste gebeurtenissen: opname op basis van een systeemeigen SDK in Application Insights Application Insights, meestal geïnstrueerd via een SDK in uw toepassing, biedt u de mogelijkheid om aangepaste gegevens te verzenden via Aangepaste gebeurtenissen.
  • Gegevens die in uw toepassing worden gegenereerd, maar niet worden opgehaald door de SDK via een van de standaardgegevenstypen (aanvragen, afhankelijkheden, uitzonderingen, enzovoort).
  • Gegevens die het vaakst worden gecorreleerd met andere toepassingsgegevens in Application Insights.
Gegevensverzamelaar-API in Azure Monitor-logboeken De Gegevensverzamelaar-API in Azure Monitor-logboeken is een volledig open manier om gegevens op te nemen. Alle gegevens die zijn opgemaakt in een JSON-object, kunnen hier worden verzonden. Nadat het is verzonden, wordt het verwerkt en beschikbaar gemaakt in MonitorLogboeken om te worden gecorreleerd met andere gegevens in monitorlogboeken of met andere Application Insights-gegevens.

Het is vrij eenvoudig om de gegevens als bestanden te uploaden naar een Azure Blob Storage-blob, waar de bestanden worden verwerkt en vervolgens worden geüpload naar Log Analytics. Zie Een gegevenspijplijn maken met de Gegevensverzamelaar-API voor een voorbeeldimplementatie.
  • Gegevens die niet noodzakelijkerwijs worden gegenereerd in een toepassing die is geïnstrueerd in Application Insights.
    Voorbeelden zijn opzoek- en feitentabellen, referentiegegevens, vooraf geaggregeerde statistieken, enzovoort.
  • Gegevens waarnaar kruislings wordt verwezen met andere Azure Monitor-gegevens (Application Insights, andere gegevenstypen monitorlogboeken, Defender voor Cloud, Container Insights en virtuele machines, enzovoort).
Azure Data Explorer Azure Data Explorer, nu algemeen beschikbaar voor het publiek, is het gegevensplatform dat application insights analytics- en Azure Monitor-logboeken mogelijk maakt. Door het gegevensplatform in de onbewerkte vorm te gebruiken, hebt u volledige flexibiliteit (maar is de overhead van beheer vereist) voor het cluster (Kubernetes op rollen gebaseerd toegangsbeheer (RBAC), retentiepercentage, schema, enzovoort). Azure Data Explorer biedt veel opnameopties, waaronder CSV-, TSV- en JSON-bestanden.
  • Gegevens die niet worden gecorreleerd met andere gegevens onder Application Insights of monitorlogboeken.
  • Gegevens waarvoor geavanceerde opname- of verwerkingsmogelijkheden zijn vereist die momenteel niet beschikbaar zijn in Azure Monitor-logboeken.

Volgende stappen