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

根据你的业务需求,可以在解决方案中包含一个或多个用来与 Azure 时序见解环境的 API 交互的客户端应用程序。Depending on your business needs, your solution might include one or more client applications that you use to interact with your Azure Time Series Insights environment's APIs. Azure 时序见解使用基于 OAUTH 2.0 的 Azure AD 安全令牌执行身份验证。Azure Time Series Insights performs authentication using Azure AD Security Tokens based on OAUTH 2.0. 若要对客户端进行身份验证,需要获取一个拥有适当权限的持有者令牌,并将其与 API 调用一起传递。To authenticate your client(s), you'll need to get a bearer token with the right permissions, and pass it along with your API calls. 本文档介绍几种获取凭据(可用于获取持有者令牌和进行身份验证)的方法,包括使用托管标识和 Azure Active Directory 应用注册。This document describes several methods for getting credentials that you can use to get a bearer token and authenticate, including using managed identity and Azure Active Directory app registration.

托管标识Managed identities

以下部分介绍如何使用 Azure Active Directory (Azure AD) 中的托管标识来访问 Azure 时序见解 API。The following sections describe how to use a managed identity from Azure Active Directory (Azure AD) to access the Azure Time Series Insights API. 在 Azure 上,托管标识可为 Azure AD 中的 Azure 资源提供标识并使用它来获取 Azure Active Directory (Azure AD) 令牌,从而使开发人员无需管理凭据。On Azure, managed identities eliminate the need for developers having to manage credentials by providing an identity for the Azure resource in Azure AD and using it to obtain Azure Active Directory (Azure AD) tokens. 下面是使用托管标识的一些好处:Here are some of the benefits of using Managed identities:

  • 你无需管理凭据,You don't need to manage credentials. 而且你甚至可能都无法访问凭据。Credentials are not even accessible to you.
  • 可以使用托管标识向支持 Azure AD 身份验证的任何 Azure 服务(包括 Azure Key Vault)进行身份验证。You can use managed identities to authenticate to any Azure service that supports Azure AD authentication including Azure Key Vault.
  • 无需额外付费也可使用托管标识。Managed identities can be used without any additional cost.

有关这两种类型的托管标识的详细信息,请参阅 Azure 资源托管标识是什么?For more information on the two types of managed identities read What are managed identities for Azure resources?

可在以下位置使用托管标识:You can use managed identities from your:

  • Azure VMAzure VMs
  • Azure 应用服务Azure App Services
  • Azure FunctionsAzure Functions
  • Azure 容器实例Azure Container instances
  • 等等and more ...

有关完整列表,请参阅支持 Azure 资源托管标识的 Azure 服务See Azure services that support managed identities for Azure resources for the complete list.

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

我们建议尽可能地使用托管标识,这样就无需管理凭据。We recommend using managed identities whenever possible so that you don't need to manage credentials. 如果客户端应用程序不是承载在支持托管标识的 Azure 服务中,你可以将该应用程序注册到 Azure AD 租户。If your client application is not hosted on an Azure service that supports managed identities you can register your application with an Azure AD tenant. 将应用程序注册到 Azure AD 时,需要创建应用程序的标识配置,使其能够与 Azure AD 集成。When you register your application with Azure AD, you are creating an identity configuration for your application that allows it to integrate with Azure AD. Azure 门户中注册应用时,可以选择单租户(只能在自己的租户中访问)或多租户(可在其他租户中访问),也可以选择设置重定向 URI(将访问令牌发送到的位置)。When you register an app in the Azure portal, you choose whether it's a single tenant (only accessible in your tenant) or multi-tenant (accessible in other tenants) and can optionally set a redirect URI (where the access token is sent to).

完成应用注册后,你将拥有应用(应用程序对象)的全局唯一实例,该实例存在于你的主租户或目录中。When you've completed the app registration, you have a globally unique instance of the app (the application object) which lives within your home tenant or directory. 而且你的应用拥有全局唯一 ID(应用或客户端 ID)。You also have a globally unique ID for your app (the app or client ID). 然后,在门户中,你便可以添加机密或证书和作用域以使应用正常工作,在登录对话框中自定义应用的品牌等等。In the portal, you can then add secrets or certificates and scopes to make your app work, customize the branding of your app in the sign-in dialog, and more.

如果在门户中注册应用程序,会在主租户中自动创建应用程序对象以及服务主体对象。If you register an application in the portal, an application object as well as a service principal object are automatically created in your home tenant. 如果使用 Microsoft Graph API 注册/创建应用程序,则通过一个单独步骤创建服务主体对象。If you register/create an application using the Microsoft Graph APIs, creating the service principal object is a separate step. 需要创建一个服务主体对象才能请求令牌。A service principal object is required to request tokens.

请务必查看应用程序的安全查检表。Be sure to review the Security checklist for your application. 作为最佳做法,应使用证书凭据,而不要使用密码凭据(客户端机密)。As a best practice, you should use certificate credentials, not password credentials (client secrets).

有关详细信息,请参阅 Azure Active Directory 中的应用程序对象和服务主体对象See Application and service principal objects in Azure Active Directory for more details.

步骤 1:创建托管标识或应用注册Step 1: Create your managed identity or app registration

在确定是要使用托管标识还是应用注册后,下一步是预配一个托管标识或应用注册。Once you've identified whether you'll be using a managed identity or app registration, your next step is to provision one.

托管标识Managed identity

用于创建托管标识的步骤根据代码所在的位置,以及是要创建系统分配的标识还是用户分配的标识而异。The steps you'll use to create a managed identity will vary depending on where your code is located and whether or not you're creating a system assigned or user assigned identity. 请参阅托管标识类型了解差异。Read Managed identity types to understand the difference. 选择标识类型后,在 Azure AD 托管标识文档中找到并遵循适当的教程。Once you've selected your identity type, locate and follow the correct tutorial in the Azure AD-managed identities documentation. 在此教程中可以找到有关如何为以下资源配置托管标识的说明:There you will find instructions for how to configure managed identities for:

应用程序注册Application registration

遵循注册应用程序中列出的步骤。Follow the steps listed in Register an application.

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

    • “重定向 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.
    • 确定“注销 URL”是否合适。Determine whether a Logout URL is appropriate.

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

    创建重定向 URICreate Redirect URIs

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

  • 将 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.

  • 接下来,指定你的应用所需的 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

  • 添加凭据(如果应用程序会自行调用环境的 API)。Add Credentials if the application will be calling your environment's APIs as itself. 通过凭据,应用程序可以自己的身份进行身份验证,无需用户在运行时进行任何交互。Credentials allow your application to authenticate as itself, requiring no interaction from a user at runtime.

步骤 2:授予访问权限Step 2: Grant Access

当 Azure 时序见解环境收到请求时,首先会验证调用方的持有者令牌。When your Azure Time Series Insights environment receives a request, first the caller's bearer token is validated. 如果通过了验证,则表示调用方已完成身份验证。接下来会执行另一项检查,以确保调用方已获得执行所请求操作的授权。If validation passes, the caller has been authenticated, and then another check is made to ensure the caller is authorized to perform the requested action. 若要为任何用户或服务主体授权,必须先为其分配“读取者”或“参与者”角色,以此授予其对环境的访问权限。To authorize any user or service principal, you must first grant them access to the environment by assigning them either the Reader or Contributor role.

  • 若要通过 Azure 门户 UI 授予访问权限,请按照授予对环境的数据访问权限一文中列出的说明操作。To grant access via the Azure portal UI, follow the instructions listed in the Grant data access to an environment article. 选择用户时,可以按名称或 ID 搜索托管标识或应用注册。When selecting the user, you can search for the managed identity or app registration by its name or by ID.

    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 或更高版本。The timeseriesinsights extension for Azure CLI requires version 2.11.0 or higher. 首次运行 az tsi access-policy 命令时,该扩展将自动安装。The extension will automatically install the first time you run an az tsi access-policy command. 详细了解扩展。Learn more about extensions.

步骤 3:请求令牌Step 3: Requesting Tokens

预配托管标识或应用注册并为其分配角色后,便可以开始使用它来请求 OAuth 2.0 持有者令牌了。Once your managed identity or app registration has been provisioned and assigned a role, you're ready to begin using it to request OAuth 2.0 bearer tokens. 用于获取令牌的方法根据代码的承载位置以及所选的语言而异。The method you use to obtain a token will differ depending on where your code is hosted and your language of choice. 指定资源(也称为令牌的“受众”)时,可以按照其 URL 或 GUID 来标识 Azure 时序见解:When specifying the resource (also known as the "audience" of the token), you can identify Azure Time Series Insights by its URL or GUID:

  • https://api.timeseries.azure.cn/
  • 120d688d-1518-4cf7-bd38-182f158850b6

重要

如果使用 URL 作为资源 ID,则必须将令牌确切地颁发给 https://api.timeseries.azure.cn/If you use the URL as the resource ID, the token must be issued exactly to https://api.timeseries.azure.cn/. 尾部反斜杠是必需项。The trailing slash is required.

  • 如果使用 Postman ,则 AuthURL 相应地是:https://login.partner.microsoftonline.cn/microsoft.partner.onmschina.cn/oauth2/authorize?scope=https://api.timeseries.azure.cn//.defaultIf using Postman your 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.

托管标识Managed identities

从 Azure 应用服务或 Functions 访问时,请按照获取 Azure 资源的令牌中的指导操作。When accessing from Azure App Service or Functions follow the guidance in the Obtain tokens for Azure resources.

对于 .NET 应用程序和函数,使用托管标识的最简单方式是通过适用于 .NET 的 Azure 标识客户端库来使用。For .NET applications and functions, the simplest way to work with a managed identity is through the Azure Identity client library for .NET. 此客户端库具有简单安全的优势,因此非常流行。This client library is popular due to its simplicity and security benefits. 开发人员可以编写代码一次,并让客户端库确定如何基于应用程序环境进行身份验证 - 无论是在开发人员工作站上的环境中使用开发人员的帐户进行身份验证,还是在部署到 Azure 的环境中使用托管服务标识进行身份验证。Developers can write code once and let the client library determine how to authenticate based on the application environment - whether on a developer workstation using a developer's account or deployed in Azure using a managed service identity.

使用 C# 和适用于 .NET 的 Azure 标识客户端库请求 Azure 时序见解的令牌:Request a token for Azure Time Series Insights using C# and the Azure Identity client library for .NET:

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;

应用注册App registration

可以在许多应用场景中使用 MSAL,包括但不限于:MSAL can be used in many application scenarios, including, but not limited to:

有关演示如何获取用作应用注册的令牌以及从 Gen2 环境查询数据的示例 C# 代码,请查看 GitHub 上的示例应用For sample C# code showing how to acquire a token as an app registration and query data from a Gen2 environment, view the sample app on GitHub

常用标头和参数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.

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.

提示

阅读托管的 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.

可选请求标头如下所述。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 版本值API version values
Gen1Gen1 api-version=2016-12-12
Gen2Gen2 api-version=2020-07-31

可选 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