Share via

Accéder à l’API Log Analytics Azure Monitor

  • Article

Vous pouvez envoyer une requête à un espace de travail en utilisant le point de terminaison Azure Monitor Log Analytics https://api.loganalytics.azure.com. Pour accéder au point de terminaison, vous devez vous authentifier via Microsoft Entra ID.

Remarque

Le point de terminaison api.loganalytics.io est remplacé par api.loganalytics.azure.com. Le point de terminaison api.loganalytics.io restera pris en charge pendant quelques temps.

Authentification avec une clé API de version de démonstration

Pour explorer rapidement l’API sans authentification Microsoft Entra, utilisez l’espace de travail de démonstration avec des échantillons de données, qui prend en charge l’authentification par clé API.

Pour authentifier et exécuter des requêtes sur l’exemple d’espace de travail, utilisez DEMO_WORKSPACE comme {workspace-id} et transmettez la clé API DEMO_KEY.

Si l’ID d’application ou la clé API est incorrect, le service d’API retourne une erreur 403 (interdit).

La clé API DEMO_KEY peut être transmise de trois façons différentes, selon que vous souhaitez utiliser un en-tête, l’URL ou l’authentification de base :

  • En-tête personnalisé : fournissez la clé API dans l’en-tête personnalisé X-Api-Key.
  • Paramètre de requête : fournissez la clé API dans le paramètre d’URL api_key.
  • Authentification de base : fournissez la clé API en tant que nom d’utilisateur ou mot de passe. Si vous fournissez les deux, la clé API doit se trouver dans le nom d’utilisateur.

Cet exemple utilise l’ID d’espace de travail et la clé API dans l’en-tête :

    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"
    }

Point de terminaison d’API public

Le point de terminaison d’API public est :

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

où :

  • api-version : version d’API utilisée. La version actuelle est « v1 ».
  • workspaceId : ID de votre espace de travail.

La requête est utilisée dans le corps de la demande.

Par exemple :

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

Configurer l’authentification

Pour accéder à l’API, vous inscrivez une application cliente avec Microsoft Entra ID et demandez un jeton.

  1. Inscrivez une application dans Microsoft Entra ID.

  2. Dans la page de présentation de l’application, sélectionnez Autorisations API.

  3. Sélectionnez Ajouter une autorisation.

  4. Sous l’onglet API que mon organisation utilise, recherchez Log Analytics, puis sélectionnez API Log Analytics dans la liste.

    A screenshot that shows the Request API permissions page.

  5. Sélectionnez Autorisations déléguées.

  6. Cochez la case Data.Read.

  7. Sélectionnez Ajouter des autorisations.

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

Maintenant que votre application est inscrite et autorisée à utiliser l’API, accordez à votre application l’accès à votre espace de travail Log Analytics.

  1. Dans la page de présentation de votre espace de travail Log Analytics, sélectionnez Contrôle d’accès (IAM).

  2. Sélectionnez Ajouter une attribution de rôle.

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

  3. Sélectionnez le rôle Lecteur, puis sélectionnez Membres.

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

  4. Dans l’onglet Membres, sélectionnez Sélectionner des membres.

  5. Entrez le nom de votre application dans la zone Sélectionner.

  6. Sélectionnez votre application, puis choisissez Sélectionner.

  7. Sélectionnez Vérifier + attribuer.

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

  8. Après avoir terminé la configuration d’Active Directory, puis accordé les autorisations d’accès à l’espace de travail, demandez un jeton d’autorisation.

Notes

Pour cet exemple, nous avons appliqué le rôle Lecteur. Ce rôle est l’un des nombreux rôles intégrés et pourrait inclure des autorisations dont vous n’avez pas besoin. Des rôles et des autorisations plus précis peuvent être créés. Pour plus d’informations, consultez Gérer l’accès aux espaces de travail Log Analytics.

Demander un jeton d’autorisation

Avant de commencer, vérifiez que vous disposez de toutes les valeurs requises pour que la requête aboutisse. Toutes les requêtes nécessitent :

  • Votre ID de locataire Microsoft Entra.
  • Votre ID d’espace de travail.
  • Votre ID client Microsoft Entra pour l’application.
  • Une clé secrète client Microsoft Entra pour l’application.

L’API Log Analytics prend en charge l’authentification Microsoft Entra avec trois flux différents Microsoft Entra OAuth2 :

  • Informations d'identification du client
  • Code d’autorisation.
  • Implicite

Flux des informations d’identification du client

Dans le flux d’informations d’identification du client, le jeton est utilisé avec le point de terminaison Log Analytics. Une seule requête est effectuée pour recevoir un jeton, avec les informations d’identification fournies pour votre application à l’étape précédente lorsque vous inscrivez une application dans Microsoft Entra ID.

Utilisez le point de terminaison https://api.loganalytics.azure.com.

URL du jeton d’informations d’identification du client (requête 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>

Une demande qui aboutit reçoit un jeton d’accès dans la réponse :

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

Utilisez le jeton dans les requêtes adressées au point de terminaison 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"
    }

Exemple de réponse :

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

Flux du code d’autorisation

Le flux OAuth2 principal pris en charge est celui qui fait appel à des codes d’autorisation. Cette méthode nécessite deux requêtes HTTP pour acquérir un jeton avec lequel appeler l’API Log Analytics Azure Monitor. Il y a deux URL, avec un point de terminaison par requête. Ces formats sont décrits dans les sections suivantes.

URL du code d’autorisation (requête 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

Lorsque vous adressez une requête à l’URL d’autorisation, l’ID client (client_id) est l’ID d’application de votre application Microsoft Entra, copié depuis le menu des propriétés de l’application. L’URI de redirection (redirect_uri) est l’URL de connexion/page d’accueil de la même application Microsoft Entra. Quand une demande aboutit, ce point de terminaison vous redirige vers la page de connexion que vous avez fournie à l’inscription avec le code d’autorisation ajouté à l’URL. Voir l’exemple suivant :

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

À ce stade, vous avez obtenu un code d’autorisation, dont vous avez besoin pour demander un jeton d’accès.

URL du jeton de code d’autorisation (requête 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>

Toutes les valeurs sont les mêmes qu’avant, avec quelques ajouts. Le code d’autorisation est le même que celui que vous avez reçu dans la requête précédente après une redirection réussie. Le code est combiné à la clé obtenue à partir de l’application Microsoft Entra. Si vous n’avez pas enregistré la clé, vous pouvez la supprimer, puis en créer une depuis l’onglet Clés du menu de l’application Microsoft Entra. La réponse est une chaîne JSON qui contient le jeton avec le schéma suivant. Les types sont indiqués pour les valeurs de jeton.

Exemple de réponse :

    {
        "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 partie jeton d’accès de cette réponse est celle que vous présentez à l’API Log Analytics dans l'en-tête Authorization: Bearer. Vous pouvez également utiliser le jeton d’actualisation à l’avenir pour acquérir un nouveau jeton d’accès (access_token) et un nouveau jeton d’actualisation (refresh_token) quand les vôtres sont périmés. Pour cette requête, le format et le point de terminaison sont les suivants :

    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>

Exemple de réponse :

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

Flux de code implicite

L’API Log Analytics prend en charge le flux implicite OAuth2. Pour ce processus, une seule requête est requise, mais aucun jeton d’actualisation ne peut être acquis.

URL d’autorisation du code implicite

    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

Une requête qui aboutit produit une redirection vers votre URI de redirection avec le jeton dans l’URL :

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

Ce jeton d’accès (access_token) peut être utilisé comme valeur d’en-tête Authorization: Bearer lorsqu’il est transmis à l’API Log Analytics pour autoriser les requêtes.

Plus d’informations

Vous trouverez la documentation sur OAuth2 avec Microsoft Entra ici :

Étapes suivantes