Esercitazione: Inviare dati ai log di Monitoraggio di Azure usando l'API di inserimento log (modelli di Resource Manager)

  • Articolo

L'API di inserimento dei log in Monitoraggio di Azure consente di inviare dati personalizzati a un'area di lavoro di Log Analytics. Questa esercitazione usa i modelli di Azure Resource Manager (modelli di ARM) per esaminare la configurazione dei componenti necessari per supportare l'API e quindi fornisce un'applicazione di esempio che usa l'API REST e le librerie client per .NET, Go, Java, JavaScript e Python.

Nota

Questa esercitazione usa i modelli di ARM per configurare i componenti necessari per supportare l'API di inserimento dei log. Vedere Esercitazione: Inviare dati a Log di Monitoraggio di Azure con l'API di inserimento dei log (portale di Azure) per un'esercitazione simile che usa l'interfaccia utente del portale di Azure per configurare questi componenti.

I passaggi necessari per configurare l'API di inserimento dei log sono i seguenti:

  1. Creare un'applicazione Microsoft Entra per l'autenticazione con l'API.
  2. Creare una tabella personalizzata in un'area di lavoro di Log Analytics. Questa è la tabella a cui verranno inviati i dati.
  3. Creare una regola di raccolta dati (DCR) per indirizzare i dati alla tabella di destinazione.
  4. Concedere all'applicazione Microsoft Entra l'accesso alla DCR.
  5. Vedere Codice di esempio per inviare dati a Monitoraggio di Azure usando l'API di inserimento dei log per l'invio di dati a tramite l'API di inserimento dei log.

Nota

Questo articolo include opzioni per l'uso di un endpoint di inserimento DCR o di un endpoint di raccolta dati (DCE). È possibile scegliere di usare uno dei due, ma un DCE è necessario con l'API di inserimento dei log se viene usato un collegamento privato. Vedere Quando è necessario un DCE?.

Prerequisiti

Per completare questa esercitazione è necessario:

Raccogliere i dettagli dell'area di lavoro

Per iniziare, raccogliere informazioni necessarie dall'area di lavoro.

Andare all'area di lavoro nel menu Aree di lavoro di Log Analytics nel portale di Azure. Nella pagina Proprietà copiare l'ID risorsa e salvarlo per usarlo in un secondo momento.

Screenshot che mostra l'ID della risorsa dell'area di lavoro.

Creare un'applicazione Microsoft Entra

Per iniziare, registrare un'applicazione Microsoft Entra per l'autenticazione nell'API. Qualsiasi schema di autenticazione di Resource Manager è supportato, ma questa esercitazione segue lo schema Flusso di concessione delle credenziali client.

  1. Nel menu Microsoft Entra ID nel portale di Azure selezionare Registrazioni app> Nuova registrazione.

    Screenshot che mostra la schermata di registrazione dell'app.

  2. Assegnare un nome all'applicazione e modificare l'ambito della tenancy se l'impostazione predefinita non è appropriata per l'ambiente. Non è necessario un URI di reindirizzamento.

    Screenshot che mostra i dettagli dell'app.

  3. Dopo la registrazione, è possibile visualizzare i dettagli dell'applicazione. Prendere nota dei valori ID applicazione (client) e ID directory (tenant). Questi valori saranno necessari più avanti nel processo.

    Schermata che mostra l'ID app.

  4. Generare un segreto client dell'applicazione, simile alla creazione di una password da usare con un nome utente. Selezionare Certificati e segreti>Nuovo segreto client. Assegnare un nome al segreto per identificarne lo scopo e selezionare una durata di scadenza. L'opzione 12 mesi è selezionata qui. Per un'implementazione di produzione, è consigliabile seguire le procedure consigliate per una procedura di rotazione dei segreti o usare una modalità di autenticazione più sicura, ad esempio un certificato.

    Screenshot che mostra il segreto per la nuova app.

  5. Selezionare Aggiungi per salvare il segreto e quindi prendere nota del Valore. Assicurarsi di registrare questo valore perché non è possibile recuperarlo dopo aver lasciato questa pagina. Usare le stesse misure di sicurezza necessarie per mantenere una password sicura perché è l'equivalente funzionale.

    Screenshot che mostra il valore del segreto per la nuova app.

Crea endpoint di raccolta dati

Un DCE non è obbligatorio se si usa l'endpoint di inserimento DCR.

Creare la nuova tabella nell'area di lavoro di Log Analytics

Prima di poter inviare dati, è necessario creare la tabella personalizzata. La tabella per questa esercitazione includerà cinque colonne illustrate nello schema seguente. Le proprietà name, type e description sono obbligatorie per ogni colonna. Per impostazione predefinita, entrambe le proprietà isHidden e isDefaultDisplay passano a false se non sono specificate in modo esplicito. I tipi di dati possibili sono string, int, long, real, boolean, dateTime, guid e dynamic.

Nota

Questa esercitazione usa PowerShell di Azure Cloud Shell per effettuare chiamate API REST usando l'API Tabelle di Monitoraggio di Azure. È possibile usare qualsiasi altro metodo valido per effettuare queste chiamate.

Importante

Le tabelle personalizzate devono usare un suffisso _CL.

  1. Selezionare il pulsante Cloud Shell nel portale di Azure e assicurarsi che l'ambiente sia impostato su PowerShell.

    Screenshot che mostra l'apertura di Cloud Shell.

  2. Copiare il codice di PowerShell seguente e sostituire la variabili nel parametro Percorso con i valori appropriati per l'area di lavoro nel comando Invoke-AzRestMethod. Incollarlo nel prompt di Cloud Shell per eseguirlo.

    $tableParams = @'
{
    "properties": {
        "schema": {
            "name": "MyTable_CL",
            "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime",
                    "description": "The time at which the data was generated"
                },
               {
                    "name": "Computer",
                    "type": "string",
                    "description": "The computer that generated the data"
                },
                {
                    "name": "AdditionalContext",
                    "type": "dynamic",
                    "description": "Additional message properties"
                },
                {
                    "name": "CounterName",
                    "type": "string",
                    "description": "Name of the counter"
                },
                {
                    "name": "CounterValue",
                    "type": "real",
                    "description": "Value collected for the counter"
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams

Crea regola di raccolta dati

Il DCR definisce la modalità di gestione dei dati dopo la ricezione. Valuta gli ambiti seguenti:

  • Schema dei dati inviati all'endpoint
  • Trasformazione che verrà applicata ai dati prima dell'invio all'area di lavoro
  • Area di lavoro di destinazione e tabella a cui verranno inviati i dati trasformati

  1. Nella casella di ricerca del portale di Azure, inserire modello e quindi selezionare Distribuisci un modello personalizzato.

    Screenshot che mostra come distribuire un modello personalizzato.

  2. Selezionare Creare un modello personalizzato nell'editor.

    Screenshot che mostra come compilare un modello nell'editor.

  3. Incollare il modello di ARM seguente nell'editor, quindi selezionare Salva.

    Screenshot che mostra come modificare un modello di ARM.

    Si notino i dettagli seguenti nella DCR definito in questo modello:

    • streamDeclarations: definizioni di colonna dei dati in ingresso.
    • destinations: area di lavoro di destinazione.
    • dataFlows: corrisponde al flusso con l'area di lavoro di destinazione e specifica la query di trasformazione e la tabella di destinazione. L'output della query di destinazione è ciò che verrà inviato alla tabella di destinazione.
    {
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2023-03-11",
            "kind": "Direct",
            "properties": {
                "streamDeclarations": {
                    "Custom-MyTableRawData": {
                        "columns": [
                            {
                                "name": "Time",
                                "type": "datetime"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            },
                            {
                                "name": "AdditionalContext",
                                "type": "string"
                            },
                            {
                                "name": "CounterName",
                                "type": "string"
                            },
                            {
                                "name": "CounterValue",
                                "type": "real"
                            }
                        ]
                    }
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "myworkspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyTableRawData"
                        ],
                        "destinations": [
                            "myworkspace"
                        ],
                        "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                        "outputStream": "Custom-MyTable_CL"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

  1. Nella schermata Distribuzione personalizzata specificare una sottoscrizione e un gruppo di risorse per archiviare la DCR. Specificare quindi i valori definiti nel modello. I valori includono un nome per la DCR e l'ID risorsa dell'area di lavoroLoop raccolti in un passaggio precedente. La Località deve essere la stessa posizione dell'area di lavoro. L'area sarà già popolata e verrà usata per la posizione della DCR.

    Screenshot che mostra come modificare i valori di distribuzione personalizzati.

  2. Selezionare Rivedi + crea e quindi Crea dopo aver esaminato i dettagli.

  3. Al termine della distribuzione, espandere la casella Dettagli distribuzione e selezionare la DCR per visualizzarne i dettagli. Selezionare Visualizzazione JSON.

    Screenshot che mostra i dettagli di DCR.

  4. Copiare l'ID non modificabile e l'URI di inserimento dei log per la DCR. Questi verranno usati quando si inviano dati a Monitoraggio di Azure usando l'API.

    Screenshot che mostra la visualizzazione JSON DCR.

Assegnare le autorizzazioni a una DCR

Dopo aver creato la DCR, è necessario assegnare all'applicazione l'autorizzazione. L'autorizzazione consentirà a qualsiasi applicazione di usare l'ID applicazione e la chiave dell'applicazione corretti per inviare dati alla nuova DCR.

  1. Nella DCR del portale di Azure, selezionare Controllo di accesso (IAM)>Aggiungi assegnazione di ruolo.

    Screenshot che mostra l'aggiunta di un'assegnazione di ruolo personalizzata a DCR.

  2. Selezionare Monitoraggio server di pubblicazione metriche seguito da Avanti. È invece possibile creare un'azione personalizzata con l'azione dati Microsoft.Insights/Telemetry/Write.

    Screenshot che mostra la selezione di un ruolo per l'assegnazione di ruolo DCR.

  3. In Assegna accesso a selezionare Utente, gruppo o entità servizio quindi scegliere Seleziona membri. Selezionare l'applicazione creata e scegliere Seleziona.

    Screenshot che mostra la selezione dei membri per l'assegnazione di ruolo DCR.

  4. Selezionare Rivedi + assegna e verificare i dettagli prima di salvare l'assegnazione di ruolo.

    Screenshot che mostra il salvataggio dell'assegnazione di ruolo DCR.

Codice di esempio

Vedere Codice di esempio per inviare dati a Monitoraggio di Azure usando l'API di inserimento dei log per il codice di esempio usando i componenti creati in questa esercitazione.

Passaggi successivi