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.

Impostazione

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

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.

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.

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.

{
    "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
• Java
• JavaScript
• Python

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.

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.

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:

• ADAssessmentRecommendation
  
• ADSecurityAssessmentRecommendation
  
• Anomalie
  
• ASimAuditEventLogs
  
• ASimAuthenticationEventLogs
  
• ASimDhcpEventLogs
  
• ASimDnsActivityLogs
  
• ASimDnsAuditLogs
  
• ASimFileEventLogs
  
• ASimNetworkSessionLogs
  
• ASimProcessEventLogs
  
• ASimRegistryEventLogs
  
• ASimUserManagementActivityLogs
  
• ASimWebSessionLogs
  
• AWSCloudTrail
  
• AWSCloudWatch
  
• AWSGuardDuty
  
• AWSVPCFlow
  
• AzureAssessmentRecommendation
  
• CommonSecurityLog
  
• DeviceTvmSecureConfigurationAssessmentKB
  
• DeviceTvmSoftwareVulnerabilitiesKB
  
• ExchangeAssessmentRecommendation
  
• ExchangeOnlineAssessmentRecommendation
  
• GCPAuditLogs
  
• GoogleCloudSCC
  
• SCCMAssessmentRecommendation
  
• SCOMAssessmentRecommendation
  
• SecurityEvent
  
• SfBAssessmentRecommendation
  
• SfBOnlineAssessmentRecommendation
  
• SharePointOnlineAssessmentRecommendation
  
• SPAssessmentRecommendation
  
• SQLAssessmentRecommendation
  
• StorageInsightsAccountPropertiesDaily
  
• StorageInsightsDailyMetrics
  
• StorageInsightsHourlyMetrics
  
• StorageInsightsMonthlyMetrics
  
• StorageInsightsWeeklyMetrics
  
• Syslog
  
• UCClient
  
• UCClientReadinessStatus
  
• UCClientUpdateStatus
  
• UCDeviceAlert
  
• UCDOAggregatedStatus
  
• UCDOStatus
  
• UCServiceUpdateStatus
  
• UCUpdateAlert
  
• WindowsClientAssessmentRecommendation
  
• WindowsEvent
  
• WindowsServerAssessmentRecommendation
  

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.