Share via

AssetFilter

  • Article

AssetFilters are used to define filters for your asset’s streaming manifests. Defined filters can be applied to any of the following streaming protocols: HLS, MPEG-DASH, Smooth Streaming, and HDS. Media Services dynamically generates manifests based on specified filters. Filters can be defined at a global level (Filter) or asset level (AssetFilter). Use AssetFilter to apply filters to a specific asset. Use Filter to apply filters to any of your assets.

For a detailed overview and code samples of dynamically generated manifests, see Dynamic manifests overview.

This topic gives an overview of the AssetFilter entity (used to define local filters) and also demonstrates how to execute various operations with the Media Services REST API.

Important

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 and Connecting to Media Services with the Media Services REST API.

AssetFilter properties

Property Type Description
Id

Read-only. Set by Media Services at creation time.		 Edm.String Unique identifier.
ParentAssetId Edm.String The Id of a parent Asset that contains a collection of these filters.
Name Edm.String Friendly name for the AssetFilter.
PresentationTimeRange PresentationTimeRange The PresentationTimeRange rule group is used for filtering manifest start/end points, presentation window length, and the live start position. Media Services uses intersections of multiple ranges to define the final presentation window.
Tracks FilterTrackSelect Contains a collection of FilterTrackPropertyConditions.
FirstQuality FirstQuality First Quality of Manifest Filter, indicates the first quality bitrate for HLS.

Create a filter

Create a filter using HTTP POST request.

Method Request URI HTTP Version
POST https://<accountname>.restv2.<location>.media.azure.net/api/AssetFilters HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers

POST https://<accountname>.restv2.<location>.media.azure.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.19  
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000  
Host: media.windows.net

Request body

  
{    
   "Name":"TestFilter",  
   "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"  
            }  
         ]  
      }  
   ]  
}

Response

HTTP/1.1 201 Created  
. . .

List filters

Return all AssetFilters associated with an asset.

Method Request URI HTTP Version
GET https://<accountname>.restv2.<location>.media.azure.net/api/Assets('assetId')/AssetFilters() HTTP/1.1

Return a specific AssetFilters by specifying the AssetFilter Id that was returned when the entity was created.

Method Request URI HTTP Version
GET https://<accountname>.restv2.<location>.media.azure.net/api/ AssetFilters('assetFilterID') HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Get all AssetFilters associated with an asset.

GET https://<accountname>.restv2.<location>.media.azure.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.19  
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000  
Host: media.windows.net

Get an AssetFilter based on its ID.

GET https://<accountname>.restv2.<location>.media.azure.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.19  
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000  
Host: media.windows.net

Update a filter

Use PATCH, PUT or MERGE to update an AssetFilter with new property values.

Note

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.

Method Request URI HTTP Version
PATCH/PUT/MERGE

For more information about these operations, see PATCH/PUT/MERGE.		 https://<accountname>.restv2.<location>.media.azure.net/api/Filters(‘filterName’) HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

MERGE https://<accountname>.restv2.<location>.media.azure.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.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 a filter

Filters can be deleted using a HTTP DELETE request.

Method Request URI HTTP Version
DELETE https://<accountname>.restv2.<location>.media.azure.net/api/AssetFilters('assetFilterId') HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

DELETE https://<accountname>.restv2.<location>.media.azure.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.19  
Host: media.windows.net