Accesso all'API analisi dei log di Monitoraggio di Azure

È possibile inviare una richiesta di query a un'area di lavoro usando l'endpoint https://api.loganalytics.azure.com di Log Analytics di Monitoraggio di Azure. Per accedere all'endpoint, è necessario eseguire l'autenticazione tramite Microsoft Entra ID.

Nota

L'endpoint api.loganalytics.io viene sostituito da api.loganalytics.azure.com. L'endpoint api.loganalytics.io continuerà a essere supportato per il prossimo futuro.

Eseguire l'autenticazione con una demo della chiave API

Per esplorare rapidamente l'API senza l'autenticazione di Microsoft Entra, utilizzare l'area di lavoro dimostrativa con dati di esempio, che supportano l'autenticazione con chiave API.

Per autenticare ed eseguire query sull'area di lavoro di esempio, usare DEMO_WORKSPACE come {workspace-id} e passare la chiave API DEMO_KEY.

Se l'ID applicazione o la chiave API non è corretta, il servizio API restituisce un errore 403 (accesso negato).

La chiave API DEMO_KEY può essere passata in tre modi diversi, a seconda che si voglia usare un'intestazione, l'URL o l'autenticazione di base:

• Intestazione personalizzata: specificare la chiave API nell'intestazione personalizzata X-Api-Key.
• Parametro query: specificare la chiave API nel parametro URL api_key.
• Autenticazione di base: specificare la chiave API come nome utente o password. Se si specificano entrambi, la chiave API deve essere nel nome utente.

Questo esempio utilizza l'ID dell'area di lavoro e la chiave API nell'intestazione:

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

Endpoint API pubblico

L’endpoint API pubblico è:

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

dove:

• api-version: versione dell'API La versione corrente è “v1.”
• workspaceId: ID dello spazio di lavoro.

La query viene passata nel corpo della richiesta.

Ad esempio:

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

Configurazione dell'autenticazione

Per accedere all'API, registrare un'app client con Microsoft Entra ID e richiedere un token.

1. Registrare un'app in Microsoft Entra ID.

2. Nella pagina di panoramica dell'app selezionare Autorizzazioni API.

3. Seleziona Aggiungi autorizzazione.

4. Nella scheda API usate dall'organizzazione cercare Log Analytics e selezionare API Log Analytics dall'elenco.

   

5. Seleziona Autorizzazioni delegate.

6. Selezionare la casella di controllo Data.Read.

7. Selezionare Aggiungi autorizzazioni.

   

Ora che l'app è registrata e ha le autorizzazioni per usare l'API, concedere all'app l'accesso all'area di lavoro Log Analytics.

1. Nella pagina di panoramica Area di lavoro Log Analytics selezionare Controllo di accesso (IAM).

2. Selezionare Aggiungi un'assegnazione di ruolo.

   

3. Selezionare il ruolo Lettore, quindi selezionare Membri.

   

4. Nella scheda Membri, scegliere Seleziona membri.

5. Immettere il nome dell’app nella casella Seleziona.

6. Selezionare l’app e scegliere Seleziona.

7. Seleziona Rivedi + assegna.

   

8. Dopo aver completato le autorizzazioni di installazione di Active Directory e per l’area di lavoro, richiedere un token di autorizzazione.

Nota

Per questo esempio è stato applicato il ruolo Lettore. Questo è uno dei molti ruoli predefiniti e può includere più autorizzazioni di quelle necessarie. È possibile creare ruoli e autorizzazioni più granulari. Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro Log Analytics.

Richiesta di un token di autorizzazione.

Prima di iniziare, assicurarsi di disporre di tutti i valori necessari per eseguire correttamente la richiesta. Tutte le richieste necessitano di:

• ID tenant di Microsoft Entra.
• ID area di lavoro.
• ID client Microsoft Entra per l'app.
• Segreto client Microsoft Entra per l'app.

L'API Log Analytics supporta l'autenticazione di Microsoft Entra con tre diversi flussi di Microsoft Entra ID OAuth2:

• Credenziali del client
• Codice di autorizzazione
• Implicito

Flusso di credenziali client

Nel flusso delle credenziali client, il token viene usato con l'endpoint di Log Analytics. Viene effettuata una singola richiesta per ricevere un token usando le credenziali fornite per l'app nel passaggio precedente quando si registra un'app in Microsoft Entra ID.

Usare resource=https://api.loganalytics.azure.com.

Ottenere un token di autenticazione utilizzando uno dei metodi seguenti:

• CLI
• REST API
• SDK

Quando si richiede un token, è necessario specificare un parametro resource. Il parametro resource è l'URL della risorsa a cui si vuole accedere.

Le risorse includono:

• https://management.azure.com
• https://api.loganalytics.io
• https://monitoring.azure.com

REST

Ottenere un token usando una richiesta REST

Usare la chiamata API REST seguente per ottenere un token. Questa richiesta usa un ID client e un segreto client per autenticare la richiesta. L'ID client e il segreto client vengono ottenuti quando si registra l'applicazione con Microsoft Entra ID. Per altre informazioni, vedere Registrare un'app per richiedere token di autorizzazione e usare le API

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

Il corpo della risposta viene visualizzato nel formato seguente:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

CLI

Ottenere un token tramite Azure CLI

Per ottenere un token con CLI, è possibile utilizzare il seguente comando

az account get-access-token 

Per altre informazioni, vedere az account get-access-token

SDK

Ottenere un token tramite SDK

Gli esempi di codice seguenti mostrano come ottenere un token tramite:

• C#
• NodeJS
• Python

C#

Il codice seguente mostra come ottenere un token tramite Azure. Raccolta identità Richiede un ID client e un segreto client per autenticare la richiesta.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

In alternativa, è possibile usare la classe DefaultAzureCredential per ottenere un token. Questo metodo utilizza le credenziali di Azure predefinite per autenticare la richiesta e non richiede un ID client o un segreto client.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Inoltre, è possibile specificare l'identità gestita o le credenziali dell'entità servizio come indicato di seguito:

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Per altre informazioni, vedere Classe DefaultAzureCredential

Node.js

Per informazioni sull'uso dell'autenticazione con JavaScript e NodeJS, vedere Come autenticare le app JavaScript nei servizi di Azure usando Azure SDK per JavaScript

Il codice seguente mostra come ottenere un token tramite la classe DefaultAzureCredential. Questo metodo utilizza le credenziali di Azure predefinite per autenticare la richiesta e non richiede un ID client o un segreto client.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

Inoltre, è possibile usare la classe InteractiveBrowserCredential per ottenere le credenziali. Questo metodo offre un'esperienza di autenticazione basata su browser per consentire agli utenti di eseguire l'autenticazione con i servizi di Azure.

Per altre informazioni, vedere Classe DefaultAzureCredential e Classe InteractiveBrowserCredential

In alternativa, è possibile usare la classe ClientSecretCredential per ottenere un token. Questo metodo richiede un ID client e un segreto client per autenticare la richiesta.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Per altre informazioni, vedere Classe ClientSecretCredential

Python

Il codice seguente mostra come ottenere un token tramite la classe DefaultAzureCredential. Questo metodo utilizza le credenziali di Azure predefinite per autenticare la richiesta e non richiede un ID client o un segreto client.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Inoltre, è possibile usare la classe InteractiveBrowserCredential per ottenere le credenziali. Questo metodo offre un'esperienza di autenticazione basata su browser per consentire agli utenti di eseguire l'autenticazione con i servizi di Azure.

Per altre informazioni, vedere Classe DefaultAzureCredential e Classe InteractiveBrowserCredential

In alternativa, è possibile usare la classe ClientSecretCredential per ottenere un token. Questo metodo richiede un ID client e un segreto client per autenticare la richiesta.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Per altre informazioni, vedere Classe ClientSecretCredential

Usare il token nelle richieste all'endpoint di Log Analytics:

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

Esempio di risposta:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

Flusso del codice di autorizzazione

Il flusso OAuth2 principale supportato è tramite codici di autorizzazione. Questo metodo richiede due richieste HTTP per acquisire un token con cui chiamare l'API Log Analytics di Monitoraggio di Azure. Sono disponibili due URL, con un endpoint per ogni richiesta. I rispettivi formati sono descritti nelle sezioni seguenti.

Codice di autorizzazione URL (richiesta GET)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Quando viene effettuata una richiesta all'URL di autorizzazione, il client_id è l'ID applicazione dell'app Microsoft Entra copiato dal menu delle proprietà dell'app. Il redirect_uri è l'URL della home page/login della stessa app Microsoft Entra. Quando una richiesta ha esito positivo, questo endpoint reindirizza l'utente alla pagina di accesso fornita all'iscrizione con il codice di autorizzazione aggiunto all'URL. Vedere l'esempio seguente:

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

A questo punto, si è ottenuto un codice di autorizzazione, che serve ora per richiedere un token di accesso.

URL del token del codice di autorizzazione (richiesta POST)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Tutti i valori sono uguali a prima, con alcune aggiunte. Il codice di autorizzazione è lo stesso codice ricevuto nella richiesta precedente dopo un reindirizzamento riuscito. Il codice viene combinato con la chiave ottenuta dall'app Microsoft Entra. Se la chiave non è stata salvata, è possibile eliminarla e crearne una nuova dalla scheda chiavi del menu dell'app Microsoft Entra. La risposta è una stringa JSON che contiene il token con lo schema seguente. I tipi sono indicati per i valori del token.

Esempio di risposta:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

La parte del token di accesso di questa risposta è ciò che si presenta all'API Log Analytics nell'intestazione Authorization: Bearer. Inoltre, è possibile usare il token di aggiornamento in futuro per acquisire un nuovo access_token e refresh_token quando i dati non sono più aggiornati. Per questa richiesta, il formato e l'endpoint sono:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Esempio di risposta:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

Flusso di codice implicito

L'API Log Analytics supporta il flusso implicito OAuth2. Per questo flusso è necessaria solo una singola richiesta, ma non è possibile acquisire alcun token di aggiornamento.

URL di autorizzazione del codice implicito

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Una richiesta con esito positivo genera un reindirizzamento all'URI di reindirizzamento con il token nell'URL:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

Questo access_token può essere usato come valore dell'intestazione Authorization: Bearer quando viene passato all'API di Log Analytics per autorizzare le richieste.

Ulteriori informazioni

La documentazione su OAuth2 con Microsoft Entra è disponibile qui:

• Flusso di codice di autorizzazione di Microsoft Entra
• Flusso di concessione implicita di Microsoft Entra
• Flusso delle credenziali client di Microsoft Entra S2S

Passaggi successivi

• Formato della richiesta
• Formato della risposta
• Log di query per le risorse di Azure
• Invio di query in batch