Creating Filters with Azure Media Services REST API

Starting with 2.11 release, Media Services enables you to define filters for your assets. These filters are server side rules that will 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.

This topic 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

When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests. For more information, see Setup for Media Services REST API Development.

Connect to Media Services

For information on how to connect to the AMS API, see Access the Azure Media Services API with Azure AD authentication.

Note

After successfully connecting to https://media.windows.net, you will receive a 301 redirect specifying another Media Services URI. You must make subsequent calls to the new URI.

Create filters

Create global Filters

To create a global Filter, use the following HTTP requests:

HTTP Request

Request Headers

POST https://media.windows.net/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host:media.windows.net 

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 Response

HTTP/1.1 201 Created 

Create local AssetFilters

To create a local AssetFilter, use the following HTTP requests:

HTTP Request

Request Headers

POST https://media.windows.net/API/AssetFilters HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net  

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 Response

HTTP/1.1 201 Created 
. . . 

List filters

Get all global Filters in the AMS account

To list filters, use the following HTTP requests:

HTTP Request

GET https://media.windows.net/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Get AssetFilters associated with an asset

HTTP Request

GET https://media.windows.net/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 <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 

Get an AssetFilter based on its Id

HTTP Request

GET https://media.windows.net/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 <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000

Update filters

Use PATCH, PUT or MERGE to update a filter with new property values. For more information about these operations, see PATCH, PUT, MERGE.

If you update a filter, it can take up to 2 minutes for streaming endpoint to refresh the rules. If the content was served using this filter (and cached in proxies and CDN caches), updating this filter can result in player failures. It is recommend to clear the cache after updating the filter. If this option is not possible, consider using a different filter.

Update global Filters

To update a global filter, use the following HTTP requests:

HTTP Request

Request headers:

MERGE https://media.windows.net/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 <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 
Content-Length: 384

Request body:

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

Update local AssetFilters

To update a local filter, use the following HTTP requests:

HTTP Request

Request headers:

MERGE https://media.windows.net/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 <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 

Request body:

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

Delete filters

Delete global Filters

To delete a global Filter, use the following HTTP requests:

HTTP Request

DELETE https://media.windows.net/api/Filters('GlobalFilter') HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Delete local AssetFilters

To delete a local AssetFilter, use the following HTTP requests:

HTTP Request

DELETE https://media.windows.net/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 <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Build streaming URLs that use filters

For information on how to publish and deliver your assets, see Delivering Content to Customers Overview.

The following examples show how to add filters to your streaming URLs.

MPEG DASH

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

Apple HTTP Live Streaming (HLS) V4

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

Apple HTTP Live Streaming (HLS) V3

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

Smooth Streaming

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

Media Services learning paths

Read about the Azure Media Services learning paths:

Provide feedback

Use the User Voice forum to provide feedback and make suggestions on how to improve Azure Media Services. You also can go directly to one of the following categories:

See Also

Dynamic manifests overview