Creating Filters with Azure Media Services REST API

  • Article

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.

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

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.

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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 two 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. 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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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 <ENCODED JWT TOKEN>
x-ms-version: 2.19
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)