API di inserimento dei log in Monitoraggio di Azure

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.

Configurazione

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

Punto finale

L'endpoint dell'API REST per l'API di inserimento dei log può essere un endpoint di raccolta dati o l'endpoint di inserimento dei log della regola di raccolta dati.

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

Un endpoint di raccolta dati è necessario solo quando ci si connette a un'area di lavoro Log Analytics usando un collegamento privato o se la regola di raccolta dati non include l'endpoint di inserimento dei log. Questo può succedere se si usa una regola di raccolta dati precedente o se è stato creata la regola di raccolta dati senza il parametro "kind": "Direct". Per altri dettagli, vedere la regola di raccolta dati di seguito.

Regola di raccolta dati (DCR)

Quando si crea una tabella personalizzata in un'area di lavoro Log Analytics usando il portale di Azure, viene creata automaticamente una regola di raccolta dati, che potrà essere usata con l'API di inserimento dei log. Se si inviano dati a una tabella già esistente, è necessario creare manualmente la DCR. Iniziare con la regola di raccolta dati 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 la regola di raccolta dati.

{
    "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.

• .NET
• Go
• Giava
• JavaScript
• Pitone

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 della regola di raccolta dati e il nome del flusso. Specifica anche la versione 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 la regola di raccolta dati alla sua creazione. È possibile recuperarlo dalla pagina Panoramica della DCR nel portale di Azure.

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

Intestazioni della richiesta

La tabella seguente descrive le intestazioni delle richieste per la chiamata API.

Corpo della richiesta

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. Di seguito è riportato un esempio di matrice a singolo elemento.

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:

• Raccomandazione di valutazione AD
  
• RaccomandazioneValutazioneSicurezzaAD
  
• Anomalie
  
• ASimAuditEventLogs
  
• ASimAuthenticationEventLogs
  
• ASimDhcpEventLogs
  
• ASimDnsActivityLogs
  
• ASimDnsAuditLogs
  
• ASimFileEventLogs
  
• ASimNetworkSessionLogs
  
• ASimProcessEventLogs
  
• ASimRegistryEventLogs
  
• ASimUserManagementActivityLogs
  
• ASimWebSessionLogs
  
• AWSCloudTrail
  
• AWSCloudWatch
  
• AWSGuardDuty
  
• AWSVPCFlow
  
• Raccomandazione di Valutazione di Azure
  
• CommonSecurityLog
  
• DeviceTvmSecureConfigurationAssessmentKB
  
• DeviceTvmSoftwareVulnerabilitiesKB
  
• ExchangeAssessmentRecommendation
  
• Raccomandazione di valutazione di Exchange Online
  
• GCPAuditLogs
  
• GoogleCloudSCC
  
• SCCMValutazioneRaccomandazione
  
• Raccomandazioni di Valutazione SCOM
  
• SecurityEvent
  
• SfBAssessmentRecommendation
  
• SfBOnlineAssessmentRecommendation
  
• RaccomandazioneValutazioneSharePointOnline
  
• RaccomandazioneDiValutazioneSP
  
• Raccomandazione di Valutazione SQL
  
• StorageInsightsAccountPropertiesDaily
  
• StorageInsightsDailyMetrics
  
• Metriche Orarie di Storage Insights
  
• Metriche Mensili di StorageInsights
  
• Metriche settimanali di Storage Insights
  
• Syslog
  
• UCClient
  
• UCClientReadinessStatus
  
• UCClientUpdateStatus
  
• UCDeviceAlert
  
• UCDOAggregatedStatus
  
• UCDOStatus
  
• UCServiceUpdateStatus
  
• UCUpdateAlert
  
• WindowsClientAssessmentRecommendation
  
• WindowsEvent
  
• RaccomandazioneDiValutazioneDelServerWindows
  

Limiti e restrizioni

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

Passaggi successivi

• Esercitazione sull'invio di dati ai registri di Monitoraggio di Azure con l'API di inserimento dei log nel portale di Azure
• Esercitazione sull'invio di log personalizzati usando i modelli di Resource Manager e l'API REST
• Ottenere indicazioni sull'uso delle librerie client per l'API di inserimento dei log per .NET, Java, JavaScripto Python.