Megosztás a következőn keresztül:


Naplóadatok küldése az Azure Monitorba a HTTP Data Collector API használatával (elavult)

Ez a cikk bemutatja, hogyan küldhet naplóadatokat a HTTP Data Collector API-val egy REST API-ügyfélről az Azure Monitorba. Leírja, hogyan formázhatja a szkript vagy alkalmazás által gyűjtött adatokat, hogyan csatolhatja azokat egy kérelembe, és hogyan rendelkezhet az Azure Monitor által engedélyezett kéréssel. Példákat mutatunk be az Azure PowerShellre, a C#-ra és a Pythonra.

Jegyzet

Az Azure Monitor HTTP Data Collector API elavult, és 2026. 09. 14-én már nem fog működni. A Logs ingestion APIváltotta fel.

Fogalmak

A HTTP Data Collector API használatával naplóadatokat küldhet egy Log Analytics-munkaterületre az Azure Monitorban bármely olyan ügyféltől, amely meghívhat EGY REST API-t. Az ügyfél lehet egy runbook az Azure Automationben, amely felügyeleti adatokat gyűjt az Azure-ból vagy egy másik felhőből, vagy egy alternatív felügyeleti rendszer, amely az Azure Monitort használja a naplóadatok konszolidálására és elemzésére.

A Log Analytics-munkaterület összes adata egy adott rekordtípusú rekordként van tárolva. Az adatokat úgy formázza, hogy a HTTP Data Collector API-nak több rekordként küldje el a JavaScript Object Notation (JSON) alkalmazásban. Az adatok elküldésekor a kérelem hasznos adatainak minden egyes rekordjához külön rekord jön létre az adattárban.

A HTTP-adatgyűjtő áttekintését bemutató képernyőkép.

Kérés létrehozása

A HTTP Data Collector API használatához létre kell hoznia egy POST-kérést, amely tartalmazza a JSON-ban küldendő adatokat. A következő három tábla felsorolja az egyes kérésekhez szükséges attribútumokat. A cikk későbbi részében részletesebben ismertetjük az egyes attribútumokat.

URI kérése

Attribútum Ingatlan
Módszer poszt
URI https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Tartalomtípus alkalmazás/json

URI-paraméterek kérése

Paraméter Leírás
Ügyfélazonosító A Log Analytics-munkaterület egyedi azonosítója.
Erőforrás Az API-erőforrás neve: /api/logs.
API-verzió A kéréshez használni kívánt API verziója. A verzió jelenleg 2016-04-01.

Kérelemfejlécek

Fejléc Leírás
Felhatalmazás Az engedélyezési aláírás. A cikk későbbi részében olvashat arról, hogyan hozhat létre HMAC-SHA256 fejlécet.
Log-Type Adja meg a beküldött adatok rekordtípusát. Csak betűket, számokat és aláhúzásjelet (_) tartalmazhat, és nem haladhatja meg a 100 karaktert.
x-ms-date A kérelem feldolgozásának dátuma RFC 1123 formátumban.
x-ms-AzureResourceId Annak az Azure-erőforrásnak az erőforrás-azonosítója, amelyhez az adatokat társítani kell. Feltölti a _ResourceId tulajdonságot, és lehetővé teszi az adatok erőforrás-környezet lekérdezésekbe való belefoglalását. Ha ez a mező nincs megadva, az adatok nem lesznek belefoglalva az erőforrás-környezet lekérdezéseibe.
idő-alapú-mező Az adatelem időbélyegét tartalmazó adatmező neve. Ha megad egy mezőt, annak tartalma a TimeGeneratedszámára használatos. Ha nem adja meg ezt a mezőt, akkor a TimeGenerated alapértelmezett beállítása az üzenet beérkezésének időpontja lesz. Az üzenetmező tartalmának az ISO 8601 YYYY-MM-DDThh:mm:ssZ formátumot kell követnie. Az idő generált értéke nem lehet 2 napnál régebbi a beérkezés előtt, vagy egy napnál hosszabb a jövőben. Ilyen esetben a rendszer az üzenet betöltésének idejét fogja használni.

Felhatalmazás

Az Azure Monitor HTTP Data Collector API-nak küldött kérésnek tartalmaznia kell egy engedélyezési fejlécet. A kérés hitelesítéséhez írja alá a kérést a kérést készítő munkaterület elsődleges vagy másodlagos kulcsával. Ezután adja át az aláírást a kérés részeként.

Az engedélyezési fejléc formátuma a következő:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID a Log Analytics-munkaterület egyedi azonosítója. aláírás egy kivonatalapú üzenethitelesítési kód (HMAC), amelyet a kérésből állítanak elő, majd az SHA256 algoritmussegítségével számítanak ki. Ezt követően Base64 kódolással kódolhatja.

Ezzel a formátummal kódolhatja a SharedKey aláírási sztringet:

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

Íme egy példa egy aláírási karakterláncra:

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

Amikor megvan az aláírási sztring, először kódolja a sztringet UTF-8 formátumba, majd alkalmazza a HMAC-SHA256 algoritmust, és végül az eredményt Base64 formátumban kódolja. Használja ezt a formátumot:

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

A következő szakaszokban szereplő minták mintakódokkal rendelkeznek, amelyek segítenek létrehozni egy engedélyezési fejlécet.

Kérelem törzse

Az üzenet törzsének JSON-ban kell lennie. Tartalmaznia kell egy vagy több rekordot a tulajdonságnévvel és értékpárokkal a következő formátumban. A tulajdonságnév csak betűket, számokat és aláhúzásjelet (_) tartalmazhat.

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

Több rekordot is egy kérésben kötegelhet az alábbi formátum használatával. Minden rekordnak azonos típusúnak kell lennie.

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

Rekord típusa és tulajdonságai

Egyéni rekordtípust határoz meg, amikor adatokat küld az Azure Monitor HTTP Data Collector API-val. Jelenleg nem írhat adatokat olyan meglévő rekordtípusokba, amelyeket más adattípusok és megoldások hoztak létre. Az Azure Monitor beolvassa a bejövő adatokat, majd létrehozza a megadott értékek adattípusainak megfelelő tulajdonságokat.

A Data Collector API-nak küldött minden kérésnek tartalmaznia kell egy naplótípusú fejlécet a rekordtípus nevével. A _CL utótagot a rendszer automatikusan hozzáfűzi a megadott névhez, hogy megkülönböztesse a többi naplótípustól egyéni naplóként. Ha például a MyNewRecordTypenevet adja meg , az Azure Monitor létrehoz egy rekordot MyNewRecordType_CLtípussal. Ez segít biztosítani, hogy ne legyenek ütközések a felhasználó által létrehozott típusnevek és az aktuális vagy jövőbeli Microsoft-megoldásokban szállított nevek között.

Egy tulajdonság adattípusának azonosításához az Azure Monitor hozzáad egy utótagot a tulajdonság nevéhez. Ha egy tulajdonság null értéket tartalmaz, a tulajdonság nem szerepel a rekordban. Ez a táblázat a tulajdonság adattípusát és a megfelelő utótagot sorolja fel:

Tulajdonság adattípusa Toldalék
Húr _s
Logikai érték _b
Dupla _d
Dátum/idő _t
GUID (sztringként tárolva) _g

Jegyzet

A GUID-nak tűnő karakterláncértékek a _g utótagot kapják, és GUID formátumba vannak alakítva, még akkor is, ha a bejövő érték nem tartalmaz kötőjeleket. Például mind a "8145d822-13a7-44ad-859c-36f31a84f6dd", mind pedig a "8145d82213a744ad859c36f31a84f6dd" a következő formátumban van tárolva: "8145d822-13a7-44ad-859c-36f31a84f6dd". Az egyetlen különbség e sztring és egy másik között a névben szereplő _g, valamint kötőjelek hozzáadása, ha nincsenek megadva a bemenetben.

Az Azure Monitor által az egyes tulajdonságokhoz használt adattípus attól függ, hogy az új rekord rekordtípusa már létezik-e.

  • Ha a rekordtípus nem létezik, az Azure Monitor létrehoz egy újat a JSON-típus következtetésével az új rekord egyes tulajdonságainak adattípusának meghatározásához.
  • Ha a rekordtípus létezik, az Azure Monitor új rekordot próbál létrehozni a meglévő tulajdonságok alapján. Ha az új rekord egyik tulajdonságának adattípusa nem egyezik meg, és nem konvertálható a meglévő típusra, vagy ha a rekord tartalmaz egy nem létező tulajdonságot, az Azure Monitor létrehoz egy új tulajdonságot, amely a megfelelő utótagot tartalmazza.

A következő beküldési bejegyzés például három tulajdonsággal, number_d, boolean_bés string_srendelkező rekordot hozna létre:

1. mintarekord képernyőképe.

Ha ezt a következő bejegyzést szeretné elküldeni, és az összes érték sztringként van formázva, a tulajdonságok nem változnak. Az értékeket meglévő adattípusokká alakíthatja.

2. mintarekord képernyőképe.

Ha azonban ezt a következő beküldést teszi, az Azure Monitor létrehozza az új tulajdonságokat boolean_d és string_d. Ezeket az értékeket nem konvertálhatja.

3. mintarekord képernyőképe.

Ha ezután elküldi a következő bejegyzést, a rekordtípus létrehozása előtt az Azure Monitor létrehoz egy rekordot három tulajdonságokkal, number_s, boolean_sés string_s. Ebben a bejegyzésben a kezdeti értékek sztringként lesznek formázva:

4. mintarekord képernyőképe.

Fenntartott tulajdonságok

A következő tulajdonságok fenntartottak, és nem használhatók egyéni rekordtípusban. Hibaüzenetet kap, ha a payload az alábbi tulajdonságneveket tartalmazza:

  • bérlő
  • TimeGenerated
  • RawData

Adatkorlátok

Az Azure Monitor adatgyűjtési API-nak közzétett adatokra bizonyos korlátozások vonatkoznak:

  • Legfeljebb 30 MB feltöltésenként az Azure Monitor Data Collector API-ba. Ez egy bejegyzés méretkorlátja. Ha egy bejegyzés adatai nagyobbak, mint 30 MB, akkor az adatokat kisebb méretű adattömbökre kell felosztani, és egyidejűleg elküldeni őket.
  • Mezőértékek esetén legfeljebb 32 KB. Ha a mező értéke nagyobb, mint 32 KB, a rendszer csonkolja az adatokat.
  • Egy adott típushoz legfeljebb 50 mező ajánlott. Ez gyakorlati korlát a használhatóság és a keresési élmény szempontjából.
  • A Log Analytics-munkaterületeken lévő táblák legfeljebb 500 oszlopot támogatnak (a jelen cikk mezőinek is nevezik).
  • Oszlopnevek legfeljebb 45 karakter hosszúságúak.

Visszatérési kódok

A HTTP-állapotkód 200 azt jelenti, hogy a kérés feldolgozásra érkezett. Ez azt jelzi, hogy a művelet sikeresen befejeződött.

A szolgáltatás által visszaadható állapotkódok teljes készlete az alábbi táblázatban található:

Kód Állapot Hibakód Leírás
200 OKÉ A kérést sikeresen elfogadták.
400 Hibás kérés inaktív ügyfél A munkaterület bezárult.
400 Hibás kérés ÉrvénytelenApiVerzió A megadott API-verziót a szolgáltatás nem ismerte fel.
400 Hibás kérés ÉrvénytelenÜgyfélAzonosító A megadott munkaterület-azonosító érvénytelen.
400 Hibás kérés ÉrvénytelenAdatFormátum Érvénytelen JSON lett elküldve. A válasz törzse további információkat tartalmazhat a hiba megoldásáról.
400 Hibás kérés ÉrvénytelenNaplóTípus A megadott naplótípus speciális karaktereket vagy számokat tartalmazott.
400 Hibás kérés MissingApiVersion Az API-verzió nincs megadva.
400 Hibás kérés MissingContentType A tartalomtípus nincs megadva.
400 Hibás kérés HiányzóNaplóTípus A szükséges értéknapló-típus nincs megadva.
400 Hibás kérés Nem támogatott tartalomtípus A tartalomtípust nem sikerült beállítani a(z) alkalmazás/jsonértékhez.
403 Tiltott Érvénytelen engedélyezés A szolgáltatás nem tudta hitelesíteni a kérést. Ellenőrizze, hogy a munkaterület azonosítója és a kapcsolatkulcs érvényes-e.
404 Nem található A megadott URL-cím helytelen, vagy a kérés túl nagy.
429 Túl sok kérés A szolgáltatás nagy mennyiségű adatot tapasztal a fiókjából. Később próbálkozzon újra a kéréssel.
500 Belső kiszolgálóhiba Nem meghatározott hiba A szolgáltatás belső hibát észlelt. Próbálkozzon újra a kéréssel.
503 A szolgáltatás nem érhető el Szolgáltatás nem elérhető A szolgáltatás jelenleg nem érhető el a kérések fogadásához. Próbálkozzon újra a kéréssel.

Adatok lekérdezése

Az Azure Monitor HTTP Data Collector API által beküldött adatok lekérdezéséhez keressen olyan rekordokat, amelyeknek a Típus megegyezik azzal a LogType értékkel, amelyet Ön adott meg, és amelyhez a _CLhozzá lett fűzve. Például, ha a MyCustomLog-t használta volna, visszakapná az összes MyCustomLog_CLrekordot.

Mintakérések

Ebben a szakaszban olyan minták találhatók, amelyek bemutatják, hogyan küldhet adatokat az Azure Monitor HTTP Data Collector API-nak különböző programozási nyelvek használatával.

Minden minta esetében állítsa be az engedélyezési fejléc változóit az alábbi lépésekkel:

  1. Az Azure Portalon keresse meg a Log Analytics-munkaterületet.
  2. Válassza a ügynököket.
  3. A Munkaterület-azonosítójobb oldalán válassza a Másolás ikont, majd illessze be az azonosítót az Ügyfélazonosító változó értékeként.
  4. Az elsődleges kulcsjobb oldalán válassza az Másolás ikont, majd illessze be az azonosítót az megosztott kulcs változó értékeként.

Másik lehetőségként módosíthatja a naplótípus és a JSON-adatok változóit.

# 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  

Alternatívák és szempontok

Bár a Data Collector API-nak a legtöbb igényét ki kell elégítenie, amikor szabad formátumú adatokat gyűjt az Azure-naplókba, alternatív megközelítésre lehet szükség az API bizonyos korlátainak leküzdéséhez. A lehetőségek, beleértve a főbb szempontokat, az alábbi táblázatban találhatók:

Alternatíva Leírás Leginkább alkalmas valamire
egyéni események: Natív SDK-alapú betöltés az Application Insightsban Az Application Insights, amely általában az alkalmazás SDK-ján keresztül van kialakítva, lehetővé teszi egyéni adatok egyéni eseményeken keresztüli küldését.
  • Az alkalmazásban létrehozott, de az SDK által nem felvett adatok az alapértelmezett adattípusok (kérések, függőségek, kivételek stb.) egyikén keresztül.
  • Az Application Insights más alkalmazásadataival leggyakrabban korrelált adatok.
Data Collector API az Azure Monitor-naplókban Az Azure Monitor-naplók Data Collector API-ja teljesen nyitott módszer az adatok betöltésére. A JSON-objektumban formázott adatok elküldhetők ide. Az elküldése után a rendszer feldolgozja és elérhetővé teszi a Monitornaplókban, hogy korreláljon a monitornaplókban szereplő más adatokkal vagy más Application Insights-adatokkal.

Elég egyszerű fájlként feltölteni az adatokat egy Azure Blob Storage-blobba, ahol a fájlokat feldolgozzák, majd feltöltik a Log Analyticsbe. A minta implementációért lásd: Adatfolyam létrehozása a Data Collector API-val.
  • Olyan adatok, amelyek nem feltétlenül jönnek létre az Application Insightsban rendszerezett alkalmazásokban.
    Ilyenek például a keresési és ténytáblák, a referenciaadatok, az előre összeállított statisztikák stb.
  • Más Azure Monitor-adatokkal (Application Insights, egyéb monitornaplók adattípusai, a Defender for Cloud, a Container Insights és a virtuális gépek stb.) összevetett adatok.
Azure Data Explorer Az Azure Data Explorer, amely most már általánosan elérhető a nyilvánosság számára, az Application Insights Analytics és az Azure Monitor naplóit kezelő adatplatform. Az adatplatform nyers formában való használatával teljes rugalmasságot biztosít (de a felügyelet többletterhelését igényli) a fürt felett (Kubernetes szerepköralapú hozzáférés-vezérlés (RBAC), megőrzési arány, séma stb. Az Azure Data Explorer számos betöltési lehetőséget biztosít, például CSV-, TSV- és JSON- fájlokat.
  • Azok az adatok, amelyek nem lesznek korrelálva más adatokkal az Application Insights vagy a Monitor-naplók területen.
  • Olyan adatok, amelyek speciális betöltési vagy feldolgozási képességeket igényelnek, amelyek jelenleg nem érhetők el az Azure Monitor-naplókban.

Következő lépések