访问 Azure Monitor Log Analytics API

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

注意

将终结点 api.loganalytics.io 替换为 api.loganalytics.azure.cn。 在可预见的将来,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.cn/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.cn/{api-version}/workspaces/{workspaceId}

其中:

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

查询在请求正文中传递。

例如:

   https://api.loganalytics.azure.cn/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”。

    屏幕截图显示请求 API 权限页面。

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

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

  7. 选择“添加权限”。

    屏幕截图显示请求 API 权限页面的续页。

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

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

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

    屏幕截图显示 Log Analytics 工作区的“访问控制”页。

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

    屏幕截图显示 Log Analytics 工作区的“添加角色分配”页。

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

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

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

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

    屏幕截图显示 Log Analytics 工作区的“添加角色分配”页上的“选择成员”窗格。

  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.cn

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

  • CLI
  • REST API
  • SDK

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

资源包括:

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

使用 REST 请求获取令牌

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

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

在对 Log Analytics 终结点发出的请求中使用令牌:

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

示例响应:

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

向授权 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.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>

所有值都与以前相同,只是增加了一些值。 该授权代码与在成功重定向后在上一个请求中收到的代码相同。 该代码与从 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.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>

响应示例:

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

成功的请求将使用 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 的文档:

后续步骤