访问 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 注册客户端应用并请求令牌。
在应用的概述页面中,选择“API 权限”。
选择“添加权限”。
在“我的组织使用的 API”选项卡中,搜索“日志分析”,然后从列表中选择“Log Analytics API”。
选择“委托的权限”。
选中“Data.Read”复选框。
选择“添加权限”。
现在,应用已注册完成并有权使用 API,接下来可以授予该应用对 Log Analytics 工作区的访问权限。
在 Log Analytics 工作区概述页中,选择“访问控制(IAM)”。
选择“添加角色分配”。
选择“读取者”角色,然后选择“成员”。
在“成员”选项卡上,选择“选择成员”。
在“选择”框中,输入应用的名称。
选择应用,然后选择“选择”。
选择“查看 + 分配”。
完成 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 的文档: