使用媒体服务 v3 API 进行开发Develop with Media Services v3 APIs

作为开发者,可以利用媒体服务 REST API 或客户端库,与 REST API 交互,以轻松创建、管理和维护自定义媒体工作流。As a developer, you can use Media Services REST API or client libraries that allow you to interact with the REST API to easily create, manage, and maintain custom media workflows. 媒体服务 v3 API 基于 OpenAPI 规范(以前称为 Swagger)。The Media Services v3 API is based on the OpenAPI specification (formerly known as a Swagger).

本文介绍在使用媒体服务 v3 进行开发时适用于实体和 API 的规则。This article discusses rules that apply to entities and APIs when you develop with Media Services v3.

访问 Azure 媒体服务 APIAccessing the Azure Media Services API

若要有权访问媒体服务资源和媒体服务 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. 下面是两个常用的身份验证选项:Two common authentication options are:

  • 服务主体身份验证:用于对某个服务(例如 Web 应用、函数应用、逻辑应用、API 和微服务)进行身份验证。Service principal authentication: Used to authenticate a service (for example: web apps, function apps, logic apps, API, and microservices). 常常使用这种身份验证方法的应用程序是运行守护程序服务、中间层服务或计划作业的应用程序。Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs. 例如,此方法适用于应始终位于通过服务主体连接到媒体服务的中间层中的 Web 应用。For example, for web apps there should always be a mid-tier that connects to Media Services with a Service Principal.
  • 用户身份验证:用于验证使用应用程序与媒体服务资源进行交互的用户。User authentication: Used to authenticate a person who is using the app to interact with Media Services resources. 交互式应用应先提示用户输入用户凭据。The interactive app 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.

媒体服务 API 要求发出 REST API 请求的用户或应用有权访问媒体服务帐户资源,并有权使用“参与者”或“所有者”角色。 The Media Services API requires that the user or app making the REST API requests have access to the Media Services account resource and use a Contributor or Owner role. 可以使用“读者”角色访问 API,但只有“获取”或“列出”操作可用。 The API can be accessed with the Reader role but only Get or List operations will be available. 有关详细信息,请参阅媒体服务帐户的基于角色的访问控制 For more information, see Role-based access control for Media Services accounts.

如果不创建服务主体,可以考虑使用 Azure 资源的托管标识通过 Azure 资源管理器来访问媒体服务 API。Instead of creating a service principal, consider using managed identities for Azure resources to access the Media Services API through Azure Resource Manager. 若要详细了解 Azure 资源的托管标识,请参阅什么是 Azure 资源的托管标识?To learn more about managed identities for Azure resources, see What is managed identities for Azure resources.

Azure AD 服务主体Azure AD service principal

如果创建 Azure AD 应用和服务主体,该应用必须位于其自身的租户中。If you're creating an Azure AD app and service principal, the app has to be in its own tenant. 创建应用后,向应用授予对媒体服务帐户的“参与者”或“所有者”角色访问权限。 After you create the app, give the app Contributor or Owner role access to the Media Services account.

如果你不确定自己是否有权创建 Azure AD 应用,请参阅所需的权限If you're not sure whether you have permissions to create an Azure AD app, see Required permissions.

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

在 Web API 中使用 AAD 进行中层应用身份验证

  1. 中间层应用请求获取包含以下参数的 Azure AD 访问令牌:A middle-tier app requests an Azure AD access token that has the following parameters:

    • Azure AD 租户终结点。Azure AD tenant endpoint.
    • 媒体服务资源 URI。Media Services resource URI.
    • REST 媒体服务的资源 URI。Resource URI for REST Media Services.
    • Azure AD 应用值:客户端 ID和客户端机密。Azure AD app values: the client ID and client secret.

    若要获取所有所需值,请参阅使用 Azure CLI 访问 Azure 媒体服务 APITo get all the needed values, see Access Azure Media Services API with the Azure CLI.

  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.

示例Samples

参阅以下示例,其中演示了如何连接 Azure AD 服务主体:See the following samples that show how to connect with Azure AD service principal:

命名约定Naming conventions

Azure 媒体服务 v3 资源名称(例如,资产、作业、转换)需遵循 Azure 资源管理器命名约束。Azure Media Services v3 resource names (for example, Assets, Jobs, Transforms) are subject to Azure Resource Manager naming constraints. 根据 Azure 资源管理器的要求,资源名称始终必须唯一。In accordance with Azure Resource Manager, the resource names are always unique. 因此,可以为资源名称使用任何唯一的标识符字符串(例如,GUID)。Thus, you can use any unique identifier strings (for example, GUIDs) for your resource names.

媒体服务资源名称不能包含“<”、“>”、“%”、“&”、“:”、“\”、“?”、“/”、“*”、“+”、“.”、单引号或任何控制字符。Media Services resource names can't include: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', the single quote character, or any control characters. 允许其他所有字符。All other characters are allowed. 资源名称的最大长度为 260 个字符。The max length of a resource name is 260 characters.

有关 Azure 资源管理器命名的详细信息,请参阅命名要求命名约定For more information about Azure Resource Manager naming, see Naming requirements and Naming conventions.

资产中的文件/Blob 的名称Names of files/blobs within an asset

资产中的文件/blob 名称必须符合 Blob 名称要求NTFS 名称要求The names of files/blobs within an asset must follow both the blob name requirements and the NTFS name requirements. 符合这些要求的原因是可以将文件从 Blob 存储复制到本地 NTFS 磁盘进行处理。The reason for these requirements is the files can get copied from blob storage to a local NTFS disk for processing.

长时间运行的操作Long-running operations

在 Azure 媒体服务 swagger 文件中标有 x-ms-long-running-operation 的操作是长时间运行的操作。The operations marked with x-ms-long-running-operation in the Azure Media Services swagger files are long running operations.

有关如何跟踪 Azure 异步操作的详细信息,请参阅异步操作For details about how to track asynchronous Azure operations, see Async operations.

媒体服务具有以下长时间运行的操作:Media Services has the following long-running operations:

成功提交长时间运行的操作后,你会收到“202 已接受”;必须使用返回的操作 ID 轮询操作的完成状态。On successful submission of a long operation, you receive a '202 Accepted' and must poll for operation completion using the returned operation ID.

跟踪异步 Azure 操作一文深入说明了如何通过响应中返回的值跟踪异步 Azure 操作的状态。The track asynchronous Azure operations article explains in depth how to track the status of asynchronous Azure operations through values returned in the response.

一个给定的实时事件或其任何关联的实时输出仅支持一个长时间运行的操作。Only one long-running operation is supported for a given Live Event or any of its associated Live Outputs. 启动某个长时间运行的操作后,必须先完成该操作,才能针对同一个实时事件或任何关联的实时输出启动后续的长时间运行的操作。Once started, a long running operation must complete before starting a subsequent long-running operation on the same LiveEvent or any associated Live Outputs. 对于包含多个实时输出的实时事件,必须等待针对一个实时输出的长时间运行的操作完成,然后才能对另一个实时输出触发长时间运行的操作。For Live Events with multiple Live Outputs, you must await the completion of a long running operation on one Live Output before triggering a long running operation on another Live Output.

SDKSDKs

Note

Azure 媒体服务 v3 SDK 不保证是线程安全的。The Azure Media Services v3 SDKs aren't guaranteed to be thread-safe. 在开发多线程应用时,应添加自己的线程同步逻辑以保护客户端,或对每个线程使用新的 AzureMediaServicesClient 对象。When developing a multi-threaded app, you should add your own thread synchronization logic to protect the client or use a new AzureMediaServicesClient object per thread. 你还应该注意由代码提供给客户端的可选对象引入的多线程问题(如 .NET 中的 HttpClient 实例)。You should also be careful of multi-threading issues introduced by optional objects provided by your code to the client (like an HttpClient instance in .NET).

SDKSDK 参考Reference
.NET SDK.NET SDK .NET 参考.NET ref
Java SDKJava SDK Java 参考Java ref
Python SDKPython SDK Python 参考Python ref
Node.js SDKNode.js SDK Node.js 参考Node.js ref
Go SDKGo SDK Go 参考Go ref
Ruby SDKRuby SDK

另请参阅See also

Azure 媒体服务浏览器Azure Media Services Explorer

Azure 媒体服务浏览器 (AMSE) 是可供希望了解媒体服务的 Windows 客户使用的工具。Azure Media Services Explorer (AMSE) is a tool available to Windows customers who want to learn about Media Services. AMSE 是一个 Winforms/C# 应用程序,用于通过媒体服务对 VOD 和实时内容进行上传、下载、编码和流式传输。AMSE is a Winforms/C# application that does upload, download, encode, stream VOD and live content with Media Services. AMSE 工具适用于希望在不编写任何代码的情况下测试媒体服务的客户。The AMSE tool is for clients who want to test Media Services without writing any code. 对于希望使用媒体服务进行开发的客户,可以为其提供 AMSE 代码作为资源。The AMSE code is provided as a resource for customers who want to develop with Media Services.

AMSE 是一个开源项目,由社区提供支持(可以将问题报告给 https://github.com/Azure/Azure-Media-Services-Explorer/issues) )。AMSE is an Open Source project, support is provided by the community (issues can be reported to https://github.com/Azure/Azure-Media-Services-Explorer/issues). 此项目采用了 Microsoft 开放源代码行为准则This project has adopted the Microsoft Open Source Code of Conduct. 有关详细信息,请参阅行为准则常见问题解答;若有其他任何问题或意见,请联系 opencode@microsoft.com。For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any other questions or comments.

媒体服务实体的筛选、排序和分页Filtering, ordering, paging of Media Services entities

请参阅 Azure 媒体服务实体的筛选、排序和分页See Filtering, ordering, paging of Azure Media Services entities.

另请参阅See also

Azure CLIAzure CLI

后续步骤Next steps