使用 Azure 媒体服务 REST API 创建筛选器Creating Filters with Azure Media Services REST API

从 2.17 版开始,可使用媒体服务为资产定义筛选器。Starting with 2.17 release, Media Services enables you to define filters for your assets. 这些筛选器是服务器端规则,可让客户选择运行如下操作:只播放一段视频(而非播放完整视频),或只指定客户设备可以处理的一部分音频和视频再现内容(而非与该资产相关的所有再现内容)。These filters are server-side rules that allow your customers to choose to do things like: playback only a section of a video (instead of playing the whole video), or specify only a subset of audio and video renditions that your customer's device can handle (instead of all the renditions that are associated with the asset). 通过按客户请求创建的动态清单可以实现对资产进行这种筛选,并基于指定的筛选器流式传输视频。This filtering of your assets is archived through Dynamic Manifests that are created upon your customer's request to stream a video based on specified filter(s).

有关与筛选器和动态清单相关的更多详细信息,请参阅动态清单概述For more detailed information related to filters and Dynamic Manifest, see Dynamic manifests overview.

本文介绍如何使用 REST API 创建、更新和删除筛选器。This article shows how to use REST APIs to create, update, and delete filters.

用于创建筛选器的类型Types used to create filters

创建筛选器时会使用以下类型:The following types are used when creating filters:

Note

访问媒体服务中的实体时,必须在 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.

创建筛选器Create filters

创建全局筛选器Create global Filters

若要创建全局筛选器,请使用以下 HTTP 请求:To create a global Filter, use the following HTTP requests:

HTTP 请求HTTP Request

请求标头Request Headers

POST https://media.chinacloudapi.cn/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host:media.chinacloudapi.cn

请求正文Request body

{  
   "Name":"GlobalFilter",
   "PresentationTimeRange":{  
      "StartTimestamp":"0",
      "EndTimestamp":"9223372036854775807",
      "PresentationWindowDuration":"12000000000",
      "LiveBackoffDuration":"0",
      "Timescale":"10000000"
   },
   "Tracks":[  
      {  
         "PropertyConditions":
              [  
            {  
               "Property":"Type",
               "Value":"audio",
               "Operator":"Equal"
            },
            {  
               "Property":"Bitrate",
               "Value":"0-2147483647",
               "Operator":"Equal"
            }
         ]
      }
   ]
}

HTTP 响应HTTP Response

HTTP/1.1 201 Created 

创建本地 AssetFilterCreate local AssetFilters

若要创建本地 AssetFilter,请使用以下 HTTP 请求:To create a local AssetFilter, use the following HTTP requests:

HTTP 请求HTTP Request

请求标头Request Headers

POST https://media.chinacloudapi.cn/API/AssetFilters HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.chinacloudapi.cn

请求正文Request body

{   
   "Name":"AssetFilter", 
   "ParentAssetId":"nb:cid:UUID:536e555d-1500-80c3-92dc-f1e4fdc6c592", 
   "PresentationTimeRange":{   
      "StartTimestamp":"0", 
      "EndTimestamp":"9223372036854775807", 
      "PresentationWindowDuration":"12000000000", 
      "LiveBackoffDuration":"0", 
      "Timescale":"10000000" 
   }, 
   "Tracks":[   
      {   
         "PropertyConditions": 
              [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

HTTP 响应HTTP Response

HTTP/1.1 201 Created 
. . . 

列出筛选器List filters

获取 AMS 帐户中的所有全局筛选器Get all global Filters in the AMS account

若要列出筛选器,请使用以下 HTTP 请求:To list filters, use the following HTTP requests:

HTTP 请求HTTP Request

GET https://media.chinacloudapi.cn/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
Host: media.chinacloudapi.cn

获取与资产关联的 AssetFilterGet AssetFilters associated with an asset

HTTP 请求HTTP Request

GET https://media.chinacloudapi.cn/API/Assets('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592')/AssetFilters HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.chinacloudapi.cn

基于 ID 获取 AssetFilterGet an AssetFilter based on its Id

HTTP 请求HTTP Request

GET https://media.chinacloudapi.cn/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__TestFilter') HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000

更新筛选器Update filters

使用 PATCH、PUT 或 MERGE 并结合新的属性值来更新筛选器。Use PATCH, PUT, or MERGE to update a filter with new property values. 有关这些操作的详细信息,请参阅 PATCH、PUT、MERGEFor more information about these operations, see PATCH, PUT, MERGE.

如果更新筛选器,则流式处理终结点需要两分钟的时间来刷新规则。If you update a filter, it can take up to two minutes for streaming endpoint to refresh the rules. 如果内容是通过使用此筛选器提供的(并在代理中缓存),则更新此筛选器会导致播放器失败。If the content was served using this filter (and cached in proxies), updating this filter can result in player failures. 请在更新筛选器之后清除缓存。Clear the cache after updating the filter. 如果此选项不可用,请考虑使用其他筛选器。If this option is not possible, consider using a different filter.

更新全局筛选器Update global Filters

若要更新全局筛选器,请使用以下 HTTP 请求:To update a global filter, use the following HTTP requests:

HTTP 请求HTTP Request

请求标头:Request headers:

MERGE https://media.chinacloudapi.cn/API/Filters('filterName') HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.chinacloudapi.cn
Content-Length: 384

请求正文:Request body:

{ 
   "Tracks":[   
      {   
         "PropertyConditions": 
         [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

更新本地 AssetFilterUpdate local AssetFilters

若要更新本地筛选器,请使用以下 HTTP 请求:To update a local filter, use the following HTTP requests:

HTTP 请求HTTP Request

请求标头:Request headers:

MERGE https://media.chinacloudapi.cn/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__TestFilter')  HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.chinacloudapi.cn

请求正文:Request body:

{ 
   "Tracks":[   
      {   
         "PropertyConditions": 
         [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

删除筛选器Delete filters

删除全局筛选器Delete global Filters

若要删除全局筛选器,请使用以下 HTTP 请求:To delete a global Filter, use the following HTTP requests:

HTTP 请求HTTP Request

DELETE https://media.chinacloudapi.cn/api/Filters('GlobalFilter') HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN>  
x-ms-version: 2.19 
Host: media.chinacloudapi.cn

删除本地 AssetFilterDelete local AssetFilters

若要删除本地 AssetFilter,请使用以下 HTTP 请求:To delete a local AssetFilter, use the following HTTP requests:

HTTP 请求HTTP Request

DELETE https://media.chinacloudapi.cn/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__LocalFilter') HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <ENCODED JWT TOKEN> 
x-ms-version: 2.19 
Host: media.chinacloudapi.cn 

生成使用筛选器的流 URLBuild streaming URLs that use filters

有关如何发布和传送资产的信息,请参阅将内容传送到客户概述For information on how to publish and deliver your assets, see Delivering Content to Customers Overview.

以下示例演示了如何将筛选器添加到流 URL。The following examples show how to add filters to your streaming URLs.

MPEG DASHMPEG DASH

http://testendpoint-testaccount.streaming.mediaservices.chinacloudapi.cn/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=mpd-time-csf, filter=MyFilter)

Apple HTTP Live Streaming (HLS) V4Apple HTTP Live Streaming (HLS) V4

http://testendpoint-testaccount.streaming.mediaservices.chinacloudapi.cn/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=m3u8-aapl, filter=MyFilter)

Apple HTTP Live Streaming (HLS) V3Apple HTTP Live Streaming (HLS) V3

http://testendpoint-testaccount.streaming.mediaservices.chinacloudapi.cn/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=m3u8-aapl-v3, filter=MyFilter)

平滑流式处理Smooth Streaming

http://testendpoint-testaccount.streaming.mediaservices.chinacloudapi.cn/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(filter=MyFilter)

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

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

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

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

另请参阅See Also

动态清单概述Dynamic manifests overview