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 usando una chiamata API REST o librerie client. L'API consente di inviare dati alle tabelle di Azure supportate o alle tabelle personalizzate create. È 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. Può trattarsi di un'applicazione personalizzata creata oppure di un'applicazione o di un agente che riconosce come inviare dati all'API. L'applicazione invia dati a un endpoint di raccolta dati (DCE), che è un punto di connessione univoco per la sottoscrizione di Azure. Specifica una regola di raccolta dati (DCR) che include la tabella di destinazione e l'area di lavoro e le credenziali di una registrazione dell'app con accesso al record di dominio specificato.

I dati inviati dall'applicazione all'API devono essere formattati in JSON e corrispondere alla struttura prevista dal DCR. Non è necessariamente necessario che corrisponda alla struttura della tabella di destinazione perché il 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 il registro di dominio senza alcuna modifica alla chiamata API o ai dati di origine.

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

Impostazione

La tabella seguente descrive ogni componente in Azure che è necessario configurare prima di poter usare l'API di inserimento log.

Nota

Per uno script di PowerShell che automatizza la configurazione di questi componenti, vedere Codice di esempio per inviare dati a Monitoraggio di Azure usando 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 al Registro Azure Container descritto di seguito. La chiamata API include l'ID applicazione (client) e l'ID 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.
Endpoint di raccolta dati (DCE) DcE fornisce un endpoint a cui inviare l'applicazione. Un singolo controller di dominio può supportare più controller di dominio di dominio, quindi è possibile usare un controller di dominio esistente se ne esiste già uno nella stessa area dell'area di lavoro Log Analytics.

Vedere Creare un endpoint di raccolta dati.
Tabella nell'area di lavoro Log Analytics La tabella nell'area di lavoro Log Analytics deve esistere prima di poter inviare 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 il Record Di dominio, inclusa una trasformazione, se necessario. Con qualsiasi altro metodo, è necessario creare manualmente il Registro Azure Container come descritto nella sezione successiva.

Vedere Creare una tabella personalizzata.
Regola di raccolta dati Monitoraggio di Azure usa la regola di raccolta dati (DCR) per comprendere la struttura dei dati in ingresso e le operazioni da eseguire. Se la struttura della tabella e i dati in ingresso non corrispondono, il registro di dominio può includere una trasformazione per convertire i dati di origine in modo che corrispondano alla tabella di destinazione. È anche possibile usare la trasformazione per filtrare i dati di origine ed eseguire qualsiasi altro calcolo o conversione.

Se si crea una tabella personalizzata usando il portale di Azure, il record di dominio e la trasformazione vengono creati 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 il record di controllo di dominio usando i dettagli nella sezione seguente.

Dopo aver creato il DCR, è necessario concedere l'accesso all'applicazione creata nel primo passaggio. Dal menu Monitoraggio nella portale di Azure selezionare Regole di raccolta dati e quindi il record di controllo dati creato. Selezionare Controllo di accesso (IAM) per DCR e quindi selezionare Aggiungi assegnazione di ruolo per aggiungere il ruolo Server di pubblicazione delle metriche di monitoraggio.

Creare manualmente il Registro Azure Container

Se si inviano dati a una tabella già esistente, è necessario creare manualmente il Registro Azure Container. Iniziare con l'API di inserimento dei log di esempio e modificare i parametri seguenti nel modello. Usare quindi 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 il record di controllo di dominio. Deve corrispondere all'area di DCE e all'area di lavoro Log Analytics.
dataCollectionEndpointId ID risorsa del controller di dominio.
streamDeclarations Modificare l'elenco di colonne con le colonne nei dati in ingresso. Non è necessario modificare il nome del flusso perché è sufficiente che corrisponda al streams nome in dataFlows.
workspaceResourceId ID risorsa dell'area di lavoro Log Analytics. Non è necessario modificare il nome perché è sufficiente che corrisponda al destinations nome 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 passerà i dati in ingresso invariati. In caso contrario, usare una query che trasformerà i dati in modo che corrispondano allo schema della tabella.
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><.

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 esempi relativi all'uso di ognuna di queste librerie, vedere Codice di esempio per inviare dati a 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 endpoint

L'URI dell'endpoint usa il formato seguente, in cui Data Collection Endpoint e DCR Immutable ID identificano dce e registro di dominio. L'ID non modificabile viene generato per il record di controllo di dominio quando viene creato. È possibile recuperarlo dalla visualizzazione JSON del DCR nella portale di Azure. Stream Name fa riferimento al flusso nel Registro Azure Container che deve gestire i dati personalizzati.

{Data Collection Endpoint URI}/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

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 richiesta che può essere usato da Microsoft per qualsiasi scopo di 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 struttura di elementi che corrisponde al formato previsto dal flusso nel DCR. Se è necessario inviare un singolo elemento all'interno della chiamata API, i dati devono essere inviati come matrice a singolo elemento.

Ad esempio:

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

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

Esempio

Vedere Codice di esempio per inviare dati a Monitoraggio di Azure usando l'API di inserimento dei log per un esempio della chiamata API con PowerShell.

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 poter inviare dati. Le tabelle personalizzate devono avere il _CL suffisso .
Tabelle di Azure Le tabelle di Azure seguenti sono attualmente supportate. È possibile aggiungere altre tabelle a questo elenco perché viene implementato il supporto per tali tabelle.

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, , _SubscriptionIdTenantIdType, , , UniqueId, e Title sono nomi di colonna riservati. _ResourceId Le colonne personalizzate aggiunte a una tabella di Azure devono avere il suffisso _CF.

Limiti e restrizioni

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

Passaggi successivi