Azure 时序见解 API 的身份验证和授权
注意
时序见解服务将于 2024 年 7 月 7 日停用。 请考虑尽快将现有环境迁移到备用解决方案。 有关弃用和迁移的详细信息，请访问我们的文档。
根据你的业务需求，可以在解决方案中包含一个或多个用来与 Azure 时序见解环境的 API 交互的客户端应用程序。 Azure 时序见解使用基于 OAUTH 2.0 的 Microsoft Entra 安全令牌执行身份验证。 若要对客户端进行身份验证，需要获取一个拥有适当权限的持有者令牌，并将其与 API 调用一起传递。 本文档介绍几种获取凭据（可用于获取持有者令牌和进行身份验证）的方法，包括使用托管标识和 Microsoft Entra 应用注册。
托管标识
以下部分介绍如何使用 Microsoft Entra ID 中的托管标识来访问 Azure 时序见解 API。 在 Azure 上，托管标识可为 Microsoft Entra ID 中的 Azure 资源提供标识并使用它来获取 Microsoft Entra 令牌，从而使开发人员无需管理凭据。 下面是使用托管标识的一些好处：
- 你无需管理凭据， 而且你甚至可能都无法访问凭据。
- 可以使用托管标识向支持 Microsoft Entra 身份验证的任何 Azure 服务（包括 Azure Key Vault）进行身份验证。
- 无需额外付费也可使用托管标识。
有关这两种类型的托管标识的详细信息，请参阅 Azure 资源托管标识是什么？
可在以下位置使用托管标识：
- Azure VM
- Azure 应用服务
- Azure Functions
- Azure 容器实例
- 等等
有关完整列表，请参阅支持 Azure 资源托管标识的 Azure 服务。
Microsoft Entra 应用注册
我们建议尽可能地使用托管标识，这样就无需管理凭据。 如果客户端应用程序不是托管在支持托管标识的 Azure 服务中，你可以将该应用程序注册到 Microsoft Entra 租户。 将应用程序注册到 Microsoft Entra ID 时，需要创建应用程序的标识配置，使其能够与 Microsoft Entra ID 集成。 在 Azure 门户中注册应用时，可以选择单租户（只能在自己的租户中访问）或多租户（可在其他租户中访问），也可以选择设置重定向 URI（将访问令牌发送到的位置）。
完成应用注册后，你将拥有应用（应用程序对象）的全局唯一实例，该实例存在于你的主租户或目录中。 而且你的应用拥有全局唯一 ID（应用或客户端 ID）。 然后，在门户中，你便可以添加机密或证书和作用域以使应用正常工作，在登录对话框中自定义应用的品牌等等。
如果在门户中注册应用程序，会在主租户中自动创建应用程序对象以及服务主体对象。 如果使用 Microsoft Graph API 注册/创建应用程序，则通过一个单独步骤创建服务主体对象。 需要创建一个服务主体对象才能请求令牌。
请务必查看应用程序的安全查检表。 作为最佳做法，应使用证书凭据，而不要使用密码凭据（客户端机密）。
请参阅 Microsoft Entra ID 中的应用程序和服务主体对象了解更多详细信息。
步骤 1：创建托管标识或应用注册
在确定是要使用托管标识还是应用注册后，下一步是预配一个托管标识或应用注册。
托管标识
用于创建托管标识的步骤根据代码所在的位置，以及是要创建系统分配的标识还是用户分配的标识而异。 请参阅托管标识类型了解差异。 选择标识类型后，在 Microsoft Entra 托管标识文档中找到适当的教程并按照该教程操作。 在此教程中可以找到有关如何为以下资源配置托管标识的说明：
应用程序注册
遵循注册应用程序中列出的步骤。
在配置平台设置的第 4 步中选择适当的平台后，在用户界面右侧的侧面板中配置“重定向 URI”和“访问令牌”。
“重定向 URI”必须与身份验证请求所提供的地址相匹配：
- 对于本地开发环境中托管的应用，请选择“公共客户端(移动和桌面)”。 确保将“公共客户端”设为“是”。
- 对于 Azure 应用服务上托管的单页应用，请选择“Web”。
确定“注销 URL”是否合适。
通过选中“访问令牌”或“ID 令牌”来启用隐式授权流。
单击“配置”，然后单击“保存”。
将 Microsoft Entra 应用与 Azure 时序见解关联。 依次选择“API 权限”“添加权限”“我的组织使用的 API”。
在搜索栏中键入
Azure Time Series Insights，然后选择Azure Time Series Insights。接下来，指定你的应用所需的 API 权限类型。 默认情况下，将突出显示“委派的权限”。 然后，选择一种权限类型，再选择“添加权限”。
如果应用程序将自己调用环境的 API，请添加凭据。 通过凭据，应用程序可以自己的身份进行身份验证，无需用户在运行时进行任何交互。
步骤 2：授予访问权限
当 Azure 时序见解环境收到请求时，首先会验证调用方的持有者令牌。 如果通过了验证，则表示调用方已完成身份验证。接下来会执行另一项检查，以确保调用方已获得执行所请求操作的授权。 若要为任何用户或服务主体授权，必须先为其分配“读取者”或“参与者”角色，以此授予其对环境的访问权限。
若要通过 Azure 门户 UI 授予访问权限，请按照授予对环境的数据访问权限一文中列出的说明操作。 选择用户时，可以按名称或 ID 搜索托管标识或应用注册。
若要使用 Azure CLI 授予访问权限，请运行以下命令。 查看此处的文档获取可用于管理访问权限的完整命令列表。
az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"
注意
Azure CLI 的 timeseriesinsights 扩展需要 2.11.0 或更高版本。 首次运行 az tsi access-policy 命令时，该扩展将自动安装。 详细了解扩展。
步骤 3：请求令牌
预配托管标识或应用注册并为其分配角色后，便可以开始使用它来请求 OAuth 2.0 持有者令牌了。 用于获取令牌的方法根据代码的承载位置以及所选的语言而异。 指定资源（也称为令牌的“受众”）时，可以按照其 URL 或 GUID 来标识 Azure 时序见解：
https://api.timeseries.azure.cn/120d688d-1518-4cf7-bd38-182f158850b6
重要
如果使用 URL 作为资源 ID，则必须将令牌确切地颁发给 https://api.timeseries.azure.cn/。 尾部反斜杠是必需项。
- 如果使用 Postman ，则 AuthURL 相应地是：
https://login.partner.microsoftonline.cn/microsoft.partner.onmschina.cn/oauth2/authorize?scope=https://api.timeseries.azure.cn//.defaulthttps://api.timeseries.azure.cn/有效，但https://api.timeseries.azure.cn无效。
托管标识
从 Azure 应用服务或 Functions 访问时，请按照获取 Azure 资源的令牌中的指导操作。
对于 .NET 应用程序和函数，使用托管标识的最简单方式是通过适用于 .NET 的 Azure 标识客户端库来使用。 此客户端库具有简单安全的优势，因此非常流行。 开发人员可以编写代码一次，并让客户端库确定如何基于应用程序环境进行身份验证 - 无论是在开发人员工作站上的环境中使用开发人员的帐户进行身份验证，还是在部署到 Azure 的环境中使用托管服务标识进行身份验证。 有关从以前的 AppAuthentication 库迁移的指导，请参阅 AppAuthentication 到 Azure.Identity 迁移指南。
使用 C# 和适用于 .NET 的 Azure 标识客户端库请求 Azure 时序见解的令牌：
using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
new[] { "https://api.timeseries.azure.cn/" }));
var accessToken = token.Token;
应用注册
- 使用 Microsoft 身份验证库 (MSAL) 获取应用注册令牌。
可以在许多应用场景中使用 MSAL，包括但不限于：
- 单页应用程序 (JavaScript)
- Web 应用程序登录用户并代表用户调用 web API
- Web API 代表已登录用户调用其他下游 Web API
- 桌面应用程序代表已登录用户调用 Web API
- 代表以交互方式登录的用户调用 Web API 的移动应用程序。
- 桌面/服务守护程序应用程序代表自己调用 Web API
有关演示如何获取用作应用注册的令牌以及从 Gen2 环境查询数据的示例 C# 代码，请查看 GitHub 上的示例应用
重要
如果正在使用 Active Directory 身份验证库 (ADAL)，则迁移到 MSAL。
常用标头和参数
本部分介绍用于对 Azure 时序见解 Gen1 和 Gen2 API 进行查询的常用 HTTP 请求标头和参数。 Azure 时序见解 REST API 参考文档中更详细地介绍了特定于 API 的要求。
提示
阅读 Azure REST API 参考，了解有关如何使用 REST API、发出 HTTP 请求和处理 HTTP 响应的详细信息。
HTTP 标头
必需的请求标头如下所述。
| 必需的请求标头 | 说明 |
|---|---|
| 授权 | 若要使用 Azure 时序见解进行身份验证，必须将有效的 OAuth 2.0 持有者令牌传入授权标头。 |
提示
阅读托管的 Azure 时序见解客户端 SDK 示例可视化，了解如何使用 JavaScript 客户端 SDK 以及图表以编程方式通过 Azure 时序见解 API 进行身份验证。
可选请求标头如下所述。
| 可选请求标头 | 说明 |
|---|---|
| Content-type | 仅支持 application/json。 |
| x-ms-client-request-id | 客户端请求 ID。 服务记录此值。 允许服务跨服务跟踪操作。 |
| x-ms-client-session-id | 客户端会话 ID。 服务记录此值。 允许服务跨服务跟踪一组相关操作。 |
| x-ms-client-application-name | 生成此请求的应用程序的名称。 服务记录此值。 |
可选但建议的响应标头如下所述。
| 响应标头 | 说明 |
|---|---|
| Content-type | 仅支持 application/json。 |
| x-ms-request-id | 服务器生成的请求 ID。 可用于与 Microsoft 联系以调查请求。 |
| x-ms-property-not-found-behavior | GA API 可选响应标头。 可能的值为 ThrowError（默认）或 UseNull。 |
HTTP 参数
提示
如需查找有关必需和可选查询信息的详细信息，请参阅参考文档。
必需的 URL 查询字符串参数依赖于 API 版本。
| 发布 | API 版本值 |
|---|---|
| Gen1 | api-version=2016-12-12 |
| Gen2 | api-version=2020-07-31 |
可选 URL 查询字符串参数包括为 HTTP 请求执行时间设置超时。
| 可选查询参数 | 说明 | 版本 |
|---|---|---|
timeout=<timeout> |
用于执行 HTTP 请求的服务器端超时。 仅适用于获取环境事件和获取环境聚合 API。 超时值应采用 ISO 8601 持续时间格式（例如 "PT20S"），并且应在 1-30 s 范围内。 默认值为 30 s。 |
Gen1 |
storeType=<storeType> |
对于启用了 Warm 存储的 Gen2 环境，可以对 WarmStore 或 ColdStore 执行查询。 查询中的此参数定义应对哪个存储执行查询。 如果未定义，将对 Cold 存储区执行查询。 若要查询 Warm 存储，需要将 storeType 设置为 。 如果未定义，将对 Cold 存储区执行查询。 |
Gen2 |
后续步骤
有关调用 Gen1 Azure 时序见解 API 的示例代码，请参阅使用 C# 查询 Gen1 数据。
有关调用 Gen2 Azure 时序见解 API 示例代码的示例代码，请参阅使用 C# 查询 Gen2 数据。
有关 API 参考信息，请阅读查询 API 参考文档。