Condividi tramite

API di inserimento dei log in Monitoraggio di Azure

  • Articolo

L'API di inserimento dei log in Monitoraggio di Azure consente di inviare dati a un'area di lavoro Log Analytics tramite una chiamata API REST o librerie client. L'API consente di inviare dati alle tabelle di Azure supportate o alle tabelle personalizzate create dall'utente. È anche possibile estendere lo schema delle tabelle di Azure con colonne personalizzate per accettare dati aggiuntivi.

Operazione di base

I dati possono essere inviati all'API di inserimento dei log da qualsiasi applicazione in grado di effettuare una chiamata API REST. Potrebbe trattarsi di un'applicazione personalizzata creata dall'utente o di un'applicazione o agente in grado di inviare dati all'API. Specifica una regola di raccolta dati (DCR) che include la tabella e l'area di lavoro di destinazione e le credenziali di registrazione di un'applicazione con accesso alla DCR specificata. Invia i dati a un endpoint specificato dalla DCR o a un endpoint di raccolta dati (DCE) se si usa un collegamento privato.

I dati inviati dall'applicazione all'API devono essere formattati in JSON e corrispondere alla struttura prevista dalla DCR. Non deve necessariamente corrispondere alla struttura della tabella di destinazione, perché la DCR può includere una trasformazione per convertire i dati in modo che corrispondano alla struttura della tabella. È possibile modificare la tabella di destinazione e l'area di lavoro modificando la DCR senza apportare alcuna modifica alla chiamata API o ai dati di origine.

Diagramma che mostra una panoramica dell'API di inserimento dei log.

Impostazione

Nella tabella seguente viene descritto ogni componente di Azure che è necessario configurare prima di poter usare l'API di inserimento dei log.

Nota

Per uno script di PowerShell che automatizza la configurazione di questi componenti, vedere Codice di esempio per l'invio di dati a Monitoraggio di Azure tramite l'API di inserimento dei log.

Componente Funzione
Registrazione dell'app e segreto La registrazione dell'applicazione viene usata per autenticare la chiamata API. Deve essere concessa l'autorizzazione alla DCR descritta di seguito. La chiamata API include l'ID applicazione (client) e l'ID della directory (tenant) dell'applicazione e il Valore di un segreto dell'applicazione.

Vedere Creare un'applicazione Microsoft Entra e un'entità servizio in grado di accedere alle risorse e Creare un nuovo segreto dell'applicazione.
Tabella nell'area di lavoro Log Analytics La tabella nell'area di lavoro di Log Analytics deve esistere prima di potervi inviare i dati. È possibile usare una delle tabelle di Azure supportate o creare una tabella personalizzata usando uno dei metodi disponibili. Se si usa il portale di Azure per creare la tabella, viene creato automaticamente la DCR, inclusa una trasformazione, se necessario. Con qualsiasi altro metodo, è necessario creare manualmente la DCR come descritto nella sezione successiva.

Vedere Creare una tabella personalizzata.
Regola di raccolta dati (DCR) Monitoraggio di Azure usa la regola di raccolta dati (DCR) per comprendere la struttura dei dati in ingresso e come usarli. Se la struttura della tabella e i dati in ingresso non corrispondono, la DCR può includere una trasformazione per convertire i dati di origine in modo che corrispondano alla tabella di destinazione. È inoltre possibile usare la trasformazione per filtrare i dati di origine ed eseguire altri calcoli o conversioni.

Se si crea una tabella personalizzata tramite il portale di Azure, la DCR e la trasformazione vengono creati automaticamente in base ai dati di esempio forniti. Se si usa una tabella esistente o si crea una tabella personalizzata usando un altro metodo, è necessario creare manualmente la DCR usando i dettagli nella sezione seguente.

Dopo aver creato la DCR, è necessario concedere l'accesso all'applicazione creata nel primo passaggio. Dal menu Monitoraggio nel portale di Azure selezionare Regole di raccolta dati, quindi la DCR creata. Selezionare Controllo di accesso (IAM) per la DCR, quindi selezionare Aggiungi assegnazione di ruolo per aggiungere il ruolo Monitoring Metrics Publisher.

Endpoint

L'endpoint dell'API REST per l'API di inserimento dei log può essere un endpoint di raccolta dati (DCE) o l'endpoint di inserimento dei log DCR.

L'endpoint di inserimento dei log DCR viene generato quando si crea un record di registrazione dati per l'inserimento diretto. Per recuperare questo endpoint, aprire il DCR nella visualizzazione JSON nella portale di Azure. Potrebbe essere necessario modificare la versione dell'API con la versione più recente per visualizzare gli endpoint.

Screenshot che mostra l'endpoint di inserimento dei log in un record di controllo dell'accesso.

Un controller di dominio di dominio è necessario solo quando ci si connette a un'area di lavoro Log Analytics usando un collegamento privato o se DCR non include l'endpoint di inserimento dei log. Questo può essere il caso se si usa un record di dominio precedente o se è stato creato il record di controllo di dominio senza il "kind": "Direct" parametro . Per altri dettagli, vedere La regola di raccolta dati (DCR) di seguito.

Nota

La logsIngestion proprietà è stata aggiunta il 31 marzo 2024. Prima di questa data, è stato necessario un controller di dominio per l'API di inserimento dei log. Gli endpoint non possono essere aggiunti a un record di dominio esistente, ma è possibile continuare a usare qualsiasi controller di dominio esistente con controller di dominio esistenti. Se si vuole passare a un endpoint DCR, è necessario creare un nuovo DCR per sostituire quello esistente. Un controller di dominio con endpoint può anche usare un controller di dominio. In questo caso, è possibile scegliere se usare gli endpoint DCE o DCR per ognuno dei client che usano il record di controllo di dominio.

Regola di raccolta dati (DCR)

Quando si crea una tabella personalizzata in un'area di lavoro Log Analytics usando il portale di Azure, viene creato automaticamente un record di controllo di accesso che può essere usato con l'API di inserimento log. Se si inviano dati a una tabella già esistente, è necessario creare manualmente la DCR. Iniziare con il DCR di esempio seguente, sostituendo i valori per i parametri seguenti nel modello. Usare uno dei metodi descritti in Creare e modificare le regole di raccolta dati (DCR) in Monitoraggio di Azure per creare il DCR.

Parametro Descrizione
region Area per creare la DCR. Deve corrispondere all'area dell'area di lavoro Log Analytics e al controller di dominio se ne usa uno.
dataCollectionEndpointId ID della risorsa del DCE. Rimuovere questo parametro se si usa il punto di inserimento DCR.
streamDeclarations Modificare l'elenco di colonne con le colonne presenti nei dati in ingresso. Non è necessario modificare il nome del flusso poiché è sufficiente che corrisponda al nome streams in dataFlows.
workspaceResourceId ID della risorsa dell'area di lavoro Log Analytics. Non è necessario modificare il nome poiché è sufficiente che corrisponda al nome destinations in dataFlows.
transformKql Query KQL da applicare ai dati in ingresso. Se lo schema dei dati in ingresso corrisponde allo schema della tabella, è possibile usare source per la trasformazione che trasmetterà i dati in arrivo senza modifiche. In caso contrario, usare una query che trasformerà i dati in modo che corrispondano allo schema della tabella di destinazione.
outputStream Nome della tabella da inviare. Per una tabella personalizzata, aggiungere il prefisso Custom-<table-name>. Per una tabella predefinita, aggiungere il prefisso 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"
            }
        ]
    }
}

Librerie client

Oltre a effettuare una chiamata API REST, è possibile usare le librerie client seguenti per inviare dati all'API di inserimento dei log. Le librerie richiedono gli stessi componenti descritti in Configurazione. Per gli esempi d'uso di ognuna di queste librerie, vedere Codice di esempio per inviare dati ad Monitoraggio di Azure usando l'API di inserimento dei log.

Chiamata API REST

Per inviare dati a Monitoraggio di Azure con una chiamata API REST, effettuare una chiamata POST su HTTP. I dettagli necessari per questa chiamata sono descritti in questa sezione.

URI

L'URI include l'area, l'endpoint di inserimento DCE o DCR, l'ID DCR e il nome del flusso. Specifica anche la versione dell'API.

L'URI usa il formato seguente.

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

Ad esempio:

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

L'oggetto DCR Immutable ID viene generato per il record di controllo di dominio quando viene creato. È possibile recuperarlo dalla pagina Panoramica della DCR nel portale di Azure.

Screenshot di una regola di raccolta dati che mostra l'ID non modificabile.

Stream Name fa riferimento al flusso nella DCR che dovrebbe gestire i dati personalizzati.

Intestazioni

La tabella seguente descrive le intestazioni per la chiamata API.

Intestazione Obbligatorio? Descrizione
Autorizzazione Sì Token di connessione ottenuto tramite il flusso delle credenziali client. Usare il valore del gruppo di destinatari del token per il cloud:

Cloud pubblico di Azure - https://monitor.azure.com
Microsoft Azure gestito dal cloud 21Vianet - https://monitor.azure.cn
Cloud di Azure US Government - https://monitor.azure.us
Content-Type Sì application/json
Content-Encoding No gzip
x-ms-client-request-id No GUID in formato stringa. Si tratta di un ID di richiesta che può essere usato da Microsoft per la risoluzione dei problemi.

Testo

Il corpo della chiamata include i dati personalizzati da inviare a Monitoraggio di Azure. La forma dei dati deve essere una matrice JSON con una struttura di elementi che corrisponde al formato previsto dal flusso nella DCR. Se è necessario inviare un singolo elemento all'interno della chiamata API, i dati devono essere inviati come matrice di elementi singoli.

Ad esempio:

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

Assicurarsi che il corpo della richiesta sia correttamente codificato in UTF-8 per evitare problemi con la trasmissione dei dati.

Esempio

Per un esempio di chiamata API tramite PowerShell, vedere Codice di esempio per inviare dati a Monitoraggio di Azure tramite l'API di inserimento dei log.

Tabelle supportate

I dati inviati all'API di inserimento possono essere inviati alle tabelle seguenti:

Tabelle Descrizione
Tabelle personalizzate Qualsiasi tabella personalizzata creata nell'area di lavoro Log Analytics. La tabella di destinazione deve esistere prima di potervi inviare i dati. Le tabelle personalizzate devono avere il suffisso _CL.
Tabelle di Azure Attualmente sono supportate le tabelle Azure seguenti. È possibile aggiungere altre tabelle a questo elenco man mano che ne viene implementato il supporto.

Nota

I nomi delle colonne devono iniziare con una lettera e possono essere costituiti da un massimo di 45 caratteri alfanumerici e caratteri di sottolineatura (_). _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId e Title sono nomi di colonna riservati. Le colonne personalizzate aggiunte a una tabella di Azure devono avere il suffisso _CF.

Limiti e restrizioni

Per i limiti relativi all'API di inserimento dei log, vedere Limiti del servizio Monitoraggio di Azure.

Passaggi successivi