Azure 时序见解 API 的身份验证和授权Authentication and authorization for Azure Time Series Insights API

本文档介绍如何使用新的 Azure Active Directory 边栏选项卡在 Azure Active Directory 中注册应用。This document describes how to register an app in Azure Active Directory using the new Azure Active Directory blade. 在 Azure Active Directory 中注册的应用可让用户进行身份验证,并有权使用与 Azure 时序见解环境关联的 Azure 时序见解 API。Apps registered in Azure Active Directory enable users to authenticate to and be authorized to use the Azure Time Series Insight API associated with an Azure Time Series Insights environment.

服务主体Service principal

以下部分介绍如何配置一个应用程序,以代表某个应用访问 Azure 时序见解 API。The following sections describe how to configure an application to access the Azure Time Series Insights API on behalf of an app. 然后,该应用程序可以通过 Azure Active Directory 使用自身的应用程序凭据在 Azure 时序见解环境中查询或发布参考数据。The application may then query or publish reference data in the Azure Time Series Insights environment using its own application credentials through Azure Active Directory.

摘要和最佳做法Summary and best practices

Azure Active Directory 应用注册流程涉及三个主要步骤。The Azure Active Directory app registration flow involves three main steps.

  1. 在 Azure Active Directory 中注册应用程序Register an application in Azure Active Directory.
  2. 授权应用程序对 Azure 时序见解环境进行数据访问Authorize the application to have data access to the Azure Time Series Insights environment.
  3. 使用应用程序 ID 和客户端密码从客户端应用中的 https://api.timeseries.azure.cn/ 获取令牌。Use the Application ID and Client Secret to acquire a token from https://api.timeseries.azure.cn/ in your client app. 然后可使用该令牌调用 Azure 时序见解 API。The token can then be used to call the Azure Time Series Insights API.

根据步骤 3,将应用程序凭据和用户凭据隔离可以:Per step 3, separating your application's and your user credentials allows you to:

  • 将权限分配给应用标识,这些权限不同于你自己的权限。Assign permissions to the app identity that are distinct from your own permissions. 通常情况下,这些权限仅限于应用需要的权限。Typically, these permissions are restricted to only what the app requires. 例如,可仅允许应用读取特定 Azure 时序见解环境中的数据。For example, you can allow the app to read data only from a particular Azure Time Series Insights environment.
  • 使用客户端密码或安全证书,将应用安全性与创建用户身份验证凭据的过程相隔离。Isolate the app's security from the creating user's authentication credentials by using a Client Secret or security certificate. 因此,应用程序的凭据不依赖于特定用户的凭据。As a result, the application's credentials are not dependent on a specific user's credentials. 如果用户的角色发生更改,应用程序不一定需要新的凭据或进一步的配置。If the user's role changes, the application does not necessarily require new credentials or further configuration. 如果用户更改了其密码,对应用程序的所有访问都不需要新的凭据或密钥。If the user changes their password, all access to the application doesn't require new credentials or keys.
  • 使用客户端密码或安全证书而不是特定用户的凭据(这需要出示这些凭据)来运行无人参与的脚本。Run an unattended script using a Client Secret or security certificate rather than a specific user's credentials (requiring them to be present).
  • 使用安全证书而不是密码来保护对 Azure 时序见解 API 的访问。Use a security certificate rather than a password to secure access to your Azure Time Series Insights API.

重要

配置 Azure 时序见解安全策略时,请遵循“关注点分离”的原则(在上述方案中已介绍)。Follow the principle of Separation of Concerns (described for this scenario above) when configuring your Azure Time Series Insights security policy.

备注

  • 文中重点介绍了单租户应用程序,其中应用程序只应在一个组织内运行。The article focuses on a single-tenant application where the application is intended to run in only one organization.
  • 通常会将单租户应用程序作为在组织中运行的业务线应用程序使用。You'll typically use single-tenant applications for line-of-business applications that run in your organization.

详细设置Detailed setup

Azure Active Directory 应用注册Azure Active Directory app registration

  1. Azure 门户中,依次选择“Azure Active Directory” > “应用注册” > “新注册”。In the Azure portal, select Azure Active Directory > App registrations > New registration.

    Azure Active Directory 中的新应用程序注册New application registration in Azure Active Directory

    你的应用在注册后将在此处列出。Your app will be listed here after you register it.

  2. 为应用程序提供名称,然后选择“仅此组织目录中的帐户”,以指定可访问 API 的“支持的帐户类型”。Give the application a name and select Accounts in this organizational directory only to specify the Supported account types that may access the API. 选择要在用户进行身份验证后将其重定向到的有效 URI,然后选择“注册”。Choose a valid URI to redirect users to after they authenticate, then Register.

    在 Azure Active Directory 中创建应用程序Create the application in Azure Active Directory

  3. 重要的 Azure Active Directory 应用信息显示在所列应用的“概述”边栏选项卡中。Important Azure Active Directory app information is displayed in your listed app's Overview blade. 在“拥有的应用程序”下,选择你的应用,然后选择“概述”。Select your app under Owned applications, then Overview.

    复制应用程序 IDCopy the application ID

    复制要在客户端应用程序中使用的“应用程序(客户端) ID”。Copy your Application (client) ID to use in your client application.

  4. “身份验证”边栏选项卡可指定重要的身份验证配置设置。The Authentication blade specifies important authentication configuration settings.

    1. 通过选择“+ 添加平台”,添加“重定向 URI”并配置“访问令牌”。Add Redirect URIs and configure Access Tokens by selecting + Add a platform.

    2. 通过选择“是”或“否”,确定应用是否为公共客户端。Determine whether the app is a public client or not by selecting Yes or No.

    3. 确认哪些帐户和租户受支持。Verify which accounts and tenants are supported.

    配置隐式授权Configure Implicit grant

  5. 选择适当的平台后,在用户界面右侧的侧面板中配置“重定向 URI”和“访问令牌”。After selecting the appropriate platform, configure your Redirect URIs and Access Tokens in the side panel to the right of the user interface.

    1. “重定向 URI”必须与身份验证请求所提供的地址相匹配:Redirect URIs must match the address supplied by the authentication request:

      • 对于本地开发环境中托管的应用,请选择“公共客户端(移动和桌面)”。For apps hosted in a local development environment, select Public client (mobile & desktop). 确保将“公共客户端”设为“是”。Make sure to set public client to Yes.
      • 对于 Azure 应用服务上托管的单页应用,请选择“Web”。For Single-Page Apps hosted on Azure App Service, select Web.
    2. 确定“注销 URL”是否合适。Determine whether a Logout URL is appropriate.

    3. 通过选中“访问令牌”或“ID 令牌”来启用隐式授权流。Enable the implicit grant flow by checking Access tokens or ID tokens.

    创建重定向 URICreate Redirect URIs

    单击“配置”,然后单击“保存”。Click Configure, then Save.

  6. 选择“证书和机密” ,然后选择“新建客户端机密”来创建客户端应用可用来证明其身份的应用程序密码。Select Certificates & secrets then New client secret to create an application password that your client app can use to prove its identity.

    创建新客户端机密Create a new client secret

    然后,客户端密钥密码将会显示。Your client secret password will then be displayed. 将密钥复制到喜爱的文本编辑器中。Copy the key to your favorite text editor.

    备注

    可以改为导入证书。You have the ability to import a certificate instead. 为增强安全性,建议使用证书。For enhanced security, a certificate is recommended. 若要使用证书,请选择“上传证书”。To use a certificate, select Upload certificate.

  7. 将 Azure Active Directory 应用与 Azure 时序见解关联。Associate your Azure Active Directory app Azure Time Series Insights. 依次选择“API 权限” > “添加权限” > “我的组织使用的 API”。Select API permissions > Add a permission > APIs my organization uses.

    将 API 与 Azure Active Directory 应用相关联Associate an API with your Azure Active Directory app

    在搜索栏中键入 Azure Time Series Insights,然后选择 Azure Time Series InsightsType Azure Time Series Insights into the search bar then select Azure Time Series Insights.

  8. 接下来,指定你的应用所需的 API 权限类型。Next, specify the kind API permission your app requires. 默认情况下,将突出显示“委派的权限”。By default, Delegated permissions will be highlighted. 然后,选择一种权限类型,再选择“添加权限”。Choose a permission type then, select Add permissions.

    指定你的应用所需的 API 权限类型Specify the kind of API permission your app requires

授予数据访问权限Granting data access

  1. 对于 Azure 时序见解环境,请选择“数据访问策略”,然后选择“添加” 。For the Azure Time Series Insights environment, select Data Access Policies and select Add.

    将新的数据访问策略添加到 Azure 时序见解环境Add new data access policy to the Azure Time Series Insights environment

  2. 在“选择用户”对话框中,粘贴来自 Azure Active Directory 应用注册部分的“应用程序名称”或“应用程序 ID” 。In the Select User dialog box, paste either the Application Name or the Application ID from the Azure Active Directory app registration section.

    在“选择用户”对话框中查找应用程序Find an application in the Select User dialog box

  3. 选择角色。Select the role. 选择“读取者”以查询数据,或选择“参与者”以查询数据和更改参考数据。Select Reader to query data or Contributor to query data and change reference data. 选择“确定”。Select OK.

    在“选择角色”对话框中选择“读取者”或“参与者”Pick Reader or Contributor in the Select User Role dialog box

  4. 通过选择“确定”来保存策略。Save the policy by selecting OK.

    提示

    对于高级数据访问选项,请阅读授予数据访问权限For advanced data access options, read granting data access.

客户端应用初始化Client app initialization

  • 开发人员可以使用 Microsoft 身份验证库 (MSAL) 通过 Azure 时序见解进行身份验证。Developers may use the [Microsoft Authentication Library (MSAL) to authenticate with Azure Time Series Insights.

  • 使用 MSAL 进行身份验证:To authenticate using MSAL:

    1. 使用来自 Azure Active Directory 应用注册部分的“应用程序 ID”和“客户端密码”(应用程序密钥)来代表应用程序获取令牌。Use the Application ID and Client Secret (Application Key) from the Azure Active Directory app registration section to acquire the token on behalf of the application.

    2. 在 C# 中,以下代码可以代表应用程序获取令牌。In C#, the following code can acquire the token on behalf of the application. 有关如何从 Gen1 环境查询数据的完整示例,请参阅使用 C# 查询数据For a complete sample on how to query data from a Gen1 environment, read Query data using C#.

      请参阅 Azure 时序见解存储库以访问 C# 代码。See the Azure Time Series Insights] repo to access the C# code.

    3. 随后可在应用程序调用 Azure 时序见解 API 时,将令牌传入 Authorization 标头。The token can then be passed in the Authorization header when the application calls the Azure Time Series Insights API.

常用标头和参数Common headers and parameters

本部分介绍用于对 Azure 时序见解 Gen1 和 Gen2 API 进行查询的常用 HTTP 请求标头和参数。This section describes common HTTP request headers and parameters used to make queries against the Azure Time Series Insights Gen1 and Gen2 APIs. Azure 时序见解 REST API 参考文档中更详细地介绍了特定于 API 的要求。API-specific requirements are covered in greater detail in the Azure Time Series Insights REST API reference documentation.

提示

阅读 Azure REST API 参考,了解有关如何使用 REST API、发出 HTTP 请求和处理 HTTP 响应的详细信息。Read the Azure REST API Reference to learn more about how to consume REST APIs, make HTTP requests, and handle HTTP responses.

身份验证Authentication

若要对 Azure 时序见解 REST API 执行经过身份验证的查询,必须使用所选的 REST 客户端(Postman、JavaScript、C#)将有效的 OAuth 2.0 持有者令牌传入授权标头To perform authenticated queries against the Azure Time Series Insights REST APIs, a valid OAuth 2.0 bearer token must be passed in the Authorization header using a REST client of your choice (Postman, JavaScript, C#).

提示

阅读托管的 Azure 时序见解客户端 SDK 示例可视化,了解如何使用 JavaScript 客户端 SDK 以及图表和图以编程方式通过 Azure 时序见解 API 进行身份验证。Read the hosted Azure Time Series Insights client SDK sample visualization to learn how to authenticate with the Azure Time Series Insights APIs programmatically using the JavaScript Client SDK along with charts and graphs.

HTTP 标头HTTP headers

必需的请求标头如下所述。Required request headers are described below.

必需的请求标头Required request header 说明Description
授权Authorization 若要使用 Azure 时序见解进行身份验证,必须将有效的 OAuth 2.0 持有者令牌传入“授权”标头。To authenticate with Azure Time Series Insights, a valid OAuth 2.0 Bearer token must be passed in the Authorization header.

重要

令牌必须严格颁发给 https://api.timeseries.azure.cn/ 资源(也称为令牌的“受众”)。The token must be issued exactly to the https://api.timeseries.azure.cn/ resource (also known as the "audience" of the token).

  • 因此,Postman AuthURL 将为:https://login.partner.microsoftonline.cn/microsoft.partner.onmschina.cn/oauth2/authorize?scope=https://api.timeseries.azure.cn/.defaultYour Postman AuthURL will therefore be: 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 无效。https://api.timeseries.azure.cn/ is valid but https://api.timeseries.azure.cn is not.

可选请求标头如下所述。Optional request headers are described below.

可选请求标头Optional request header 说明Description
Content-typeContent-type 仅支持 application/jsononly application/json is supported.
x-ms-client-request-idx-ms-client-request-id 客户端请求 ID。A client request ID. 服务记录此值。The service records this value. 允许服务跨服务跟踪操作。Allows the service to trace operation across services.
x-ms-client-session-idx-ms-client-session-id 客户端会话 ID。A client session ID. 服务记录此值。The service records this value. 允许服务跨服务跟踪一组相关操作。Allows the service to trace a group of related operations across services.
x-ms-client-application-namex-ms-client-application-name 生成此请求的应用程序的名称。Name of the application that generated this request. 服务记录此值。The service records this value.

可选但建议的响应标头如下所述。Optional but recommended response headers are described below.

响应标头Response header 说明Description
Content-typeContent-type 仅支持 application/jsonOnly application/json is supported.
x-ms-request-idx-ms-request-id 服务器生成的请求 ID。Server-generated request ID. 可用于与 Microsoft 联系以调查请求。Can be used to contact Microsoft to investigate a request.
x-ms-property-not-found-behaviorx-ms-property-not-found-behavior GA API 可选响应标头。GA API optional response header. 可能的值为 ThrowError(默认)或 UseNullPossible values are ThrowError (default) or UseNull.

HTTP 参数HTTP parameters

提示

如需查找有关必需和可选查询信息的详细信息,请参阅参考文档Find more information about required and optional query information in the reference documentation.

必需的 URL 查询字符串参数依赖于 API 版本。Required URL query string parameters depend on API version.

发布Release 可能的 API 版本值Possible API version values
Gen1Gen1 api-version=2016-12-12
Gen2Gen2 api-version=2020-07-31api-version=2018-11-01-previewapi-version=2020-07-31 and api-version=2018-11-01-preview

重要

api-version=2018-11-01-preview 版本很快就会被弃用。The api-version=2018-11-01-preview version will be deprecated soon. 建议用户切换到较新的版本。We recommend users to switch onto the newer version.

可选 URL 查询字符串参数包括为 HTTP 请求执行时间设置超时。Optional URL query string parameters include setting a timeout for HTTP request execution times.

可选查询参数Optional query parameter 说明Description 版本Version
timeout=<timeout> 用于执行 HTTP 请求的服务器端超时。Server-side timeout for HTTP request execution. 仅适用于获取环境事件获取环境聚合 API。Applicable only to the Get Environment Events and Get Environment Aggregates APIs. 超时值应采用 ISO 8601 持续时间格式(例如 "PT20S"),并且应在 1-30 s 范围内。Timeout value should be in ISO 8601 duration format, for example "PT20S" and should be in the range 1-30 s. 默认值为 30 sDefault value is 30 s. Gen1Gen1
storeType=<storeType> 对于启用了 Warm 存储的 Gen2 环境,可以对 WarmStoreColdStore 执行查询。For Gen2 environments with warm store enabled, the query can be executed either on the WarmStore or ColdStore. 查询中的此参数定义应对哪个存储执行查询。This parameter in the query defines which store the query should be executed on. 如果未定义,将对 Cold 存储区执行查询。If not defined, the query will be executed on the cold store. 若要查询 Warm 存储,需要将 storeType 设置为 WarmStoreTo query the warm store, storeType needs to be set to WarmStore. 如果未定义,将对 Cold 存储区执行查询。If not defined, the query will be executed against the cold store. Gen2Gen2

后续步骤Next steps