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.
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
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:
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.
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.
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:
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_CL
rekordot.
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:
- Az Azure Portalon keresse meg a Log Analytics-munkaterületet.
- Válassza a ügynököket.
- 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.
- 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. |
|
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. |
|
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. |
|
Következő lépések
- A Log Search API használatával adatokat kér le a Log Analytics-munkaterületről.
- További információ arról, hogyan létrehozni egy adatfolyamot a Data Collector API- egy Logic Apps-munkafolyamattal az Azure Monitorban.