使用 REST 管理媒体服务实体Managing Media Services entities with REST

Azure 媒体服务是一项以 OData v3 为基础的基于 REST 的服务。Azure Media Services is a REST-based service built on OData v3. 可以像在任何其他 OData 服务上一样添加、查询、更新和删除实体。You can add, query, update, and delete entities in much the same way as you can on any other OData service. 适用时,标注例外情况。Exceptions will be called out when applicable. 有关 OData 的详细信息,请参阅 开放数据协议文档For more information on OData, see Open Data Protocol documentation.

本主题介绍如何使用 REST 管理 Azure 媒体服务实体。This topic shows you how to manage Azure Media Services entities with REST.

备注

自 2017 年 4 月 1 日起,即使记录总数低于最大配额,也自动删除帐户中所有超过 90 天的作业记录,及其相关的任务记录。Starting April 1, 2017, any Job record in your account older than 90 days will be automatically deleted, along with its associated Task records, even if the total number of records is below the maximum quota. 例如,在 2017 年 4 月 1 日,用户帐户中 2016 年 12 月 31 日以前的任何作业记录都会被系统自动删除。For example, on April 1, 2017, any Job record in your account older than December 31, 2016, will be automatically deleted. 若需存档作业/任务信息,可使用本主题所述代码。If you need to archive the job/task information, you can use the code described in this topic.

注意事项Considerations

访问媒体服务中的实体时,必须在 HTTP 请求中设置特定标头字段和值。When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests. 有关详细信息,请参阅媒体服务 REST API 开发的设置For more information, see Setup for Media Services REST API Development.

连接到媒体服务Connect to Media Services

若要了解如何连接到 AMS API,请参阅通过 Azure AD 身份验证访问 Azure 媒体服务 APIFor information on how to connect to the AMS API, see Access the Azure Media Services API with Azure AD authentication.

添加实体Adding entities

媒体服务中的每个实体都通过 POST HTTP 请求添加到实体集(如资产)中。Every entity in Media Services is added to an entity set, such as Assets, through a POST HTTP request.

以下示例说明了如何创建 AccessPolicy。The following example shows how to create an AccessPolicy.

POST https://media.chinacloudapi.cn/API/AccessPolicies 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
Content-Length: 74
Expect: 100-continue

{"Name": "DownloadPolicy", "DurationInMinutes" : "300", "Permissions" : 1}

查询实体Querying entities

查询和列出实体非常简单,仅涉及 GET HTTP 请求和可选的 OData 操作。Querying and listing entities is straightforward and only involves a GET HTTP request and optional OData operations. 以下示例会检索包含所有 MediaProcessor 实体的列表。The following example retrieves a list of all MediaProcessor entities.

GET https://media.chinacloudapi.cn/API/MediaProcessors 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

也可检索特定实体或与特定实体关联的所有实体集,如以下示例所示:You can also retrieve a specific entity or all entity sets associated with a specific entity, such as in the following examples:

GET https://media.chinacloudapi.cn/API/JobTemplates('nb:jtid:UUID:e81192f5-576f-b247-b781-70a790c20e7c') 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

GET https://media.chinacloudapi.cn/API/JobTemplates('nb:jtid:UUID:e81192f5-576f-b247-b781-70a790c20e7c')/TaskTemplates 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

以下示例仅返回所有作业的 State 属性。The following example returns only the State property of all Jobs.

GET https://media.chinacloudapi.cn/API/Jobs?$select=State 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

以下示例返回名为“SampleTemplate”的所有 JobTemplate。The following example returns all JobTemplates with the name "SampleTemplate."

GET https://media.chinacloudapi.cn/API/JobTemplates?$filter=startswith(Name,%20'SampleTemplate') 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

备注

媒体服务不支持 $expand 操作以及“LINQ 注意事项(WCF Data Services)”中所述的不受支持的 LINQ 方法。The $expand operation is not supported in Media Services as well as the unsupported LINQ methods described in LINQ Considerations (WCF Data Services).

枚举大型实体集合Enumerating through large collections of entities

查询实体时,一次返回的实体数限制为 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. 使用 skip 和 top 枚举大型实体集合 。Use skip and top to enumerate through the large collection of entities.

以下示例说明如何使用 skip 和 top 来跳过前 2000 个作业并获取后 1000 个作业 。The following example shows how to use skip and top to skip the first 2000 jobs and get the next 1000 jobs.

GET https://media.chinacloudapi.cn/api/Jobs()?$skip=2000&$top=1000 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

更新实体Updating entities

根据实体类型及其所处的状态,可以通过 PATCH、PUT 或 MERGE HTTP 请求更新该实体上的属性。Depending on the entity type and the state that it is in, you can update properties on that entity through a PATCH, PUT, or MERGE HTTP requests. 有关这些操作的详细信息,请参阅 PATCH/PUT/MERGEFor more information about these operations, see PATCH/PUT/MERGE.

以下代码示例演示如何更新资产实体上的名称属性。The following code example shows how to update the Name property on an Asset entity.

MERGE https://media.chinacloudapi.cn/API/Assets('nb:cid:UUID:80782407-3f87-4e60-a43e-5e4454232f60') 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
Content-Length: 21
Expect: 100-continue

{"Name" : "NewName" }

删除实体Deleting entities

可以使用 DELETE HTTP 请求在媒体服务中删除实体。Entities can be deleted in Media Services by using a DELETE HTTP request. 删除实体的顺序可能很重要,具体视实体而定。Depending on the entity, the order in which you delete entities may be important. 例如,资产等实体要求先撤消(或删除)引用该特定资产的所有定位符,然后再删除资产。For example, entities such as Assets require that you revoke (or delete) all Locators that reference that particular Asset before deleting the Asset.

以下示例演示如何删除用于将文件上传到 blob 存储的定位符。The following example shows how to delete a Locator that was used to upload a file into blob storage.

DELETE https://media.chinacloudapi.cn/API/Locators('nb:lid:UUID:76dcc8e8-4230-463d-97b0-ce25c41b5c8d') 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
Content-Length: 0

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

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

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

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