Access the Azure Monitor Log Analytics API

Article
07/29/2024

You can submit a query request to a workspace by using the Azure Monitor Log Analytics endpoint https://api.loganalytics.azure.cn. To access the endpoint, you must authenticate through Microsoft Entra ID.

Note

The api.loganalytics.io endpoint is being replaced by api.loganalytics.azure.cn. The api.loganalytics.io endpoint will continue to be supported for the forseeable future.

Authenticate with a demo API key

To quickly explore the API without Microsoft Entra authentication, use the demonstration workspace with sample data, which supports API key authentication.

To authenticate and run queries against the sample workspace, use DEMO_WORKSPACE as the {workspace-id} and pass in the API key DEMO_KEY.

If either the Application ID or the API key is incorrect, the API service returns a 403 (Forbidden) error.

The API key DEMO_KEY can be passed in three different ways, depending on whether you want to use a header, the URL, or basic authentication:

Custom header: Provide the API key in the custom header X-Api-Key.
Query parameter: Provide the API key in the URL parameter api_key.
Basic authentication: Provide the API key as either username or password. If you provide both, the API key must be in the username.

This example uses the workspace ID and API key in the header:

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

Public API endpoint

The public API endpoint is:

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

where:

api-version: The API version. The current version is "v1."
workspaceId: Your workspace ID.

The query is passed in the request body.

For example:

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

Set up authentication

To access the API, you register a client app with Microsoft Entra ID and request a token.

Register an app in Microsoft Entra ID.
On the app's overview page, select API permissions.
Select Add a permission.
On the APIs my organization uses tab, search for Log Analytics and select Log Analytics API from the list.
Select Delegated permissions.
Select the Data.Read checkbox.
Select Add permissions.

Now that your app is registered and has permissions to use the API, grant your app access to your Log Analytics workspace.

From your Log Analytics workspace overview page, select Access control (IAM).
Select Add role assignment.
Select the Reader role and then select Members.
On the Members tab, choose Select members.
Enter the name of your app in the Select box.
Select your app and choose Select.
Select Review + assign.
After you finish the Active Directory setup and workspace permissions, request an authorization token.

Note

For this example, we applied the Reader role. This role is one of many built-in roles and might include more permissions than you require. More granular roles and permissions can be created. For more information, see Manage access to Log Analytics workspaces.

Request an authorization token

Before you begin, make sure you have all the values required to make the request successfully. All requests require:

Your Microsoft Entra tenant ID.
Your workspace ID.
Your Microsoft Entra client ID for the app.
A Microsoft Entra client secret for the app.

The Log Analytics API supports Microsoft Entra authentication with three different Microsoft Entra ID OAuth2 flows:

Client credentials
Authorization code
Implicit

Client credentials flow

In the client credentials flow, the token is used with the Log Analytics endpoint. A single request is made to receive a token by using the credentials provided for your app in the previous step when you register an app in Microsoft Entra ID.

Use resource=https://api.loganalytics.azure.cn.

Get an authentication token using any of the following methods:

CLI
REST API
SDK

When requesting a token, you must provide a resource parameter. The resource parameter is the URL of the resource you want to access.

Resources include:

https://management.chinacloudapi.cn
https://api.loganalytics.io
https://monitoring.azure.cn

Get a token using a REST request

Use the following REST API call to get a token. This request uses a client ID and client secret to authenticate the request. The client ID and client secret are obtained when you register your application with Microsoft Entra ID. For more information, see Register an App to request authorization tokens and work with APIs

curl -X POST 'https://login.partner.microsoftonline.cn/<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.cn'

The response body appears in the following format:

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

Get a token using Azure CLI

To get a token using CLI, you can use the following command

az account get-access-token

For more information, see az account get-access-token

Get a token using the SDKs

The following code samples show how to get a token using:

C#
NodeJS
Python

C#

The following code shows how to get a token using the Azure. Identity library It requires a client ID and client secret to authenticate the request.

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

Alternatively, you can use the DefaultAzureCredential class to get a token. This method uses the default Azure credentials to authenticate the request and doesn't require a client ID or client secret.

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

You can also specify your managed identity or service principal credentials as follows:

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

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

For more information, see DefaultAzureCredential Class

Node.js

For information on authentication use JavaScript and NodeJS, see How to authenticate JavaScript apps to Azure services using the Azure SDK for JavaScript

The following code shows how to get a token using the DefaultAzureCredential class. This method uses the default Azure credentials to authenticate the request and doesn't require a client ID or client secret.

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

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

You can also use the InteractiveBrowserCredential class to get the credentials. This method provides a browser-based authentication experience for users to authenticate with Azure services.

For more information, see DefaultAzureCredential Class and InteractiveBrowserCredential Class

Alternatively you can use the ClientSecretCredential class to get a token. This method requires a client ID and client secret to authenticate the request.

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

For more information, see ClientSecretCredential Class

Python

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.chinacloudapi.cn/.default')
print(token.token)

You can also use the InteractiveBrowserCredential class to get the credentials. This method provides a browser-based authentication experience for users to authenticate with Azure services.

For more information, see DefaultAzureCredential Class and InteractiveBrowserCredential Class

Alternatively you can use the ClientSecretCredential class to get a token. This method requires a client ID and client secret to authenticate the request.

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.chinacloudapi.cn/.default")
print(token.token)

For more information, see ClientSecretCredential Class

Use the token in requests to the Log Analytics endpoint:

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

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

Example response:

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

Authorization code flow

The main OAuth2 flow supported is through authorization codes. This method requires two HTTP requests to acquire a token with which to call the Azure Monitor Log Analytics API. There are two URLs, with one endpoint per request. Their formats are described in the following sections.

Authorization code URL (GET request)

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

When a request is made to the authorize URL, the client_id is the application ID from your Microsoft Entra app, copied from the app's properties menu. The redirect_uri is the homepage/login URL from the same Microsoft Entra app. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:

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

At this point, you've obtained an authorization code, which you need now to request an access token.

Authorization code token URL (POST request)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.partner.microsoftonline.cn
    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>

All values are the same as before, with some additions. The authorization code is the same code you received in the previous request after a successful redirect. The code is combined with the key obtained from the Microsoft Entra app. If you didn't save the key, you can delete it and create a new one from the keys tab of the Microsoft Entra app menu. The response is a JSON string that contains the token with the following schema. Types are indicated for the token values.

Response example:

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

The access token portion of this response is what you present to the Log Analytics API in the Authorization: Bearer header. You can also use the refresh token in the future to acquire a new access_token and refresh_token when yours have gone stale. For this request, the format and endpoint are:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.partner.microsoftonline.cn
    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>

Response example:

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

Implicit code flow

The Log Analytics API supports the OAuth2 implicit flow. For this flow, only a single request is required, but no refresh token can be acquired.

Implicit code authorize URL

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

A successful request produces a redirect to your redirect URI with the token in the URL:

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

This access_token can be used as the Authorization: Bearer header value when it's passed to the Log Analytics API to authorize requests.

More information

You can find documentation about OAuth2 with Microsoft Entra here: