Creating Filters with Azure Media Services REST API
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)