Filter

Filters are used to define filters for assets’ 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 Filter to apply filters to any of your assets. Use AssetFilter to apply filters to a specific asset.

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

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

• Filter Properties

• Create a Filter

• List Filters

• Update a Filter

• Delete a Filter

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.

Filter properties

Property	Type	Description
Name	Edm.String	Friendly name of the filter.
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/Filters	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/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.19  
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000  
Host: media.windows.net  
  

Request body

{  
   "Name":"Mobile",  
   "PresentationTimeRange":{    
      "StartTimestamp":"0",  
      "EndTimestamp":"9223372036854775807",  
      "PresentationWindowDuration":"12000000000",  
      "LiveBackoffDuration":"0",  
      "Timescale":"10000000"  
   },  
   "Tracks":[    
      {    
         "PropertyConditions":[    
            {    
               "Property":"Type",  
               "Value":"video",  
               "Operator":"Equal"  
            },  
            {    
               "Property":"Bitrate",  
               "Value":"550000-1350000",  
               "Operator":"Equal"  
            }  
         ]  
      }  
   ]  
}  

Response

HTTP/1.1 201 Created  
. . .  
  

List filters

Filters can be retrieved using a HTTP GET request.

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

Method	Request URI	HTTP Version
GET	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.

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

Update a filter

Use PATCH, PUT or MERGE to update a Filter 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:

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

DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Filters('Mobile') 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