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

根据你的业务需求,可以在解决方案中包含一个或多个用来与 Azure 时序见解环境的 API 交互的客户端应用程序。 Azure 时序见解使用基于 OAUTH 2.0 的 Azure AD 安全令牌执行身份验证。 若要对客户端进行身份验证,需要获取一个拥有适当权限的持有者令牌,并将其与 API 调用一起传递。 本文档介绍几种获取凭据(可用于获取持有者令牌和进行身份验证)的方法,包括使用托管标识和 Azure Active Directory 应用注册。

托管标识

以下部分介绍如何使用 Azure Active Directory (Azure AD) 中的托管标识来访问 Azure 时序见解 API。 在 Azure 上,托管标识可为 Azure AD 中的 Azure 资源提供标识并使用它来获取 Azure Active Directory (Azure AD) 令牌,从而使开发人员无需管理凭据。 下面是使用托管标识的一些好处:

  • 你无需管理凭据, 而且你甚至可能都无法访问凭据。
  • 可以使用托管标识向支持 Azure AD 身份验证的任何 Azure 服务(包括 Azure Key Vault)进行身份验证。
  • 无需额外付费也可使用托管标识。

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

可在以下位置使用托管标识:

  • Azure VM
  • Azure 应用服务
  • Azure Functions
  • Azure 容器实例
  • 等等

有关完整列表,请参阅支持 Azure 资源托管标识的 Azure 服务

Azure Active Directory 应用注册

我们建议尽可能地使用托管标识,这样就无需管理凭据。 如果客户端应用程序不是承载在支持托管标识的 Azure 服务中,你可以将该应用程序注册到 Azure AD 租户。 将应用程序注册到 Azure AD 时,需要创建应用程序的标识配置,使其能够与 Azure AD 集成。 在 Azure 门户中注册应用时,可以选择单租户(只能在自己的租户中访问)或多租户(可在其他租户中访问),也可以选择设置重定向 URI(将访问令牌发送到的位置)。

完成应用注册后,你将拥有应用(应用程序对象)的全局唯一实例,该实例存在于你的主租户或目录中。 而且你的应用拥有全局唯一 ID(应用或客户端 ID)。 然后,在门户中,你便可以添加机密或证书和作用域以使应用正常工作,在登录对话框中自定义应用的品牌等等。

如果在门户中注册应用程序,会在主租户中自动创建应用程序对象以及服务主体对象。 如果使用 Microsoft Graph API 注册/创建应用程序,则通过一个单独步骤创建服务主体对象。 需要创建一个服务主体对象才能请求令牌。

请务必查看应用程序的安全查检表。 作为最佳做法,应使用证书凭据,而不要使用密码凭据(客户端机密)。

有关详细信息,请参阅 Azure Active Directory 中的应用程序对象和服务主体对象

步骤 1:创建托管标识或应用注册

在确定是要使用托管标识还是应用注册后,下一步是预配一个托管标识或应用注册。

托管标识

用于创建托管标识的步骤根据代码所在的位置,以及是要创建系统分配的标识还是用户分配的标识而异。 请参阅托管标识类型了解差异。 选择标识类型后,在 Azure AD 托管标识文档中找到并遵循适当的教程。 在此教程中可以找到有关如何为以下资源配置托管标识的说明:

应用程序注册

遵循注册应用程序中列出的步骤。

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

    • “重定向 URI”必须与身份验证请求所提供的地址相匹配:

      • 对于本地开发环境中托管的应用,请选择“公共客户端(移动和桌面)”。 确保将“公共客户端”设为“是”。
      • 对于 Azure 应用服务上托管的单页应用,请选择“Web”。
    • 确定“注销 URL”是否合适。

    • 通过选中“访问令牌”或“ID 令牌”来启用隐式授权流。

    创建重定向 URI

    单击“配置”,然后单击“保存”。

  • 将 Azure Active Directory 应用与 Azure 时序见解关联。 依次选择“API 权限” > “添加权限” > “我的组织使用的 API”。

    将 API 与 Azure Active Directory 应用相关联

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

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

    指定你的应用所需的 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//.default
  • https://api.timeseries.azure.cn/ 有效,但 https://api.timeseries.azure.cn 无效。

托管标识

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

对于 .NET 应用程序和函数,使用托管标识的最简单方式是通过适用于 .NET 的 Azure 标识客户端库来使用。 此客户端库具有简单安全的优势,因此非常流行。 开发人员可以编写代码一次,并让客户端库确定如何基于应用程序环境进行身份验证 - 无论是在开发人员工作站上的环境中使用开发人员的帐户进行身份验证,还是在部署到 Azure 的环境中使用托管服务标识进行身份验证。

使用 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;

应用注册

可以在许多应用场景中使用 MSAL,包括但不限于:

有关演示如何获取用作应用注册的令牌以及从 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 环境,可以对 WarmStoreColdStore 执行查询。 查询中的此参数定义应对哪个存储执行查询。 如果未定义,将对 Cold 存储区执行查询。 若要查询 Warm 存储,需要将 storeType 设置为 WarmStore。 如果未定义,将对 Cold 存储区执行查询。 Gen2

后续步骤