Share via

Accesso all'API analisi dei log di Monitoraggio di Azure

  • Articolo

È possibile inviare una richiesta di query a un'area di lavoro usando l'endpoint https://api.loganalytics.azure.comdi 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 futuro possibile.

Eseguire l'autenticazione con una chiave API demo

Per esplorare rapidamente l'API senza l'autenticazione di Microsoft Entra, usare 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 DEMO_KEYAPI .

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

La chiave DEMO_KEY API 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 di query: specificare la chiave API nel parametro api_keyURL .
  • 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 usa 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 dell'area 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"
   }

Configurare l'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 un'autorizzazione.

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

    A screenshot that shows the Request API permissions page.

  5. Seleziona Autorizzazioni delegate.

  6. Selezionare la casella di controllo Data.Read .

  7. Selezionare Aggiungi autorizzazioni.

    A screenshot that shows the continuation of the Request API permissions page.

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 dell'area di lavoro Log Analytics selezionare Controllo di accesso (IAM).

  2. Selezionare Aggiungi un'assegnazione di ruolo.

    A screenshot that shows the Access control page for a Log Analytics workspace.

  3. Selezionare il ruolo Lettore e quindi Selezionare Membri.

    A screenshot that shows the Add role assignment page for a Log Analytics workspace.

  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.

    A screenshot that shows the Select members pane on the Add role assignment page for a Log Analytics workspace.

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

Nota

Per questo esempio è stato applicato il ruolo Lettore. Questo ruolo è 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 alle aree di lavoro Log Analytics.

Richiedere un token di autorizzazione

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

  • ID tenant di Microsoft Entra.
  • ID dell'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 OAuth2 di Microsoft Entra ID:

  • 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 l'endpoint https://api.loganalytics.azure.com .

URL del token delle credenziali client (richiesta POST)

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

Una richiesta con esito positivo riceve un token di accesso nella risposta:

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

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 i 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 relativi formati sono descritti nelle sezioni seguenti.

URL del codice di autorizzazione (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, è stato ottenuto un codice di autorizzazione, che è ora necessario 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 . È anche 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 di Authorization: Bearer intestazione quando viene passato all'API di Log Analytics per autorizzare le richieste.

Altre informazioni

La documentazione su OAuth2 con Microsoft Entra è disponibile qui:

Passaggi successivi