Accéder à l’API Log Analytics Azure Monitor

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.

   

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

6. Cochez la case Data.Read.

7. Sélectionnez Ajouter des autorisations.

   

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.

   

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

   

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.

   

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.

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

Obtenez un jeton d’authentification à l’aide de l’une des méthodes suivantes :

• INTERFACE DE LIGNE DE COMMANDE
• API REST
• Kit SDK

Lors de la demande d’un jeton, vous devez fournir un paramètre resource. Le paramètre resource est l’URL de la ressource que vous souhaitez accéder.

Les ressources incluent :

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

REST

Obtenir un jeton à l’aide d’une requête REST

Utilisez l’appel d’API REST suivant pour obtenir un jeton. Cette demande utilise un ID client et une clé secrète client pour authentifier la demande. L’ID client et la clé secrète client sont obtenus lorsque vous inscrivez votre application auprès de Microsoft Entra ID. Pour plus d’informations, voir Inscrire une application pour demander des jetons d’autorisation et utiliser des 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'

Le corps de la réponse apparaît au format suivant :

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

INTERFACE DE LIGNE DE COMMANDE

Obtenir un jeton à l’aide d’Azure CLI

Pour obtenir un jeton à l’aide de l’interface CLI, vous pouvez utiliser la commande suivante

az account get-access-token 

Pour plus d’informations, consultez az account get-access-token

Kit de développement logiciel (SDK)

Obtenir un jeton à l’aide des Kits de développement logiciel (SDK)

Les exemples de code suivants montrent comment obtenir un jeton à l’aide de :

• C#
• NodeJS
• Python

C#

Le code suivant montre comment obtenir un jeton à l’aide d’Azure. La bibliothèque d’identités nécessite un ID client et une clé secrète client pour authentifier la demande.

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;

Vous pouvez également utiliser la classe DefaultAzureCredential pour obtenir un jeton. Cette méthode utilise les informations d’identification Azure par défaut pour authentifier la demande et ne nécessite pas d’ID client ou de clé secrète client.

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

Vous pouvez également spécifier vos informations d’identification d’identité managée ou de principal de service comme suit :

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

Pour plus d’informations, consultez la classe DefaultAzureCredential

Node.JS

Pour plus d’informations sur l’authentification, utilisez JavaScript et NodeJS, consultez Comment authentifier des applications JavaScript auprès des services Azure à l’aide du Kit de développement logiciel (SDK) Azure pour JavaScript

Le code suivant montre comment obtenir un jeton à l’aide de la classe DefaultAzureCredential. Cette méthode utilise les informations d’identification Azure par défaut pour authentifier la demande et ne nécessite pas d’ID client ou de clé secrète client.

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

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

Vous pouvez également utiliser la classe InteractiveBrowserCredential pour obtenir les informations d’identification. Cette méthode offre une expérience d’authentification basée sur un navigateur pour que les utilisateurs s’authentifient auprès des services Azure.

Pour plus d’informations, consultez la classe DefaultAzureCredential et la classe InteractiveBrowserCredential

Vous pouvez également utiliser la classe ClientSecretCredential pour obtenir un jeton. Cette méthode nécessite un ID client et une clé secrète client pour authentifier la demande.

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");

Pour plus d’informations, consultez la classe ClientSecretCredential

Python

Le code suivant montre comment obtenir un jeton à l’aide de la classe DefaultAzureCredential. Cette méthode utilise les informations d’identification Azure par défaut pour authentifier la demande et ne nécessite pas d’ID client ou de clé secrète client.

from azure.identity import DefaultAzureCredential

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

Vous pouvez également utiliser la classe InteractiveBrowserCredential pour obtenir les informations d’identification. Cette méthode offre une expérience d’authentification basée sur un navigateur pour que les utilisateurs s’authentifient auprès des services Azure.

Pour plus d’informations, consultez la classe DefaultAzureCredential et la classe InteractiveBrowserCredential

Vous pouvez également utiliser la classe ClientSecretCredential pour obtenir un jeton. Cette méthode nécessite un ID client et une clé secrète client pour authentifier la demande.

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)

Pour plus d’informations, consultez la classe ClientSecretCredential

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 :

• Flux de code d’autorisation Microsoft Entra
• Flux d’octroi implicite Microsoft Entra
• Flux d’informations d’identification du client S2S Microsoft Entra

Étapes suivantes

• Format de la demande
• Format de la réponse
• Requêtes de ressources Azure dans les journaux
• Traitement par lot des requêtes