Condividi tramite

Inviare dati di log a Monitoraggio di Azure con l'API di raccolta dati HTTP (deprecato)

  • Articolo

Questo articolo illustra come usare l'API di raccolta dati HTTP per inviare dati di log a Monitoraggio di Azure da un client dell'API REST. L'articolo descrive come formattare i dati raccolti dall'applicazione o dallo script, come includerli in una richiesta e come autorizzare tale richiesta in Monitoraggio di Azure. Vengono forniti esempi per Azure PowerShell, C# e Python.

Nota

L'API dell'agente di raccolta dati HTTP di Monitoraggio di Azure è stata deprecata e non funzionerà più a partire dal 14/09/2026. È stata sostituita dall'API di inserimento log.

Concetti

È possibile usare l'API di raccolta dati HTTP per inviare dati di log a un'area di lavoro Log Analytics in Monitoraggio di Azure da qualsiasi client in grado di chiamare un'API REST. Il cliente potrebbe essere un runbook in Automazione di Azure che raccoglie dati di gestione da Azure o da un altro cloud oppure di un sistema di gestione alternativo che usa Monitoraggio di Azure per consolidare e analizzare i dati di log.

Tutti i dati nell'area di lavoro Log Analytics vengono archiviati come record con un tipo specifico. I dati da inviare all'API dell'agente di raccolta dati HTTP devono essere formattati come più record in JSON (JavaScript Object Notation). Quando si inviano i dati, nel repository viene creato un record singolo per ogni record presente nel payload della richiesta.

Screenshot che illustra la panoramica dell'agente di raccolta dati HTTP.

Crea una richiesta

Per usare l'API dell'agente di raccolta dati HTTP, creare una richiesta POST che include i dati da inviare in formato JSON. Le tre tabelle successive indicano gli attributi necessari per ogni richiesta. Ogni attributo viene descritto con maggiori dettagli più avanti nell'articolo.

URI della richiesta

Attributo Proprietà
metodo POST
URI https://<IdCliente>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Content type application/json

Parametri URI della richiesta

Parametro Descrizione
CustomerID Identificatore univoco per l'area di lavoro Log Analytics.
Conto risorse Nome della risorsa API: /api/logs.
Versione dell'API Versione dell'API da usare con questa richiesta. Attualmente, la versione è 2016-04-01.

Intestazioni della richiesta

Intestazione Descrizione
Autorizzazione Firma di autorizzazione. Più avanti nell'articolo sono disponibili informazioni sulla creazione di un'intestazione HMAC-SHA256.
Log-Type Specificare il tipo di record dei dati inviati. Può contenere solo lettere, numeri e il carattere di sottolineatura (_) e non può superare i 100 caratteri.
x-ms-date Data di elaborazione della richiesta, in formato RFC 1123.
x-ms-AzureResourceId ID risorsa della risorsa di Azure a cui devono essere associati i dati. Popola la proprietà _ResourceId e consente di includere i dati nelle query con contesto risorsa. Se questo campo non viene specificato, i dati non verranno inclusi nelle query con contesto risorsa.
time-generated-field Nome di un campo nei dati che contiene il timestamp dell'elemento di dati. Se si specifica un campo, il relativo contenuto verrà usato per TimeGenerated. Se non si specifica questo campo, il valore predefinito di TimeGenerated sarà la data/ora di inserimento del messaggio. Il contenuto del campo del messaggio deve seguire il formato ISO 8601 AAAA-MM-GGThh:mm:ssZ. Il valore Time Generated non può essere precedente a 2 giorni prima della ricezione o più di un giorno in futuro. In tal caso, verrà usata la data/ora di inserimento del messaggio.

Autorizzazione

Qualsiasi richiesta inviata all'API di raccolta dati HTTP di Monitoraggio di Azure deve includere l'intestazione dell'autorizzazione. Per autenticare una richiesta, firmarla con la chiave primaria o secondaria dell'area di lavoro che effettua la richiesta. Passare quindi la firma come parte della richiesta.

Il formato dell'intestazione dell'autorizzazione è il seguente:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID è l'identificatore univoco per l'area di lavoro Log Analytics. Signature è un codice HMAC (Hash-based Message Authentication Code) che viene creato dalla richiesta e quindi calcolato con l'algoritmo SHA256. Viene quindi codificato con la codifica Base64.

Usare questo formato per codificare la stringa di firma SharedKey:

StringToSign = VERB + "\n" +
                  Content-Length + "\n" +
                  Content-Type + "\n" +
                  "x-ms-date:" + x-ms-date + "\n" +
                  "/api/logs";

Di seguito è riportato un esempio di stringa della firma:

POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs

La stringa della firma deve essere codificata usando l'algoritmo HMAC-SHA256 sulla stringa con codifica UTF-8. Il risultato deve essere quindi codificato in Base64. Usare il formato seguente:

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

Gli esempi nelle sezioni successive indicano il codice di esempio per creare l'intestazione dell'autorizzazione.

Testo della richiesta

Il corpo del messaggio deve essere in formato JSON. Deve includere uno o più record con coppie di nome e valore di proprietà nel formato seguente. Il nome della proprietà può contenere solo lettere, numeri e il carattere di sottolineatura (_).

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

È possibile creare batch di più record in una singola richiesta usando il formato seguente. Tutti i record devono essere dello stesso tipo.

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    },
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

Proprietà e tipo di record

Quando si inviano dati con l'API di raccolta dati HTTP di Monitoraggio di Azure si definisce un tipo di record personalizzato. È attualmente possibile scrivere dati nei tipi di record esistenti creati da altri tipi di dati e soluzioni. Monitoraggio di Azure legge i dati in ingresso e quindi crea le proprietà che corrispondono ai tipi di dati dei valori immessi.

Ogni richiesta all'API di raccolta dati deve includere un'intestazione Log-Type con il nome del tipo di record. Il suffisso _CL viene aggiunto automaticamente al nome immesso per distinguerlo da altri tipi di log come log personalizzato. Se ad esempio si immette il nome MyNewRecordType, Monitoraggio di Azure crea un record di tipo MyNewRecordType_CL. È così possibile evitare conflitti tra i nomi dei tipi creati dall'utente e i nomi forniti nelle soluzioni Microsoft correnti o future.

Per identificare il tipo di dati di una proprietà, Monitoraggio di Azure aggiunge un suffisso al nome della proprietà. Una proprietà con un valore null non viene inclusa in tale record. Questa tabella elenca il tipo di dati proprietà e il suffisso corrispondente:

Tipo di dati proprietà Suffisso
String _s
Booleano _b
Double _d
Data/ora _t
GUID (archiviato come stringa) _g

Nota

Ai valori stringa che sembrano essere GUID viene assegnato il suffisso _g e vengono formattati come GUID, anche se il valore in ingresso non include trattini. Ad esempio, sia "8145d822-13a7-44ad-859c-36f31a84f6dd" che "8145d82213a744ad859c36f31a84f6dd" vengono archiviati come "8145d822-13a7-44ad-859c-36f31a84f6dd". Le uniche differenze tra questa e un'altra stringa sono la _g nel nome e l'inserimento di trattini se non sono presenti nell'input.

Il tipo di dati usato da Monitoraggio di Azure per ogni proprietà dipende dall'eventuale esistenza di un tipo di record per il nuovo record.

  • Se il tipo di record non esiste, Monitoraggio di Azure ne crea uno nuovo usando l'inferenza del tipo JSON per determinare il tipo di dati per ogni proprietà del nuovo record.
  • Se il tipo di record esiste, Monitoraggio di Azure prova a creare un nuovo record in base alle proprietà esistenti. Se il tipo di dati di una proprietà nel nuovo record non corrisponde e non può essere convertito nel tipo esistente, oppure se il record include una proprietà che non esiste, Monitoraggio di Azure crea una nuova proprietà con il suffisso pertinente.

Ad esempio, la voce di invio seguente creerà un record con tre proprietà, number_d, boolean_b e string_s:

Screenshot del record di esempio 1.

Se si inviasse la voce seguente, con tutti i valori formattati come stringhe, le proprietà non cambierebbero. È possibile convertire i valori nei tipi di dati esistenti.

Screenshot del record di esempio 2.

Con l'invio seguente, tuttavia, Monitoraggio di Azure creerebbe le nuove proprietà boolean_d e string_d. Non è possibile convertire questi valori.

Screenshot del record di esempio 3.

Inviando la voce seguente, prima della creazione del tipo di record Monitoraggio di Azure creerebbe un record con tre proprietà, number_s, boolean_s e string_s. In questa voce, ognuno dei valori iniziali viene formattato come stringa:

Screenshot del record di esempio 4.

Proprietà riservate

Le proprietà seguenti sono riservate e non devono essere usate in un tipo di record personalizzato. Se il payload include uno di questi nomi di proprietà, verrà visualizzato un errore:

  • tenant
  • TimeGenerated
  • RawData

Limiti dei dati

I dati inviati all'API di raccolta dati di Monitoraggio di Azure sono soggetti a determinati vincoli:

  • Limite di 30 MB per post nell'API per la raccolta dei dati di Monitoraggio di Azure. Questo limite riguarda le dimensioni di ogni messaggio. Se i dati di un singolo post superano i 30 MB, è necessario suddividerli in blocchi di dimensioni inferiori, che andranno inviati contemporaneamente.
  • Massimo 32 KB per i valori dei campi. Se il valore di un campo è superiore a 32 KB, i dati verranno troncati.
  • Il numero massimo di campi consigliato per un determinato tipo è 50. Si tratta di un limite pratico dal punto di vista dell'usabilità e dell'esperienza di ricerca.
  • Una tabella in un'area di lavoro Log Analytics supporta solo al massimo 500 colonne, indicate in questo articolo come campi.
  • Massimo 45 caratteri per i nomi di colonna.

Codici restituiti

Il codice di stato HTTP 200 indica che è stata ricevuta la richiesta per l'elaborazione. Indica che l'operazione è stata completata correttamente.

Il set completo di codici di stato che il servizio potrebbe restituire è elencato nella tabella seguente:

Codice Status Codice errore Descrizione
200 OK La richiesta è stata accettata.
400 Richiesta non valida InactiveCustomer L'area di lavoro è stata chiusa.
400 Richiesta non valida InvalidApiVersion La versione API specificata non è stata riconosciuta dal servizio.
400 Richiesta non valida InvalidCustomerId L'ID dell'area di lavoro specificato non è valido.
400 Richiesta non valida InvalidDataFormat È stata inviato codice JSON non valido. Il corpo della risposta può contenere altre informazioni sulla risoluzione dell'errore.
400 Richiesta non valida InvalidLogType Il tipo di log specificato conteneva caratteri speciali o numeri.
400 Richiesta non valida MissingApiVersion La versione API non è stata specificata.
400 Richiesta non valida MissingContentType Il tipo di contenuto non è stato specificato.
400 Richiesta non valida MissingLogType Il tipo di log dei valori non è stato specificato.
400 Richiesta non valida UnsupportedContentType Il tipo di contenuto non è stato impostato su application/json.
403 Non consentito InvalidAuthorization Il servizio non è riuscito ad autenticare la richiesta. Verificare che l'ID dell'area di lavoro e la chiave di connessione siano validi.
404 Non trovato L'URL specificato non è corretto o la richiesta è di dimensioni eccessive.
429 Troppe richieste Il servizio sta ricevendo un elevato volume di dati dall'account. Si prega di ripetere la richiesta più tardi.
500 Internal Server Error UnspecifiedError Errore interno del servizio. Si prega di ripetere la richiesta.
503 Servizio non disponibile ServiceUnavailable Il servizio non è attualmente disponibile per la ricezione delle richieste. Si prega di ripetere la richiesta.

Eseguire query sui dati

Per eseguire query sui dati inviati dall'API di raccolta dati HTTP di Monitoraggio di Azure, cercare i record con Type uguale al valore LogType specificato, con l'aggiunta di _CL. Usando MyCustomLog, ad esempio, verrebbero restituiti tutti i record con MyCustomLog_CL.

Richieste di esempio

Questa sezione include esempi che dimostrano come inviare dati all'API dell'agente di raccolta dati HTTP di Monitoraggio di Azure usando vari linguaggi di programmazione.

Per ogni esempio, impostare le variabili per l'intestazione dell'autorizzazione seguendo questa procedura:

  1. Nel portale di Azure individuare l'area di lavoro Log Analytics.
  2. Selezionare Agenti.
  3. A destra di ID area di lavoro selezionare l'icona Copia e quindi incollare l'ID come valore della variabile ID cliente.
  4. A destra di Chiave primaria selezionare l'icona Copia e quindi incollare l'ID come valore della variabile Chiave condivisa.

In alternativa è possibile modificare le variabili per il tipo di log e i dati JSON.

# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  

# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"

# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""


# Create two records with the same set of properties to create
$json = @"
[{  "StringValue": "MyString1",
    "NumberValue": 42,
    "BooleanValue": true,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{   "StringValue": "MyString2",
    "NumberValue": 43,
    "BooleanValue": false,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@

# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
    $xHeaders = "x-ms-date:" + $date
    $stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource

    $bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
    $keyBytes = [Convert]::FromBase64String($sharedKey)

    $sha256 = New-Object System.Security.Cryptography.HMACSHA256
    $sha256.Key = $keyBytes
    $calculatedHash = $sha256.ComputeHash($bytesToHash)
    $encodedHash = [Convert]::ToBase64String($calculatedHash)
    $authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
    return $authorization
}

# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
    $method = "POST"
    $contentType = "application/json"
    $resource = "/api/logs"
    $rfc1123date = [DateTime]::UtcNow.ToString("r")
    $contentLength = $body.Length
    $signature = Build-Signature `
        -customerId $customerId `
        -sharedKey $sharedKey `
        -date $rfc1123date `
        -contentLength $contentLength `
        -method $method `
        -contentType $contentType `
        -resource $resource
    $uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"

    $headers = @{
        "Authorization" = $signature;
        "Log-Type" = $logType;
        "x-ms-date" = $rfc1123date;
        "time-generated-field" = $TimeStampField;
    }

    $response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
    return $response.StatusCode

}

# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType

Alternative e considerazioni

Anche se l'API dell'agente di raccolta dati dovrebbe coprire la maggior parte delle esigenze durante la raccolta di dati in formato libero nei log di Azure, potrebbe essere necessario un approccio alternativo per superare alcune delle limitazioni dell'API. Le opzioni, incluse le considerazioni principali, sono elencate nella tabella seguente:

Alternativa Descrizione Ideale per
Eventi personalizzati: inserimento basato su SDK nativo in Application Insights Application Insights, in genere instrumentato tramite un SDK all'interno dell'applicazione, consente di inviare dati personalizzati tramite eventi personalizzati.
  • Dati generati all'interno dell'applicazione, ma non raccolti dall'SDK tramite uno dei tipi di dati predefiniti (richieste, dipendenze, eccezioni e così via).
  • Dati spesso correlati ad altri dati dell'applicazione in Application Insights.
API dell'agente di raccolta dati nei log di Monitoraggio di Azure L'API dell'agente di raccolta dati nei log di Monitoraggio di Azure è un modo completamente aperto per inserire i dati. Tutti i dati formattati in un oggetto JSON possono essere inviati qui. Dopo l'invio, vengono elaboratori e resi disponibili nei log di monitoraggio per la correlazione con altri dati nei log di monitoraggio o con altri dati di Application Insights.

È abbastanza facile caricare i dati come file in un BLOB di Archiviazione BLOB di Azure, in cui i file verranno elaborati e quindi caricati in Log Analytics. Per un'implementazione di esempio, vedere Creare una pipeline di dati con l'API dell'Agente di raccolta dati.
  • Dati che non vengono necessariamente generati all'interno di un'applicazione instrumentata in Application Insights.
    Gli esempi includono tabelle di ricerca e fatti, dati di riferimento, statistiche preaggregate e così via.
  • Dati a cui verrà fatto riferimento incrociato per altri dati di Monitoraggio di Azure (Application Insights, altri tipi di dati dei log di monitoraggio, Defender per il cloud, informazioni dettagliate sui contenitori e macchine virtuali e così via).
Esplora dati di Azure Esplora dati di Azure, ora disponibile a livello generale per il pubblico, è la piattaforma dati che supporta Application Insights Analytics e i log di Monitoraggio di Azure. Usando la piattaforma dati nel formato non elaborato, si ha una flessibilità completa (ma con un sovraccarico per la gestione) sul cluster (controllo degli accessi in base al ruolo di Kubernetes), sulla frequenza di conservazione, sullo schema e così via. Esplora dati di Azure offre molte opzioni di inserimento, tra cui file CSV, TSV e JSON.
  • Dati che non verranno correlati ad altri dati in Application Insights o nei log di monitoraggio.
  • Dati che richiedono funzionalità avanzate di inserimento o elaborazione che non sono attualmente disponibili nei log di Monitoraggio di Azure.

Passaggi successivi