通过

Azure 时序见解 API 的身份验证和授权

  • 项目

注意

时序见解服务将于 2024 年 7 月 7 日停用。 请考虑尽快将现有环境迁移到备用解决方案。 有关弃用和迁移的更多信息，请访问我们的 文档。

根据业务需求，解决方案可能包含一个或多个客户端应用程序，这些客户端应用程序可用于与 Azure 时序见解环境的 API进行交互。 Azure 时序见解使用基于 OAUTH 2.0的 Microsoft Entra 安全令牌执行身份验证。 若要对客户端进行身份验证，需要获取具有适当权限的持有者令牌，并将其与 API 调用一起传递。 本文档描述了几种获取可用于获得持有者令牌和进行身份验证的凭据的方法，包括使用托管身份和 Microsoft Entra 应用注册。

托管身份

以下部分介绍如何使用 Microsoft Entra ID 的托管标识来访问 Azure Time Series Insights API。 在 Azure 上，托管标识通过为 Microsoft Entra ID 中的 Azure 资源提供身份并使用它来获取 Microsoft Entra 令牌，从而消除了开发人员管理凭据的需要。 下面是使用托管标识的若干优势：

  • 无需管理凭据。 你甚至无法访问凭据。
  • 可以使用托管标识向任何支持 Microsoft Entra 身份验证（包括 Azure Key Vault）的 Azure 服务进行身份验证。
  • 可以使用托管标识，无需任何额外费用。

有关两种类型的托管标识的详细信息，请参阅 什么是 Azure 资源的托管标识？

您可以从您的以下项使用托管标识：

  • Azure 虚拟机
  • Azure 应用服务
  • Azure Functions
  • Azure 容器实例
  • 等等...

有关支持 Azure 资源的托管身份的 Azure 服务的完整列表，请参阅 。

Microsoft Entra 应用注册

建议尽可能使用托管标识，以便无需管理凭据。 如果客户端应用程序未托管在支持托管标识的 Azure 服务上，则可以将应用程序注册到 Microsoft Entra 租户。 使用 Microsoft Entra ID 注册应用程序时，将为应用程序创建标识配置，以便与 Microsoft Entra ID 集成。 在 Azure 门户中注册应用时，可以选择是单个租户（只能在租户中访问）还是多租户（在其他租户中可访问），并且可以选择设置重定向 URI（其中将访问令牌发送到）。

完成应用注册后，你拥有位于主租户或目录中的应用（应用程序对象）的全局唯一实例。 你的应用程序也有一个全球唯一的标识符（应用程序或客户端 ID）。 在门户中，可以添加机密或证书和作用域，使应用正常工作，在登录对话框中自定义应用的品牌等。

如果在门户中注册应用程序，则会自动在主租户中创建应用程序对象和服务主体对象。 如果使用 Microsoft Graph API 注册/创建应用程序，则创建服务主体对象是一个单独的步骤。 请求令牌需要服务主体对象。

请务必查看应用程序的 安全 清单。 最佳实践是使用 证书凭据，而不是密码凭据（客户端密钥）。

有关详细信息，请参阅Microsoft Entra ID 中的 应用程序和服务主体对象。

步骤 1：创建托管身份或应用程序注册

确定是使用托管标识还是应用注册，下一步是预配一个。

托管身份

用于创建托管标识的步骤将有所不同，具体取决于代码所在的位置，以及是要创建系统分配的标识还是用户分配的标识。 阅读 托管标识类型 以理解不同之处。 选择标识类型后，请在Microsoft Entra 托管标识 文档中找到并遵循正确的教程。 在此处可以找到如何配置托管身份的详细说明：

应用程序注册

按照 注册应用程序中列出的步骤操作。

  • 在 配置平台 设置的步骤 4 中选择适当的平台后，在用户界面右侧面板中配置 重定向 URI 和 访问令牌。

    • 重定向 URI 必须与认证请求提供的地址匹配：

      • 对于在本地开发环境中托管的应用，请选择 公共客户端（移动 & 桌面）。 请确保将 公共客户端 设置为 “是”。
      • 对于 Azure 应用服务上托管的 Single-Page 应用，请选择 Web。

    • 确定 注销 URL 是否适当。

    • 通过检查 访问令牌 或 ID 令牌来启用隐式授予流。

    创建重定向 URI

    单击 配置，然后 保存。

  • 将你的 Microsoft Entra 应用程序关联到 Azure 时序见解。 选择 API 权限，>添加权限，>我组织使用的 API。

    将 API 与 Microsoft Entra 应用关联

    在搜索栏中键入 Azure Time Series Insights，然后选择 Azure Time Series Insights。

  • 接下来，指定应用所需的类型 API 权限。 默认情况下，将突出显示 委派的权限。 然后选择权限类型，然后选择 添加权限。

    指定应用需要 的 API 权限类型

  • 添加凭据，如果应用程序需要以自己的身份调用环境的 API。 凭据允许应用程序以自身身份进行身份验证，无需在运行时与用户交互。

步骤 2：授予访问权限

当 Azure 时序见解环境收到请求时，首先验证调用方的 Bearer 令牌。 如果验证通过，则调用方已经过身份验证，然后进行另一个检查以确保调用方有权执行请求的操作。 若要授权任何用户或服务主体，必须先通过为其分配“读取者”或“参与者”角色来授予他们对环境的访问权限。

  • 若要通过 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.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

重要

使用 URL 作为资源 ID 时，必须将令牌准确地颁发给 https://api.timeseries.azure.com/。 需要尾部斜杠。

  • 如果使用 Postman，你的 AuthURL 就是：https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ 有效，但 https://api.timeseries.azure.com 无效。

管理身份

从 Azure 应用服务或 Azure Functions 访问时，请按照 获取 Azure 资源的令牌中的指南进行操作。

对于 .NET 应用程序和函数，使用托管标识的最简单方法是通过适用于 .NET 的 Azure 标识客户端库。 由于客户端库的简单性和安全性优势，此客户端库很受欢迎。 开发人员可以编写代码一次，让客户端库确定如何基于应用程序环境进行身份验证 - 无论是在开发人员工作站上使用开发人员帐户还是使用托管服务标识在 Azure 中部署。 有关从前身 AppAuthentication 库迁移到 Azure.Identity 的指南，请阅读 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.com/" }));
var accessToken = token.Token;

应用注册

MSAL 可用于许多应用程序方案，包括但不限于：

有关如何作为应用注册从 Gen2 环境中获取令牌并查询数据的示例 C# 代码，请在 GitHub 上查阅示例应用

重要

如果使用 Azure 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-客户端-应用程序-名称 生成此请求的应用程序的名称。 服务会记录此值。

下面介绍了可选但建议的响应标头。

响应标头 描述
内容类型 仅支持 application/json。
x-ms-request-id 服务器生成的请求 ID。 可用于联系Microsoft调查请求。
x-ms-property-not-found-behavior (属性未找到时的行为) GA API 可选响应标头。 可能的值为 ThrowError（默认值）或 UseNull。

HTTP 参数

提示

在 参考文档中查找有关必需和可选查询信息的更多详细内容。

所需的 URL 查询字符串参数取决于 API 版本。

释放 API 版本值
第一代 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。 第1代
storeType=<storeType> 对于启用了热存储的 Gen2 环境，可以在 WarmStore 或 ColdStore上执行查询。 查询中的此参数定义应在哪个商店执行查询。 如果未定义，查询将在冷存储上执行。 查询暖存储时，storeType 应设置为 WarmStore。 如果未定义，将在冷存储库中执行查询。 Gen2

后续步骤