媒体服务操作 REST API 概述Media Services operations REST API overview

媒体服务徽标media services logo


备注

不会向媒体服务 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

媒体服务操作 REST API 用于在媒体服务帐户中创建作业、资产、实时频道和其他资源 。The Media Services Operations REST API is used for creating Jobs, Assets, Live Channels and other resources in a Media Services account. 有关详细信息,请参阅 Media Services Operations REST API reference(媒体服务操作 REST API 参考)。For more information, see Media Services Operations REST API reference.

媒体服务提供了接受 JSON 或 atom+pub XML 格式的 REST API。Media Services provides a REST API that accepts both JSON or atom+pub XML format. 媒体服务 REST API 需要每个客户端连接到媒体服务时必须发送的特定 HTTP 标头,以及一组可选标头。Media Services REST API requires specific HTTP headers that each client must send when connecting to Media Services, as well as a set of optional headers. 以下部分介绍你在创建请求和接收来自媒体服务的响应时可以使用的标头和 HTTP 谓词。The following sections describe the headers and HTTP verbs you can use when creating requests and receiving responses from Media Services.

对媒体服务 REST API 的身份验证通过 Azure Active Directory 身份验证完成,如通过 Azure AD 身份验证使用 REST 访问 Azure 媒体服务 API一文所述Authentication to the Media Services REST API is done through Azure Active Directory authentication which is outlined in the article Use Azure AD authentication to access the Azure Media Services API with REST

注意事项Considerations

使用 REST 时需考虑下列事项:The following considerations apply when using REST.

  • 查询实体时,一次返回的实体数限制为 1000 个,因为公共 REST v2 将查询结果数限制为 1000 个。When querying entities, there is a limit of 1000 entities returned at one time because public REST v2 limits query results to 1000 results. 需要使用此 .NET 示例此 REST API 示例中所述的 SkipTake (.NET)/ top (REST)。You need to use Skip and Take (.NET)/ top (REST) as described in this .NET example and this REST API example.

  • 使用 JSON 并指定在请求中使用 __metadata 关键字(例如,为了引用某个链接对象)时,必须将 Accept 标头设置为 JSON 详细格式(参阅以下示例)。When using JSON and specifying to use the __metadata keyword in the request (for example, to reference a linked object) you MUST set the Accept header to JSON Verbose format (see the following example). Odata 并不了解请求中的 __metadata 属性,除非将其设置为 verbose。Odata does not understand the __metadata property in the request, unless you set it to verbose.

    POST https://media.chinacloudapi.cn/API/Jobs HTTP/1.1
    Content-Type: application/json;odata=verbose
    Accept: application/json;odata=verbose
    DataServiceVersion: 3.0
    MaxDataServiceVersion: 3.0
    x-ms-version: 2.19
    Authorization: Bearer <ENCODED JWT TOKEN> 
    Host: media.chinacloudapi.cn
    
    {
        "Name" : "NewTestJob", 
        "InputMediaAssets" : 
            [{"__metadata" : {"uri" : "https://media.chinacloudapi.cn/api/Assets('nb%3Acid%3AUUID%3Aba5356eb-30ff-4dc6-9e5a-41e4223540e7')"}}]
    . . . 
    

媒体服务支持的标准 HTTP 请求标头Standard HTTP request headers supported by Media Services

每次调用媒体服务时,必须在请求中包括一组必需标头,还可以根据需要包括一组可选标头。For every call you make into Media Services, there is a set of required headers you must include in your request and also a set of optional headers you may want to include. 下表列出了必需的标头:The table below lists the required headers:

标头Header 类型Type Value
授权Authorization 持有者Bearer 持有者是唯一接受的授权机制。Bearer is the only accepted authorization mechanism. 该值还必须包括由 Azure Active Directory 提供的访问令牌。The value must also include the access token provided by Azure Active Directory.
x-ms-versionx-ms-version DecimalDecimal 2.17(或最新版本)2.17 (or most recent version)
DataServiceVersionDataServiceVersion DecimalDecimal 3.03.0
MaxDataServiceVersionMaxDataServiceVersion DecimalDecimal 3.03.0

备注

由于媒体服务使用 OData 公开其 REST API,因此所有请求中均应包括 DataServiceVersion 和 MaxDataServiceVersion 标头,但如果未包括这些标头,则当前媒体服务会假定使用的 DataServiceVersion 值为 3.0。Because Media Services uses OData to expose its REST APIs, the DataServiceVersion and MaxDataServiceVersion headers should be included in all requests; however, if they are not, then currently Media Services assumes the DataServiceVersion value in use is 3.0.

以下是一组可选标头:The following is a set of optional headers:

标头Header 类型Type Value
DateDate RFC 1123 日期RFC 1123 date 请求的时间戳Timestamp of the request
AcceptAccept 内容类型Content type 响应的请求内容类型,例如:The requested content type for the response such as the following:

-application/json;odata=verbose-application/json;odata=verbose

- application/atom+xml- application/atom+xml

响应可能具有不同的内容类型,如 BLOB 提取,在该类型中成功的响应包含 BLOB 流作为负载。Responses may have a different content type, such as a blob fetch, where a successful response contains the blob stream as the payload.

Accept-EncodingAccept-Encoding Gzip、deflateGzip, deflate GZIP 和 DEFLATE 编码(如果适用)。GZIP and DEFLATE encoding, when applicable. 注意:对于大型资源,媒体服务可能会忽略此标头并返回未经压缩的数据。Note: For large resources, Media Services may ignore this header and return noncompressed data.
Accept-LanguageAccept-Language “en”、“es”等。"en", "es", and so on. 指定响应的首选语言。Specifies the preferred language for the response.
Accept-CharsetAccept-Charset 字符集类型,如“UTF-8”Charset type like “UTF-8” 默认值为 UTF-8。Default is UTF-8.
X-HTTP-MethodX-HTTP-Method HTTP 方法HTTP Method 允许不支持 HTTP 方法(例如 PUT 或 DELETE)的客户端或防火墙使用这些通过 GET 调用隧道化的方法。Allows clients or firewalls that do not support HTTP methods like PUT or DELETE to use these methods, tunneled via a GET call.
Content-TypeContent-Type 内容类型Content type PUT 或 POST 请求中请求正文的内容类型。Content type of the request body in PUT or POST requests.
client-request-idclient-request-id StringString 调用方定义的值,用于标识给定请求。A caller-defined value that identifies the given request. 如果指定,会在响应消息中包括此值,作为一种映射请求的方法。If specified, this value will be included in the response message as a way to map the request.

重要说明Important

值的上限应为 2096b (2k)。Values should be capped at 2096b (2k).

媒体服务支持的标准 HTTP 响应标头Standard HTTP response headers supported by Media Services

下面是可以根据你请求的资源以及要执行的操作返回给一组标头。The following is a set of headers that may be returned to you depending on the resource you were requesting and the action you intended to perform.

标头Header 类型Type Value
request-idrequest-id StringString 当前操作的唯一标识符,由服务生成。A unique identifier for the current operation, service generated.
client-request-idclient-request-id StringString 调用方在原始请求(如果存在)中指定的标识符。An identifier specified by the caller in the original request, if present.
DateDate RFC 1123 日期RFC 1123 date 处理请求的日期/时间。The date/time that the request was processed.
Content-TypeContent-Type 不定Varies 响应正文的内容类型。The content type of the response body.
Content-EncodingContent-Encoding 不定Varies Gzip 或 deflate(视情况而定)。Gzip or deflate, as appropriate.

媒体服务支持的标准 HTTP 谓词Standard HTTP verbs supported by Media Services

下面是在提出 HTTP 请求时可以使用的 HTTP 谓词的完整列表:The following is a complete list of HTTP verbs that can be used when making HTTP requests:

谓词Verb 说明Description
GETGET 返回对象的当前值。Returns the current value of an object.
POSTPOST 根据提供的数据创建对象,或提交命令。Creates an object based on the data provided, or submits a command.
PUTPUT 替换对象,或创建命名对象(如果适用)。Replaces an object, or creates a named object (when applicable).
DELETEDELETE 删除对象。Deletes an object.
MERGEMERGE 使用指定的属性更改更新现有对象。Updates an existing object with named property changes.
HEADHEAD 为 GET 响应返回对象的元数据。Returns metadata of an object for a GET response.

查找并浏览媒体服务实体模型Discover and browse the Media Services entity model

为了使媒体服务实体易于发现,可使用 $metadata 操作。To make Media Services entities more discoverable, the $metadata operation can be used. 使用该操作,可以检索所有有效的实体类型、实体属性、关联、函数、操作等。It allows you to retrieve all valid entity types, entity properties, associations, functions, actions, and so on. 将 $metadata 操作添加到媒体服务 REST API 终结点的末尾后,即可访问此发现服务。By adding the $metadata operation to the end of your Media Services REST API endpoint, you can access this discovery service.

/api/$metadata。/api/$metadata.

如果希望在浏览器中查看元数据,应在 URI 的末尾追加“?api-version=2.x”,或不要在请求中包括 x-ms-version 标头。You should append "?api-version=2.x" to the end of the URI if you want to view the metadata in a browser, or do not include the x-ms-version header in your request.

使用 Azure Active Directory 进行媒体服务 REST 身份验证Authenticate with Media Services REST using Azure Active Directory

对 REST API 的身份验证是通过 Azure Active Directory (AAD) 完成的。Authentication on the REST API is done through Azure Active Directory(AAD). 要详细了解如何从 Azure 门户获取媒体服务帐户所需的身份验证详细信息,请参阅通过 Azure AD 身份验证访问 Azure 媒体服务 APIFor details on how to get required authentication details for your Media Services account from the Azure Portal, see Access the Azure Media Services API with Azure AD authentication.

有关使用 Azure AD 身份验证编写连接到 REST API 的代码的详细信息,请参阅通过 Azure AD 身份验证使用 REST 访问 Azure 媒体服务 APIFor details on writing code that connects to the REST API using Azure AD authentication, see the article Use Azure AD authentication to access the Azure Media Services API with REST.

后续步骤Next steps

要了解如何配合使用 Azure AD 身份验证和媒体服务 REST API,请参阅通过 Azure AD 身份验证使用 REST 访问 Azure 媒体服务 APITo learn how to use Azure AD authentication with Media Services REST API, see Use Azure AD authentication to access the Azure Media Services API with REST.

媒体服务学习路径Media Services learning paths

媒体服务 v3(最新版本)Media Services v3 (latest)

查看最新版本的 Azure 媒体服务!Check out the latest version of Azure Media Services!

媒体服务 v2(旧版)Media Services v2 (legacy)