通过 Azure AD 身份验证使用 REST 访问媒体服务 APIUse Azure AD authentication to access the Media Services API with REST

备注

不会向媒体服务 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 媒体服务使用 Azure AD 身份验证时,可以通过以下两种方式之一进行身份验证:When you're using Azure AD authentication with Azure Media Services, you can authenticate in one of two ways:

  • 用户身份验证:对使用应用程序与 Azure 媒体服务资源进行交互的人员执行身份验证。User authentication authenticates a person who is using the app to interact with Azure Media Services resources. 交互式应用程序应先提示用户输入凭据。The interactive application should first prompt the user for credentials. 举个例子,授权用户用来监视编码作业或实时流式处理的管理控制台应用程序。An example is a management console app that's used by authorized users to monitor encoding jobs or live streaming.

  • 服务主体身份验证:对服务进行身份验证。Service principal authentication authenticates a service. 通常使用此身份验证方法的应用程序是运行守护程序服务、中间层服务或计划作业的应用:如 Web 应用、函数应用、逻辑应用、 API 或微服务。Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs, such as web apps, function apps, logic apps, APIs, or microservices.

    本教程演示如何通过 Azure AD“服务主体”身份验证使用 REST 访问 AMS API 。This tutorial shows you how to use Azure AD service principal authentication to access AMS API with REST.

    备注

    “服务主体”是为连接到 Azure 媒体服务的大多数应用程序推荐的最佳做法 。Service principal is the recommended best practice for most applications connecting to Azure Media Services.

在本教程中,你将了解如何执行以下操作:In this tutorial, you learn how to:

  • 从 Azure 门户获取身份验证信息Get the authentication information from the Azure portal
  • 使用 Postman 获取访问令牌Get the access token using Postman
  • 使用访问令牌测试资产 API Test the Assets API using the access token

重要

目前,媒体服务支持 Azure 访问控制服务身份验证模型。Currently, Media Services supports the Azure Access Control services authentication model. 不过,访问控制身份验证将于 2018 年 6 月 1 日弃用。However, Access Control authentication will be deprecated June 1, 2018. 建议尽快迁移到 Azure AD 身份验证模型。We recommend that you migrate to the Azure AD authentication model as soon as possible.

必备条件Prerequisites

从 Azure 门户获取身份验证信息Get the authentication information from the Azure portal

概述Overview

若要访问媒体服务 API,需要收集以下数据点。To access Media Services API, you need to collect the following data points.

设置Setting 示例Example 说明Description
Azure Active Directory 租户域Azure Active Directory tenant domain microsoft.partner.onmschina.cnmicrosoft.partner.onmschina.cn 作为安全令牌服务 (STS) 终结点的 Azure AD 是使用以下格式创建的:https://login.partner.microsoftonline.cn/{your-ad-tenant-name.partner.onmschina.cn}/oauth2/tokenAzure AD as a Secure Token Service (STS) endpoint is created using the following format: https://login.partner.microsoftonline.cn/{your-ad-tenant-name.partner.onmschina.cn}/oauth2/token. Azure AD 颁发用于访问资源的 JWT(访问令牌)。Azure AD issues a JWT in order to access resources (an access token).
REST API 终结点REST API endpoint https://amshelloworld.restv2.chinanorth.media.chinacloudapi.cn/api/ 这是应用程序中发出的所有媒体服务 REST API 调用所针对的终结点。This is the endpoint against which all Media Services REST API calls in your application are made.
客户端 ID(应用程序 ID)Client ID (Application ID) f7fbbb29-a02d-4d91-bbc6-59a2579259d2f7fbbb29-a02d-4d91-bbc6-59a2579259d2 Azure AD 应用程序(客户端)ID。Azure AD application (client) ID. 需要客户端 ID 才能获取访问令牌。The client ID is required to get the access token.
客户端机密Client Secret +mUERiNzVMoJGggD6aV1etzFGa1n6KeSlLjIq+Dbim0=+mUERiNzVMoJGggD6aV1etzFGa1n6KeSlLjIq+Dbim0= Azure AD 应用程序密钥(客户端密码)。Azure AD application keys (client secret). 需要客户端密码才能获取访问令牌。The client secret is required to get the access token.

从 Azure 门户获取 AAD 身份验证信息Get AAD auth info from the Azure portal

若要获取信息,请按照以下步骤操作:To get the information, follow these steps:

  1. 登录到 Azure 门户Log in to the Azure portal.

  2. 导航到 AMS 实例。Navigate to your AMS instance.

  3. 选择“API 访问” 。Select API access.

  4. 点击“通过服务主体连接到 Azure 媒体服务 API” 。Click on Connect to Azure Media Services API with service principal.

    API 访问

  5. 选择现有的“Azure AD 应用程序”或新建一个 Azure AD 应用程序(如下所示) 。Select an existing Azure AD application or create a new one (shown below).

    备注

    为使 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. 如果出现“远程服务器返回错误: (401)未授权”的异常,请参阅访问控制If you get an exception that says "The remote server returned an error: (401) Unauthorized," see Access control.

    如果需要创建新的 AD 应用,请执行以下步骤:If you need to create a new AD app, follow these steps:

    1. 按“新建” 。Press Create New.

    2. 输入名称。Enter a name.

    3. 再次按“新建” 。Press Create New again.

    4. 按“保存” 。Press Save.

      API 访问

      新的应用将显示在页面上。The new app shows up on the page.

  6. 获取“客户端 ID”(应用程序 ID) 。Get the Client ID (Application ID).

    1. 选择应用程序。Select the application.

    2. 从右侧的窗口获取“客户端 ID” 。Get the Client ID from the window on the right.

      API 访问

  7. 获取应用程序的“密钥”(客户端密码) 。Get the application's Key (client secret).

    1. 单击“Azure Active Directory”按钮。 Click the Azure Active Directory button .

    2. 按“应用注册”。 Press App registration.

    3. 按“testapp”。 Press testapp.

    4. 按“密钥”(请注意,客户端 ID 信息位于“应用程序 ID”下)。 Press Keys (notice that the Client ID info is under Application ID).

      API 访问

    5. 填写“说明”和“到期时间”,然后按“保存”以生成应用密钥(客户端密码) 。Generate the app key (client secret) by filling in DESCRIPTION and EXPIRES and pressing Save.

      按下“保存”按钮后将显示密钥值 。Once the Save button is pressed, the key value appears. 在退出此边栏选项卡之前复制此密钥值。Copy the key value before leaving the blade.

    API 访问

可以将 AD 连接参数的值添加到 web.config 或 app.config 文件,稍后在代码中使用。You can add values for AD connection parameters to your web.config or app.config file, to later use in your code.

重要

“客户端密钥”是重要的密码,应该正确地在密钥保管库中受到保护或在生产中加密 。The Client key is an important secret and should be properly secured in a key vault or encrypted in production.

使用 Postman 获取访问令牌Get the access token using Postman

本部分演示如何使用 Postman 执行返回 JWT 持有者令牌(访问令牌)的 REST API 。This section shows how to use Postman to execute a REST API that returns a JWT Bearer Token (access token). 若要调用任何媒体服务 REST API,需要将“授权”标头添加到这些调用,并将“持有者 your_access_token”的值添加到每个调用(如本教程的下一部分中所示) 。To call any Media Services REST API, you need to add the "Authorization" header to the calls, and add the value of "Bearer your_access_token" to each call (as shown in the next section of this tutorial).

  1. 打开 Postman 。Open Postman.

  2. 选择“POST” 。Select POST.

  3. 使用以下格式输入包含租户名称的 URL:租户名称应以 .partner.onmschina.cn 结尾,URL 应以 oauth2/token 结尾:Enter the URL that includes your tenant name using the following format: the tenant name should end with .partner.onmschina.cn and the URL should end with oauth2/token:

    https://login.partner.microsoftonline.cn/{your-aad-tenant-name.partner.onmschina.cn}/oauth2/token

  4. 选择“标头”选项卡 。Select the Headers tab.

  5. 使用“密钥/值”数据网格输入“标头”信息 。Enter the Headers information using the "Key/Value" data grid.

    数据网格

    或者,单击 Postman 窗口右侧的“批量编辑”链接,然后粘贴以下代码 。Alternatively, click Bulk Edit link on the right of the Postman window and paste the following code.

    Content-Type:application/x-www-form-urlencoded
    Keep-Alive:true
    
  6. 按“正文”选项卡 。Press the Body tab.

  7. 使用“密钥/值”数据网格输入正文信息(替换客户端 ID 和密钥值)。Enter the body information using the "Key/Value" data grid (replace the client ID and secret values).

    数据网格

    或者,单击 Postman 窗口右侧的“批量编辑”,然后粘贴以下正文(替换客户端 ID 和密钥值) :Alternatively, click Bulk Edit on the right of the Postman window and paste the following body (replace the client ID and secret values):

    grant_type:client_credentials
    client_id:{Your Client ID that you got from your Azure AD Application}
    client_secret:{Your client secret that you got from your Azure AD Application's Keys}
    resource:https://rest.media.chinacloudapi.cn
    
  8. 按“发送”。 Press Send.

    获取令牌

返回的响应包含需要用于访问任何 AMS API 的访问令牌 。The returned response contains the access token that you need to use to access any AMS APIs.

使用访问令牌测试资产 API Test the Assets API using the access token

此部分介绍如何使用 Postman 访问资产 API。This section shows how to access the Assets API using Postman.

  1. 打开 Postman 。Open Postman.

  2. 选择“GET” 。Select GET.

  3. 粘贴 REST API 终结点(例如, https://amshelloworld.restv2.chinanorth.media.chinacloudapi.cn/api/Assets)Paste the REST API endpoint (for example, https://amshelloworld.restv2.chinanorth.media.chinacloudapi.cn/api/Assets)

  4. 选择“授权”选项卡 。Select the Authorization tab.

  5. 选择“持有者令牌” 。Select Bearer Token.

  6. 粘贴上一部分中创建的令牌。Paste the token that was created in the previous section.

    获取令牌

    备注

    Postman UX 在 Mac 和电脑上可能有所不同。The Postman UX could be different between a Mac and PC. 如果 Mac 版本的“身份验证”部分下拉列表中没有“持有者令牌”选项,应在 Mac 客户端上手动添加“授权”标头 。If the Mac version does not have the "Bearer Token" option in the Authentication section dropdown, you should add the Authorization header manually on the Mac client.

    “授权”标头

  7. 选择“标头” 。Select Headers.

  8. 单击 Postman 窗口右侧的“批量编辑”链接 。Click Bulk Edit link on the right the Postman window.

  9. 粘贴以下标头:Paste the following headers:

    x-ms-version:2.19
    Accept:application/json
    Content-Type:application/json
    DataServiceVersion:3.0
    MaxDataServiceVersion:3.0
    
  10. 按“发送”。 Press Send.

返回的响应包含帐户中的资产。The returned response contains the assets that are in your account.

后续步骤Next steps