你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

访问 Azure Monitor Log Analytics API

可以使用 Azure Monitor Log Analytics 终结点 https://api.loganalytics.azure.com 将查询请求提交到工作区。 若要访问终结点，必须通过 Microsoft Entra ID 进行身份验证。

注意

将终结点 api.loganalytics.io 替换为 api.loganalytics.azure.com。 在可预见的将来，api.loganalytics.io 终结点将继续受支持。

使用演示 API 密钥进行身份验证

若要在不使用 Microsoft Entra 身份验证的情况下快速浏览 API，请使用包含示例数据的演示工作区，因为它支持 API 密钥身份验证。

要对示例工作区进行身份验证和运行查询，请使用 DEMO_WORKSPACE 作为 {workspace-id} 并传入 API 密钥 DEMO_KEY。

如果应用程序 ID 或 API 密钥不正确，API 服务会返回 403（禁止）错误。

API 密钥 DEMO_KEY 可以通过三种不同的方式传递，具体取决于你是希望使用标头、URL 还是基本身份验证：

• 自定义标头：在自定义标头 X-Api-Key 中提供 API 密钥。
• 查询参数：在 URL 参数 api_key 中提供 API 密钥。
• 基本身份验证：提供 API 密钥作为用户名或密码。 如果同时提供这两个，则 API 密钥必须位于用户名中。

下面的示例在标头中使用工作区 ID 和 API 密钥：

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

公共 API 终结点

公共 API 终结点是：

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

其中：

• api-version：API 版本。 当前版本为“v1”。
• workspaceId：你的工作区 ID。

查询在请求正文中传递。

例如：

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

设置身份验证

若要访问 API，请向 Microsoft Entra ID 注册客户端应用并请求令牌。

1. 在 Microsoft Entra ID 中注册应用。

2. 在应用的概述页面中，选择“API 权限”。

3. 选择“添加权限”。

4. 在“我的组织使用的 API”选项卡中，搜索“日志分析”，然后从列表中选择“Log Analytics API”。

   

5. 选择“委托的权限”。

6. 选中“Data.Read”复选框。

7. 选择“添加权限”。

   

现在，应用已注册完成并有权使用 API，接下来可以授予该应用对 Log Analytics 工作区的访问权限。

1. 在 Log Analytics 工作区概述页中，选择“访问控制(IAM)”。

2. 选择“添加角色分配”。

   

3. 选择“读取者”角色，然后选择“成员”。

   

4. 在“成员”选项卡上，选择“选择成员”。

5. 在“选择”框中，输入应用的名称。

6. 选择应用，然后选择“选择”。

7. 选择“查看 + 分配”。

   

8. 完成 Active Directory 设置和工作区权限事项后，请求获取授权令牌。

注意

在此示例中，我们应用了“读取者”角色。 此角色是许多内置角色之一，可能包含超过所需的权限。 可以创建更精细的角色和权限。 有关详细信息，请参阅管理对 Log Analytics 工作区的访问权限。

请求获取授权令牌

在开始之前，请确保你拥有成功进行请求所需的所有值。 所有请求都需要：

• Microsoft Entra 租户 ID。
• 你的工作区 ID。
• 应用的 Microsoft Entra 客户端 ID。
• 应用的 Microsoft Entra 客户端密码。

Log Analytics API 通过三种不同的 Microsoft Entra ID OAuth2 流支持 Microsoft Entra 身份验证：

• 客户端凭据
• 授权代码
• 隐式

客户端凭据流

在客户端凭据流中，令牌用于 Log Analytics 终结点。 使用上述在 Microsoft Entra ID 中注册应用的步骤中为应用提供的凭据，发出单个请求来接收令牌。

使用 resource=https://api.loganalytics.azure.com。

使用以下任一方法获取身份验证令牌：

• CLI
• REST API
• SDK

在请求令牌时，必须提供 resource 参数。 resource 参数是你要访问的资源的 URL。

资源包括：

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

REST

使用 REST 请求获取令牌

使用以下 REST API 调用来获取令牌。 此请求使用客户端 ID 和客户端密码对请求进行身份验证。 客户端 ID 和客户端密码是在你向 Microsoft Entra ID 注册应用程序时获取的。 有关详细信息，请参阅注册应用以请求授权令牌并使用 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'

响应正文格式如下：

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

使用 Azure CLI 获取令牌

若要使用 CLI 获取令牌，可以使用以下命令

az account get-access-token 

有关详细信息，请参阅 az account get-access-token

SDK

使用 SDK 获取令牌

以下代码示例演示了如何使用以下语言获取令牌：

• C#
• NodeJS
• Python

C#

以下代码示例演示了如何使用 Azure 获取令牌。 标识库 它需要使用客户端 ID 和客户端密码对请求进行身份验证。

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;

另外，你也可以使用 DefaultAzureCredential 类来获取令牌。 此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

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

还可以如下所示指定托管标识或服务主体凭据：

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

有关详细信息，请参阅 DefaultAzureCredential 类

Node.js

有关使用 JavaScript 和 NodeJS 进行身份验证的信息，请参阅如何使用 Azure SDK for JavaScript 向 Azure 服务证明 JavaScript 应用的身份

以下示例演示了如何使用 DefaultAzureCredential 类获取令牌。 此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

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

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

你还可以使用 InteractiveBrowserCredential 类来获取凭据。 此方法提供了基于浏览器的身份验证体验供用户用来向 Azure 服务进行身份验证。

有关详细信息，请参阅 DefaultAzureCredential 类 和 InteractiveBrowserCredential 类

另外，你也可以使用 ClientSecretCredential 类来获取令牌。 此方法需要使用客户端 ID 和客户端密码对请求进行身份验证。

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

有关详细信息，请参阅 ClientSecretCredential 类

Python

以下示例演示了如何使用 DefaultAzureCredential 类获取令牌。 此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

from azure.identity import DefaultAzureCredential

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

你还可以使用 InteractiveBrowserCredential 类来获取凭据。 此方法提供了基于浏览器的身份验证体验供用户用来向 Azure 服务进行身份验证。

有关详细信息，请参阅 DefaultAzureCredential 类 和 InteractiveBrowserCredential 类

另外，你也可以使用 ClientSecretCredential 类来获取令牌。 此方法需要使用客户端 ID 和客户端密码对请求进行身份验证。

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)

有关详细信息，请参阅 ClientSecretCredential 类

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

示例响应:

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

授权代码流

支持的主要 OAuth2 流是通过授权代码实现的。 此方法需要两个 HTTP 请求来获取用于调用 Azure Monitor Log Analytics API 的令牌。 有两个 URL，每个请求对应一个终结点。 后续章节将介绍其格式。

授权代码 URL（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

向授权 URL 发出请求时，client_id 是 Microsoft Entra 应用的应用程序 ID（从应用的属性菜单中复制）。 redirect_uri 是来自同一 Microsoft Entra 应用的主页/登录 URL。 请求成功时，此终结点会将你重定向到你在注册时提供的登录页，并将授权代码追加到 URL。 请参阅以下示例：

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

此时，你已获得授权代码，现在需要使用该代码来请求访问令牌。

授权代码令牌 URL（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>

所有值都与以前相同，只是增加了一些值。 该授权代码与在成功重定向后在上一个请求中收到的代码相同。 该代码与从 Microsoft Entra 应用获取的密钥结合在一起。 如果未保存该密钥，可将其删除，并从 Microsoft Entra 应用菜单的“密钥”选项卡中创建一个新密钥。 响应是包含具有以下架构的令牌的 JSON 字符串。 为令牌值指明了类型。

响应示例：

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

此响应的访问令牌部分是在 Authorization: Bearer 标头中提供给 Log Analytics API 的内容。 将来如果令牌过时，还可以使用刷新令牌来获取新的 access_token 和 refresh_token。 对于此请求，格式和终结点为：

    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>

响应示例：

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

隐式代码流

Log Analytics API 还支持 OAuth2 隐式流。 对于此流，只需要单个请求，但无法获取刷新令牌。

隐式代码授权 URL

    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

成功的请求将使用 URL 中的令牌生成到你的重定向 URI 的重定向：

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

此 access_token 在传递给 Log Analytics API 以授权请求时可用作 Authorization: Bearer 标头值。

更多信息

可以在此处找到有关使用 Microsoft Entra 的 OAuth2 的文档：

• Microsoft Entra 授权代码流
• Microsoft Entra 隐式授权流
• Microsoft Entra S2S 客户端凭据流

后续步骤

• 请求格式
• 响应格式
• 查询 Azure 资源的日志
• 批处理查询