Skicka loggdata till Azure Monitor med hjälp av HTTP Data Collector API (inaktuellt)

Den här artikeln visar hur du använder HTTP Data Collector API för att skicka loggdata till Azure Monitor från en REST API-klient. Den beskriver hur du formaterar data som samlas in av ditt skript eller program, inkluderar dem i en begäran och har den begäran auktoriserad av Azure Monitor. Vi tillhandahåller exempel för Azure PowerShell, C#och Python.

Kommentar

AZURE Monitor HTTP Data Collector-API:et har blivit inaktuellt och fungerar inte längre från och med 2026-09-14. Den har ersatts av API:et för logginmatning.

Begrepp

Du kan använda HTTP Data Collector-API:et för att skicka loggdata till en Log Analytics-arbetsyta i Azure Monitor från alla klienter som kan anropa ett REST-API. Klienten kan vara en runbook i Azure Automation som samlar in hanteringsdata från Azure eller ett annat moln, eller ett alternativt hanteringssystem som använder Azure Monitor för att konsolidera och analysera loggdata.

Alla data på Log Analytics-arbetsytan lagras som en post med en viss posttyp. Du formaterar dina data för att skicka till HTTP Data Collector API som flera poster i JavaScript Object Notation (JSON). När du skickar data skapas en enskild post på lagringsplatsen för varje post i nyttolasten för begäran.

Screenshot illustrating the HTTP Data Collector overview.

Skapa en begäran

Om du vill använda HTTP Data Collector-API:et skapar du en POST-begäran som innehåller de data som ska skickas i JSON. De följande tre tabellerna visar de attribut som krävs för varje begäran. Vi beskriver varje attribut mer detaljerat senare i artikeln.

URI för förfrågan

Attribut Property
Metod POST
URI <https:// CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01>
Content type application/json

Begär URI-parametrar

Parameter Beskrivning
CustomerID Den unika identifieraren för Log Analytics-arbetsytan.
Resurs API-resursnamnet: /api/logs.
API-version Den version av API:et som ska användas med den här begäran. För närvarande är versionen 2016-04-01.

Begärandehuvuden

Header Description
Auktorisering Auktoriseringssignaturen. Senare i artikeln kan du läsa om hur du skapar en HMAC-SHA256-rubrik.
Loggtyp Ange posttypen för de data som skickas. Den kan bara innehålla bokstäver, siffror och understreck (_) och får inte överstiga 100 tecken.
x-ms-date Det datum då begäran bearbetades i RFC 1123-format .
x-ms-AzureResourceId Resurs-ID för Azure-resursen som data ska associeras med. Den fyller i egenskapen _ResourceId och tillåter att data inkluderas i resurskontextfrågor . Om det här fältet inte anges inkluderas inte data i resurskontextfrågor.
time-generated-field Namnet på ett fält i data som innehåller tidsstämpeln för dataobjektet. Om du anger ett fält används dess innehåll för TimeGenerated. Om du inte anger det här fältet är standardvärdet för TimeGenerated den tid då meddelandet matas in. Innehållet i meddelandefältet ska följa ISO 8601-formatet YYYY-MM-DDThh:mm:ssZ. Det tidsgenererade värdet får inte vara äldre än 2 dagar innan det tas emot eller mer än en dag i framtiden. I sådana fall används den tid då meddelandet matas in.

Auktorisering

Alla förfrågningar till AZURE Monitor HTTP Data Collector API måste innehålla ett auktoriseringshuvud. Om du vill autentisera en begäran signerar du begäran med antingen den primära eller den sekundära nyckeln för arbetsytan som gör begäran. Skicka sedan signaturen som en del av begäran.

Här är formatet för auktoriseringshuvudet:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID är den unika identifieraren för Log Analytics-arbetsytan. Signaturen är en Hash-baserad kod för meddelandeautentisering (HMAC) som skapas från begäran och sedan beräknas med hjälp av SHA256-algoritmen. Sedan kodar du den med hjälp av Base64-kodning.

Använd det här formatet för att koda signatursträngen SharedKey :

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

Här är ett exempel på en signatursträng:

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

När du har signatursträngen kodar du den med hjälp av HMAC-SHA256-algoritmen på DEN UTF-8-kodade strängen och kodar sedan resultatet som Base64. Använd det här formatet:

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

Exemplen i nästa avsnitt har exempelkod som hjälper dig att skapa ett auktoriseringshuvud.

Begärandetext

Meddelandets brödtext måste finnas i JSON. Den måste innehålla en eller flera poster med egenskapsnamnet och värdeparen i följande format. Egenskapsnamnet får bara innehålla bokstäver, siffror och understreck (_).

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

Du kan gruppera flera poster i en enda begäran med hjälp av följande format. Alla poster måste vara av samma posttyp.

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

Posttyp och egenskaper

Du definierar en anpassad posttyp när du skickar data via AZURE Monitor HTTP Data Collector API. För närvarande kan du inte skriva data till befintliga posttyper som har skapats av andra datatyper och lösningar. Azure Monitor läser inkommande data och skapar sedan egenskaper som matchar datatyperna för de värden som du anger.

Varje begäran till API:et för datainsamlare måste innehålla ett log-type-huvud med namnet på posttypen. Suffixet _CL läggs automatiskt till i det namn du anger för att skilja det från andra loggtyper som en anpassad logg. Om du till exempel anger namnet MyNewRecordType skapar Azure Monitor en post med typen MyNewRecordType_CL. Detta säkerställer att det inte finns några konflikter mellan användarskapade typnamn och de som levereras i aktuella eller framtida Microsoft-lösningar.

För att identifiera en egenskaps datatyp lägger Azure Monitor till ett suffix i egenskapsnamnet. Om en egenskap innehåller ett null-värde inkluderas inte egenskapen i posten. I den här tabellen visas egenskapsdatatypen och motsvarande suffix:

Egenskapsdatatyp Suffix
String _S
Booleskt _B
Dubbel _D
Datum/tid _T
GUID (lagras som en sträng) _G

Kommentar

Strängvärden som verkar vara GUID får _g suffix och formateras som ett GUID, även om det inkommande värdet inte innehåller bindestreck. Till exempel både "8145d822-13a7-44ad-859c-36f31a84f6dd" och "8145d8213a744ad859c36f31a84f6dd" lagras som "8145d822-13a7-44ad-859c-36f31a84f6dd". De enda skillnaderna mellan den här och en annan sträng är _g i namnet och infogningen av bindestreck om de inte anges i indata.

Den datatyp som Azure Monitor använder för varje egenskap beror på om posttypen för den nya posten redan finns.

  • Om posttypen inte finns skapar Azure Monitor en ny med hjälp av JSON-typinferensen för att fastställa datatypen för varje egenskap för den nya posten.
  • Om posttypen finns försöker Azure Monitor skapa en ny post baserat på befintliga egenskaper. Om datatypen för en egenskap i den nya posten inte matchar och inte kan konverteras till den befintliga typen, eller om posten innehåller en egenskap som inte finns, skapar Azure Monitor en ny egenskap som har relevant suffix.

Följande överföringspost skulle till exempel skapa en post med tre egenskaper, number_d, boolean_b och string_s:

Screenshot of sample record 1.

Om du skulle skicka nästa post, med alla värden formaterade som strängar, skulle egenskaperna inte ändras. Du kan konvertera värdena till befintliga datatyper.

Screenshot of sample record 2.

Men om du gör nästa inlämning skapar Azure Monitor de nya egenskaperna boolean_d och string_d. Du kan inte konvertera dessa värden.

Screenshot of sample record 3.

Om du sedan skickar följande post, innan posttypen skapas, skapar Azure Monitor en post med tre egenskaper, number_s, boolean_s och string_s. I den här posten formateras vart och ett av de första värdena som en sträng:

Screenshot of sample record 4.

Reserverade egenskaper

Följande egenskaper är reserverade och bör inte användas i en anpassad posttyp. Du får ett felmeddelande om nyttolasten innehåller något av följande egenskapsnamn:

  • tenant
  • TimeGenerated
  • RawData

Databegränsningar

De data som publiceras i API:et för Insamling av Azure Monitor-data omfattas av vissa begränsningar:

  • Högst 30 MB per post till Azure Monitor Data Collector API. Det här är en storleksgräns för ett enda inlägg. Om data från ett enda inlägg överskrider 30 MB bör du dela upp data i mindre segment och skicka dem samtidigt.
  • Maximalt 32 KB för fältvärden. Om fältvärdet är större än 32 kB kommer data att trunkeras.
  • Rekommenderas högst 50 fält för en viss typ. Detta är en praktisk gräns med tanke på användbarhet och sökfunktion.
  • Tabeller i Log Analytics-arbetsytor stöder endast upp till 500 kolumner (kallas fält i den här artikeln).
  • Högst 45 tecken för kolumnnamn.

Returkoder

HTTP-statuskoden 200 innebär att begäran har tagits emot för bearbetning. Detta indikerar att åtgärden har slutförts.

Den fullständiga uppsättningen statuskoder som tjänsten kan returnera visas i följande tabell:

Kod Status Felkod Description
200 OK Begäran har godkänts.
400 Felaktig begäran InactiveCustomer Arbetsytan har stängts.
400 Felaktig begäran InvalidApiVersion Den API-version som du angav kändes inte igen av tjänsten.
400 Felaktig begäran InvalidCustomerId Det angivna arbetsyte-ID:t är ogiltigt.
400 Felaktig begäran InvalidDataFormat En ogiltig JSON skickades. Svarstexten kan innehålla mer information om hur du löser felet.
400 Felaktig begäran InvalidLogType Den angivna loggtypen innehöll specialtecken eller numeriska tecken.
400 Felaktig begäran MissingApiVersion API-versionen har inte angetts.
400 Felaktig begäran MissingContentType Innehållstypen har inte angetts.
400 Felaktig begäran MissingLogType Den nödvändiga värdeloggtypen har inte angetts.
400 Felaktig begäran UnsupportedContentType Innehållstypen har inte angetts till application/json.
403 Ej tillåtet InvalidAuthorization Tjänsten kunde inte autentisera begäran. Kontrollera att arbetsytans ID och anslutningsnyckel är giltiga.
404 Hittades inte Antingen är den angivna URL:en felaktig eller så är begäran för stor.
429 För många begäranden Tjänsten har en stor mängd data från ditt konto. Försök igen senare.
500 Internt serverfel UnspecifiedError Tjänsten påträffade ett internt fel. Försök igen.
503 Tjänsten är inte tillgänglig ServiceUnavailable Tjänsten är för närvarande inte tillgänglig för att ta emot begäranden. Försök igen.

Fråga efter data

Om du vill köra frågor mot data som skickas av AZURE Monitor HTTP Data Collector-API:et söker du efter poster vars typ är lika med det LogType-värde som du angav och lade till med _CL. Om du till exempel använde MyCustomLog skulle du returnera alla poster med MyCustomLog_CL.

Exempelbegäranden

I det här avsnittet finns exempel som visar hur du skickar data till AZURE Monitor HTTP Data Collector API med hjälp av olika programmeringsspråk.

För varje exempel anger du variablerna för auktoriseringshuvudet genom att göra följande:

  1. Leta upp din Log Analytics-arbetsyta i Azure-portalen.
  2. Välj Agenter.
  3. Till höger om Arbetsyte-ID väljer du ikonen Kopiera och klistrar sedan in ID:t som värde för variabeln Kund-ID .
  4. Till höger om Primärnyckel väljer du ikonen Kopiera och klistrar sedan in ID:t som värdet för variabeln Delad nyckel.

Du kan också ändra variablerna för loggtypen och JSON-data.

# 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  

Alternativ och överväganden

Även om API:et för datainsamlare bör täcka de flesta av dina behov när du samlar in kostnadsfria data i Azure-loggar, kan du behöva en alternativ metod för att övervinna några av begränsningarna i API:et. Dina alternativ, inklusive viktiga överväganden, visas i följande tabell:

Alternativ Description Passar bäst för
Anpassade händelser: Intern SDK-baserad inmatning i Application Insights Application Insights, som vanligtvis instrumenteras via ett SDK i ditt program, ger dig möjlighet att skicka anpassade data via anpassade händelser.
  • Data som genereras i ditt program, men som inte hämtas av SDK:et via någon av standarddatatyperna (begäranden, beroenden, undantag och så vidare).
  • Data som oftast korreleras med andra programdata i Application Insights.
API för datainsamlare i Azure Monitor-loggar API:et för datainsamlare i Azure Monitor-loggar är ett helt öppet sätt att mata in data. Alla data som är formaterade i ett JSON-objekt kan skickas här. När den har skickats bearbetas den och görs tillgänglig i Övervakningsloggar för att korreleras med andra data i Övervakningsloggar eller mot andra Application Insights-data.

Det är ganska enkelt att ladda upp data som filer till en Azure Blob Storage-blob, där filerna bearbetas och sedan laddas upp till Log Analytics. En exempelimplementering finns i Skapa en datapipeline med API:et datainsamlare.
  • Data som inte nödvändigtvis genereras i ett program som instrumenteras i Application Insights.
    Exempel är uppslags- och faktatabeller, referensdata, föraggregerad statistik och så vidare.
  • Data som korsreferenseras mot andra Azure Monitor-data (Application Insights, andra datatyper för övervakningsloggar, Defender för molnet, containerinsikter och virtuella datorer och så vidare).
Azure-datautforskaren Azure Data Explorer, som nu är allmänt tillgängligt för allmänheten, är den dataplattform som driver Application Insights Analytics och Azure Monitor-loggar. Genom att använda dataplattformen i dess råa form har du fullständig flexibilitet (men kräver hanteringskostnaderna) över klustret (Rollbaserad åtkomstkontroll i Kubernetes (RBAC), kvarhållningshastighet, schema och så vidare). Azure Data Explorer innehåller många inmatningsalternativ, inklusive CSV-, TSV- och JSON-filer .
  • Data som inte korreleras med andra data under Application Insights eller Övervaka loggar.
  • Data som kräver avancerade inmatnings- eller bearbetningsfunktioner som inte är tillgängliga i dag i Azure Monitor-loggar.

Nästa steg

  • Använd LOG Search-API:et för att hämta data från Log Analytics-arbetsytan.

  • Läs mer om hur du skapar en datapipeline med API :et datainsamlare med hjälp av ett Logic Apps-arbetsflöde till Azure Monitor.