通过 Azure AD 身份验证访问 Azure 媒体服务 APIAccess the Azure Media Services API with Azure AD authentication

备注

不会向媒体服务 v2 添加任何新特性或新功能。No new features or functionality are being added to Media Services v2.
查看最新版本:媒体服务 v3Check out the latest version, Media Services v3. 另请参阅从 v2 到 v3 的迁移指南Also, see migration guidance from v2 to v3

Azure 媒体服务 API 是 RESTful API。The Azure Media Services API is a RESTful API. 可用于通过 REST API 或可用的客户端 SDK 对媒体资源执行操作。You can use it to perform operations on media resources by using a REST API or by using available client SDKs. Azure 媒体服务提供了适用于 Microsoft.NET 的媒体服务客户端 SDK。Azure Media Services offers a Media Services client SDK for Microsoft .NET. 若要有权访问媒体服务资源和媒体服务 API,必须先进行身份验证。To be authorized to access Media Services resources and the Media Services API, you must first be authenticated.

媒体服务支持基于 Azure Active Directory (Azure AD) 的身份验证Media Services supports Azure Active Directory (Azure AD)-based authentication. Azure 媒体 REST 服务要求,发出 REST API 请求的用户或应用程序必须具有参与者所有者角色,才能访问资源。The Azure Media REST service requires that the user or application that makes the REST API requests have either the Contributor or Owner role to access the resources. 有关详细信息,请参阅 Azure 门户中基于角色的访问控制入门For more information, see Get started with Role-Based Access Control in the Azure portal.

本文档概述了如何使用 REST 或 .NET API 访问媒体服务 API。This document gives an overview of how to access the Media Services API by using REST or .NET APIs.

备注

访问控制授权已于 2018 年 6 月 1 日弃用。Access Control authorization was deprecated on June 1, 2018.

访问控制Access control

若要让 Azure 媒体 REST 请求成功,对于尝试访问的媒体服务帐户,调用用户必须具有参与者或所有者角色。For the Azure Media REST request to succeed, the calling user must have a Contributor or Owner role for the Media Services account it is trying to access.
只有具有所有者角色的用户,才能向新用户或应用程序授予媒体资源(帐户)访问权限。Only a user with the Owner role can give media resource (account) access to new users or apps. 参与者角色只能访问媒体资源。The Contributor role can access only the media resource. 未授权的请求失败,状态代码为 401。Unauthorized requests fail, with status code of 401. 如果看到此错误代码,请检查用户是否具有针对用户媒体服务帐户分配的参与者或所有者角色。If you see this error code, check whether your user has the Contributor or Owner role assigned for the user's Media Services account. 可以在 Azure 门户中检查角色分配。You can check this in the Azure portal. 搜索媒体帐户,再单击“访问控制”选项卡。Search for your media account, and then click the Access control tab.

“访问控制”选项卡

身份验证类型Types of authentication

将 Azure AD 身份验证与 Azure 媒体服务结合使用时,可以选择下列两个身份验证选项:When you use Azure AD authentication with Azure Media Services, you have two authentication options:

  • 用户身份验证User authentication. 验证使用应用程序与媒体服务资源进行交互的用户。Authenticate a person who is using the app to interact with Media Services resources. 交互式应用程序应先提示用户输入用户凭据。The interactive application should first prompt the user for the user's credentials. 例如,授权用户用来监视编码作业或实时传送视频流的管理控制台应用程序。An example is a management console app used by authorized users to monitor encoding jobs or live streaming.
  • 服务主体身份验证Service principal authentication. 对服务进行身份验证。Authenticate a service. 常常使用这种身份验证方法的应用程序是运行守护程序服务、中间层服务或计划作业的应用程序。Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs. 例如,Web 应用程序、函数应用程序、逻辑应用程序、API 和微服务。Examples are web apps, function apps, logic apps, API, and microservices.

用户身份验证User authentication

应使用用户身份验证方法的应用程序是负责管理或监视的本机应用程序:移动应用、Windows 应用程序和控制台应用程序。Applications that should use the user authentication method are management or monitoring native apps: mobile apps, Windows apps, and Console applications. 若要在以下情形之一让用户与服务进行交互,此类解决方案十分有用:This type of solution is useful when you want human interaction with the service in one of the following scenarios:

  • 编码作业的监视仪表板。Monitoring dashboard for your encoding jobs.
  • 实时传送视频流的监视仪表板。Monitoring dashboard for your live streams.
  • 面向桌面或移动用户的管理应用程序,用于管理媒体服务帐户中的资源。Management application for desktop or mobile users to administer resources in a Media Services account.

备注

这种身份验证方法不得用于面向使用者的应用程序。This authentication method should not be used for consumer-facing applications.

本机应用程序必须先从 Azure AD 获取访问令牌,再使用此令牌对媒体服务 REST API 发出 HTTP 请求。A native application must first acquire an access token from Azure AD, and then use it when you make HTTP requests to the Media Services REST API. 将访问令牌添加到请求头。Add the access token to the request header.

下图展示了典型的交互式应用程序身份验证流:The following diagram shows a typical interactive application authentication flow:

本机应用图

在上图中,数字表示按时间顺序的请求流。In the preceding diagram, the numbers represent the flow of the requests in chronological order.

备注

使用用户身份验证方法时,所有应用共用同一(默认)本机应用程序客户端 ID 和本机应用程序重定向 URI。When you use the user authentication method, all apps share the same (default) native application client ID and native application redirect URI.

  1. 提示用户输入凭据。Prompt a user for credentials.

  2. 请求获取包含以下参数的 Azure AD 访问令牌:Request an Azure AD access token with the following parameters:

    • Azure AD 租户终结点。Azure AD tenant endpoint.

      可以在 Azure 门户中检索租户信息。The tenant information can be retrieved from the Azure portal. 将光标悬停在右上角的登录用户名之上。Place your cursor over the name of the signed-in user in the top right corner.

    • 媒体服务资源 URI。Media Services resource URI.

      如果媒体服务帐户位于同一 Azure 环境中,此 URI 相同(例如 https://rest.media.chinacloudapi.cn)。This URI is the same for Media Services accounts that are in the same Azure environment (for example, https://rest.media.chinacloudapi.cn).

    • 媒体服务(本机)应用程序客户端 ID。Media Services (native) application client ID.

    • 媒体服务(本机)应用程序重定向 URI。Media Services (native) application redirect URI.

    • REST 媒体服务的资源 URI。Resource URI for REST Media Services.

      该 URI 表示 REST API 终结点(例如, https://test03.restv2.chinanorth.media.chinacloudapi.cn/api/) 。The URI represents the REST API endpoint (for example, https://test03.restv2.chinanorth.media.chinacloudapi.cn/api/).

      若要获取这些参数的值,请参阅使用 Azure 门户访问 Azure AD 身份验证设置(使用用户身份验证选项)。To get values for these parameters, see Use the Azure portal to access Azure AD authentication settings using the user authentication option.

  3. Azure AD 访问令牌发送到客户端。The Azure AD access token is sent to the client.

  4. 客户端使用 Azure AD 访问令牌向 Azure 媒体 REST API 发送请求。The client sends a request to the Azure Media REST API with the Azure AD access token.

  5. 客户端获取媒体服务返回的数据。The client gets back the data from Media Services.

若要了解如何通过 Azure AD 身份验证使用媒体服务 .NET 客户端 SDK 与 REST 请求进行通信,请参阅通过 Azure AD 身份验证使用 .NET 访问媒体服务 APIFor information about how to use Azure AD authentication to communicate with REST requests by using the Media Services .NET client SDK, see Use Azure AD authentication to access the Media Services API with .NET.

如果未使用媒体服务 .NET 客户端 SDK,必须使用第 2 步所述参数,手动创建 Azure AD 访问令牌请求。If you are not using the Media Services .NET client SDK, you must manually create an Azure AD access token request by using the parameters described in step 2. 有关详细信息,请参阅如何使用 Azure AD 身份验证库获取 Azure AD 令牌For more information, see How to use the Azure AD Authentication Library to get the Azure AD token.

服务主体身份验证Service principal authentication

常常使用这种身份验证方法的应用程序是运行中间层服务和计划作业的应用:Web 应用、函数应用、逻辑应用、API 和微服务。Applications that commonly use this authentication method are apps that run middle-tier services and scheduled jobs: web apps, function apps, logic apps, APIs, and microservices. 这种身份验证方法还适用于交互式应用程序,即可能需要使用服务帐户管理资源的应用程序。This authentication method also is suitable for interactive applications in which you might want to use a service account to manage resources.

使用服务主体身份验证方法生成使用者方案时,通常在中间层(通过一些 API)处理身份验证,而不直接在移动或桌面应用程序中处理。When you use the service principal authentication method to build consumer scenarios, authentication typically is handled in the middle tier (through some API) and not directly in a mobile or desktop application.

若要使用这种方法,请在它自己的租户中创建 Azure AD 应用程序和服务主体。To use this method, create an Azure AD application and service principal in its own tenant. 创建应用程序后,向应用程序授予对媒体服务帐户的参与者或所有者角色访问权限。After you create the application, give the app Contributor or Owner role access to the Media Services account. 可在 Azure 门户中使用 Azure CLI 或 PowerShell 脚本执行此操作。You can do this in the Azure portal, by using the Azure CLI, or with a PowerShell script. 也可以使用现有 Azure AD 应用程序。You also can use an existing Azure AD application. 可以在 Azure 门户中注册和管理 Azure AD 应用程序和服务主体。You can register and manage your Azure AD app and service principal in the Azure portal. 也可以使用 Azure CLIPowerShell 执行此操作。You also can do this by using Azure CLI or PowerShell.

中间层应用

创建 Azure AD 应用程序后,将会获得下列设置的值。After you create your Azure AD application, you get values for the following settings. 需要使用这些值进行身份验证:You need these values for authentication:

  • 客户端 IDClient ID
  • 客户端机密Client secret

在上图中,数字表示按时间顺序的请求流:In the preceding figure, the numbers represent the flow of the requests in chronological order:

  1. 中间层应用(Web API 或 Web 应用程序)请求获取包含以下参数的 Azure AD 访问令牌:A middle-tier app (web API or web application) requests an Azure AD access token that has the following parameters:

    • Azure AD 租户终结点。Azure AD tenant endpoint.

      可以在 Azure 门户中检索租户信息。The tenant information can be retrieved from the Azure portal. 将光标悬停在右上角的登录用户名之上。Place your cursor over the name of the signed-in user in the top right corner.

    • 媒体服务资源 URI。Media Services resource URI.

      如果媒体服务帐户位于同一 Azure 环境中,此 URI 相同(例如 https://rest.media.chinacloudapi.cn)。This URI is the same for Media Services accounts that are located in the same Azure environment (for example, https://rest.media.chinacloudapi.cn).

    • REST 媒体服务的资源 URI。Resource URI for REST Media Services.

      该 URI 表示 REST API 终结点(例如, https://test03.restv2.chinanorth.media.chinacloudapi.cn/api/) 。The URI represents the REST API endpoint (for example, https://test03.restv2.chinanorth.media.chinacloudapi.cn/api/).

    • Azure AD 应用程序值:客户端 ID和客户端机密。Azure AD application values: the client ID and client secret.

      若要获取这些参数的值,请参阅使用 Azure 门户访问 Azure AD 身份验证设置(使用服务主体身份验证选项)。To get values for these parameters, see Use the Azure portal to access Azure AD authentication settings by using the service principal authentication option.

  2. Azure AD 访问令牌发送到中间层。The Azure AD access token is sent to the middle tier.

  3. 中间层使用 Azure AD 令牌向 Azure 媒体 REST API 发送请求。The middle tier sends request to the Azure Media REST API with the Azure AD token.

  4. 中间层获取媒体服务返回的数据。The middle tier gets back the data from Media Services.

若要详细了解如何通过 Azure AD 身份验证使用媒体服务 .NET 客户端 SDK 与 REST 请求进行通信,请参阅通过 Azure AD 身份验证使用 .NET 访问 Azure 媒体服务 APIFor more information about how to use Azure AD authentication to communicate with REST requests by using the Media Services .NET client SDK, see Use Azure AD authentication to access Azure Media Services API with .NET.

如果未使用媒体服务 .NET 客户端 SDK,必须使用第 1 步所述参数,手动创建 Azure AD 访问令牌请求。If you are not using the Media Services .NET client SDK, you must manually create an Azure AD token request by using parameters described in step 1. 有关详细信息,请参阅如何使用 Azure AD 身份验证库获取 Azure AD 令牌For more information, see How to use the Azure AD Authentication Library to get the Azure AD token.

故障排除Troubleshooting

异常:“远程服务器返回错误:(401)未经授权。”Exception: "The remote server returned an error: (401) Unauthorized."

解决方案:若要让媒体服务 REST 请求成功,对于尝试访问的媒体服务帐户,调用用户必须具有参与者或所有者角色。Solution: For the Media Services REST request to succeed, the calling user must be a Contributor or Owner role in the Media Services account it is trying to access. 有关详细信息,请参阅访问控制部分。For more information, see the Access control section.

资源Resources

下面的文章概述了 Azure AD 身份验证概念:The following articles are overviews of Azure AD authentication concepts:

后续步骤Next steps