Dela via

Loggar inmatnings-API i Azure Monitor

  • Artikel

Med API för logginmatning i Azure Monitor kan du skicka data till en Log Analytics-arbetsyta med antingen ett REST API-anrop eller klientbibliotek. Med API:et kan du skicka data till Azure-tabeller som stöds eller till anpassade tabeller som du skapar. Du kan också utöka schemat för Azure-tabeller med anpassade kolumner för att acceptera ytterligare data.

Grundläggande åtgärd

Data kan skickas till LOGS Ingestion API från alla program som kan göra ett REST API-anrop. Detta kan vara ett anpassat program som du skapar, eller så kan det vara ett program eller en agent som förstår hur du skickar data till API:et. Den anger en datainsamlingsregel (DCR) som innehåller måltabellen och arbetsytan och autentiseringsuppgifterna för en appregistrering med åtkomst till den angivna DOMÄNKONTROLLanten. Den skickar data till en slutpunkt som anges av DCR eller till en datainsamlingsslutpunkt (DCE) om du använder en privat länk.

De data som skickas av ditt program till API:et måste formateras i JSON och matcha den struktur som förväntas av DCR. Det behöver inte nödvändigtvis matcha måltabellens struktur eftersom DCR kan innehålla en transformering för att konvertera data så att de matchar tabellens struktur. Du kan ändra måltabellen och arbetsytan genom att ändra DCR utan att ändra API-anropet eller källdata.

Diagram som visar en översikt över API för logginmatning.

Konfiguration

I följande tabell beskrivs varje komponent i Azure som du måste konfigurera innan du kan använda API:et För inmatning av loggar.

Kommentar

Ett PowerShell-skript som automatiserar konfigurationen av dessa komponenter finns i Exempelkod för att skicka data till Azure Monitor med hjälp av Logs-inmatnings-API.

Komponent Funktion
Appregistrering och hemlighet Programregistreringen används för att autentisera API-anropet. Den måste beviljas behörighet till dcr som beskrivs nedan. API-anropet innehåller programmets program-ID (klient- och katalog-ID) och värdet för en programhemlighet.

Se Skapa ett Microsoft Entra-program och tjänstens huvudnamn som kan komma åt resurser och Skapa en ny programhemlighet.
Tabell i Log Analytics-arbetsytan Tabellen på Log Analytics-arbetsytan måste finnas innan du kan skicka data till den. Du kan använda en av de Azure-tabeller som stöds eller skapa en anpassad tabell med någon av de tillgängliga metoderna. Om du använder Azure Portal för att skapa tabellen skapas domänkontrollanten åt dig, inklusive en transformering om det behövs. Med andra metoder måste du skapa DCR manuellt enligt beskrivningen i nästa avsnitt.

Se Skapa en anpassad tabell.
Datainsamlingsregel (DCR) Azure Monitor använder datainsamlingsregeln (DCR) för att förstå strukturen för inkommande data och vad du ska göra med dem. Om tabellens struktur och inkommande data inte matchar kan DCR innehålla en transformering för att konvertera källdata så att de matchar måltabellen. Du kan också använda omvandlingen för att filtrera källdata och utföra andra beräkningar eller konverteringar.

Om du skapar en anpassad tabell med hjälp av Azure Portal skapas DCR och omvandlingen åt dig baserat på exempeldata som du anger. Om du använder en befintlig tabell eller skapar en anpassad tabell med en annan metod måste du manuellt skapa DCR med hjälp av information i följande avsnitt.

När domänkontrollanten har skapats måste du bevilja åtkomst till den för det program som du skapade i det första steget. På menyn Övervaka i Azure Portal väljer du Regler för datainsamling och sedan den DCR som du skapade. Välj Åtkomstkontroll (IAM) för DCR och välj sedan Lägg till rolltilldelning för att lägga till utgivarrollen Övervakningsmått.

Slutpunkt

REST API-slutpunkten för LOGS Ingestion API kan antingen vara en slutpunkt för datainsamling (DCE) eller DCR-loggarnas inmatningsslutpunkt.

DCR-loggarnas inmatningsslutpunkt genereras när du skapar en DCR för direkt inmatning. Om du vill hämta den här slutpunkten öppnar du DCR i JSON-vyn i Azure Portal. Du kan behöva ändra API-versionen till den senaste versionen för att slutpunkterna ska visas.

Skärmbild som visar slutpunkten för logginmatning i en DCR.

En DOMÄNKONTROLLant krävs bara när du ansluter till en Log Analytics-arbetsyta med hjälp av en privat länk eller om domänkontrollanten inte innehåller slutpunkten för logginmatning. Detta kan vara fallet om du använder en äldre DCR eller om du skapade DCR utan parametern "kind": "Direct" . Mer information finns i Regeln för datainsamling (DCR) nedan.

Kommentar

Fastigheten logsIngestion lades till den 31 mars 2024. Före det här datumet krävdes en DCE för API:et för logginmatning. Slutpunkter kan inte läggas till i en befintlig domänkontrollant, men du kan fortsätta att använda befintliga domänkontrollanter med befintliga domänkontrollanter. Om du vill flytta till en DCR-slutpunkt måste du skapa en ny DCR för att ersätta den befintliga. En DCR med slutpunkter kan också använda en DCE. I det här fallet kan du välja om du vill använda DCE- eller DCR-slutpunkterna för var och en av klienterna som använder DCR.

Datainsamlingsregel (DCR)

När du skapar en anpassad tabell på en Log Analytics-arbetsyta med hjälp av Azure Portal skapas en DCR som kan användas med API:et för logginmatning åt dig. Om du skickar data till en tabell som redan finns måste du skapa DCR manuellt. Börja med dcr-exemplet nedan och ersätt värden för följande parametrar i mallen. Använd någon av metoderna som beskrivs i Skapa och redigera regler för datainsamling (DCR) i Azure Monitor för att skapa DCR.

Parameter Description
region Region för att skapa din DCR. Detta måste matcha regionen för Log Analytics-arbetsytan och DCE om du använder en.
dataCollectionEndpointId Resurs-ID för din DCE. Ta bort den här parametern om du använder DCR-inmatningspunkten.
streamDeclarations Ändra kolumnlistan till kolumnerna i dina inkommande data. Du behöver inte ändra namnet på strömmen eftersom det bara behöver matcha streams namnet i dataFlows.
workspaceResourceId Resurs-ID för din Log Analytics-arbetsyta. Du behöver inte ändra namnet eftersom det bara behöver matcha destinations namnet i dataFlows.
transformKql KQL-fråga som ska tillämpas på inkommande data. Om schemat för inkommande data matchar schemat för tabellen kan du använda source för omvandlingen som skickar inkommande data oförändrade. Annars använder du en fråga som transformerar data för att matcha måltabellschemat.
outputStream Namnet på tabellen som ska skicka data. Lägg till prefixet Custom-table-name<> för en anpassad tabell. För en inbyggd tabell lägger du till prefixet Microsoft-table-name><. 
{
    "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"
            }
        ]
    }
}

Klientbibliotek

Förutom att göra ett REST API-anrop kan du använda följande klientbibliotek för att skicka data till API:et för logginmatning. Biblioteken kräver samma komponenter som beskrivs i Konfiguration. Exempel på hur du använder vart och ett av dessa bibliotek finns i Exempelkod för att skicka data till Azure Monitor med hjälp av API för logginmatning.

REST API-anrop

Om du vill skicka data till Azure Monitor med ett REST API-anrop gör du ett POST-anrop via HTTP. Information som krävs för det här anropet beskrivs i det här avsnittet.

URI

URI:n innehåller regionen, DCE- eller DCR-inmatningsslutpunkten, DCR-ID:t och strömnamnet. Den anger även API-versionen.

URI:n använder följande format.

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

Till exempel:

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

DCR Immutable ID Genereras för DCR när den skapas. Du kan hämta den från översiktssidan för DCR i Azure Portal.

Skärmbild av en datainsamlingsregel som visar det oföränderliga ID:t.

Stream Namerefererar till strömmen i DCR som ska hantera anpassade data.

Sidhuvuden

I följande tabell beskrivs rubrikerna för DITT API-anrop.

Header Obligatoriskt? beskrivning
Auktorisering Ja Ägartoken som hämtas via flödet för klientautentiseringsuppgifter. Använd tokenmålgruppens värde för ditt moln:

Offentligt Azure-moln – https://monitor.azure.com
Microsoft Azure drivs av 21Vianet-molnet – https://monitor.azure.cn
Azure US Government-moln – https://monitor.azure.us
Innehållstyp Ja application/json
Content-Encoding Nej gzip
x-ms-client-request-id Nej Strängformaterat GUID. Det här är ett begärande-ID som kan användas av Microsoft i alla felsökningssyften.

Brödtext

Anropets brödtext innehåller anpassade data som ska skickas till Azure Monitor. Dataformen måste vara en JSON-matris med objektstruktur som matchar det format som förväntas av dataströmmen i DCR. Om det behövs för att skicka ett enskilt objekt i API-anropet ska data skickas som en matris med ett objekt.

Till exempel:

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

Se till att begärandetexten är korrekt kodad i UTF-8 för att förhindra problem med dataöverföring.

Exempel

Se Exempelkod för att skicka data till Azure Monitor med logginmatnings-API för ett exempel på API-anropet med Hjälp av PowerShell.

Tabeller som stöds

Data som skickas till inmatnings-API:et kan skickas till följande tabeller:

Tabeller beskrivning
Anpassade tabeller Alla anpassade tabeller som du skapar på Log Analytics-arbetsytan. Måltabellen måste finnas innan du kan skicka data till den. Anpassade tabeller måste ha suffixet _CL .
Azure-tabeller Följande Azure-tabeller stöds för närvarande. Andra tabeller kan läggas till i den här listan när stöd för dem implementeras.

Kommentar

Kolumnnamn måste börja med en bokstav och kan bestå av upp till 45 alfanumeriska tecken och understreck (_). _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, , UniqueIdoch Title är reserverade kolumnnamn. Anpassade kolumner som du lägger till i en Azure-tabell måste ha suffixet _CF.

Gränser och begränsningar

Begränsningar som rör API :et för logginmatning finns i Tjänstbegränsningar för Azure Monitor.

Nästa steg