Filtering, ordering, and paging help you narrow down search results based on specific criteria, like showing only completed encoding jobs or finding assets created after a certain date. This article explains how to use filters to refine searches, sort results, and handle large datasets.
In this article:
Monitoring and performance considerations
Before you begin
- Authenticate using the RMS API Authentication
Get started
Advantages
Filtering, ordering, and paging in the RMS API mirror the behaviors of AMS on this matter. This compatibility allows you to adapt existing SDKs to work with the RMS API without changes to your code.
Examples of how to apply filters, ordering, and paging
Use filtering, ordering, and paging as on examples in a REST API request format, using the URL structure:
1. Filtering
Retrieve only finished jobs using filtering by state:
GET https://{{apiEndpoint}}/subscriptions/:subscriptionId/resourceGroups/:resourceGroup/providers/Microsoft.Media/mediaServices/:accountName/assets?$filter=properties/state eq 'Finished'&api-version={{api-version}}
This filters the query to return only assets where the state is "Finished": $filter=properties/state eq 'Finished'
2. Ordering
List assets in alphabetical order (A-Z) using ordering by name:
GET https://{{apiEndpoint}}/subscriptions/:subscriptionId/resourceGroups/:resourceGroup/providers/Microsoft.Media/mediaServices/:accountName/assets?$orderby=name asc&api-version={{api-version}} This orders the results by name in ascending (A-Z) order: $orderby=name asc
3. Paging
Return the first 10 results and continue with a skip token:
GET https://{{apiEndpoint}}/subscriptions/:subscriptionId/resourceGroups/:resourceGroup/providers/Microsoft.Media/mediaServices/:accountName/assets?$top=10&$skiptoken=Asset+30&api-version={{api-version}} Use the skip token to continue retrieving assets from item 31 onwards: $skiptoken=Asset+30
Base request URL structure:
-
$filter: filter results based on specific conditions. -
api-version={{api-version}}: This specifies the version of the AMS API you used. Any valid version number will work for your requests, e.g.api-version=2018-07-01. -
{{apiEndpoint}}: Placeholder for the actual API endpoint -
subscriptionId: This is your Azure subscription ID, a unique identifier for your Azure subscription. -
resourceGroup: The name of the resource group where your Media Services account is located. -
accountName: This is the name of your Media Services account.
Ensure that you accurately replace these placeholders with the corresponding values from your Azure account to configure the API request correctly. Learn how to find your API values.
Navigate to the AMS documentation for C# syntax examples.
What you can filter and order
RMS fully supports all filters available in AMS, including range and equality operators, as well as the $skiptoken parameter for paging through results. Understanding these filters is key when using the RMS API.
The following table shows how to apply filtering and ordering options to different entities:
| Entity name | Property name | Filter | Order |
|---|---|---|---|
| Assets | name |
eq, gt, lt, ge, le
|
asc, desc
|
| properties/alternateId | eq |
||
| properties/assetId | eq |
||
| properties/created |
eq, gt, lt
|
asc, desc
|
|
| Content key policies | name |
eq, ne, ge, le, gt, lt
|
asc, desc
|
| properties/created |
eq, ne, ge, le, gt, lt
|
asc, desc
|
|
| properties/description |
eq, ne, ge, le, gt, lt
|
||
| properties/lastModified |
eq, ne, ge, le, gt, lt
|
asc, desc
|
|
| properties/policyId |
eq, ne
|
||
| Jobs | name | eq |
asc, desc
|
| properties/state |
eq, ne
|
||
| properties/created |
gt, ge, lt, le
|
asc, desc
|
|
| properties/lastModified |
gt, ge, lt, le
|
asc, desc
|
|
| Streaming locators | name |
eq, ne, ge, le, gt, lt
|
asc, desc
|
| properties/created |
eq, ne, ge, le, gt, lt
|
asc, desc
|
|
| properties/endTime |
eq, ne, ge, le, gt, lt
|
asc, desc
|
|
| Streaming policies | name |
eq, ne, ge, le, gt, lt
|
asc, desc
|
| properties/created |
eq, ne, ge, le, gt, lt
|
asc, desc
|
|
| Transforms | name | eq |
asc, desc
|
| properties/created |
gt, ge, lt, le
|
asc, desc
|
|
| properties/lastModified |
gt, ge, lt, le
|
asc, desc
|
|
| Live Events | name | eq |
|
| properties/created | eq |
asc, desc
|
|
| properties/resourceState | eq |
Monitoring and performance considerations
When filtering jobs by state, consider the performance implications, particularly when dealing with large datasets. Filtering and paging through large data sets may impact system performance and result in higher operational costs. When you frequently check the state of jobs or other entities using GET requests, it uses more processing power, which can affect overall performance as the data grows.
Better option: use Event Grid
For improved performance, use Event Grid. Event Grid provides real-time notifications, such as when a job's state changes. This way, there is no need to repeatedly query the API for updates.
Benefits:
- Less load: fewer API requests mean less strain on your system.
- Cost-effective: using fewer resources saves money.
- Quick updates: get immediate alerts when something changes, so you can respond faster.
Complex query building
RMS API supports the use of logical operators like OR and AND. This allows building complex queries such as:
GET https://{{apiEndpoint}}/subscriptions/:subscriptionId/resourceGroups/:resourceGroup/providers/Microsoft.Media/mediaServices/:accountName/assets?$filter=properties/created gt 2024-07-13T23:59:59Z and properties/created lt 2024-07-15T00:00:00Z&$orderby=name desc&api-version={{api-version}}This example demonstrates the following in a single request:
- use of multiple filters
- ordering the results.
Logical operators usage:
-
$filter: filter results based on specific conditions. -
properties/created gt 2024-07-13T23:59:59Z: Filters for assets created after 13th July 2024, 23:59:59. -
properties/created lt 2024-07-15T00:00:00Z: Filters for assets created before 15th July 2024, 00:00:00.
Use only available operators according to the table. As an example, a range can be created by using
gt(greater than) for the start of the range andlt(less than) for the end of the range to search for assets created on 14 July 2024.
-
and: The logical operator combines conditions so that the query retrieves results created both after the 14th of July begins and before it ends. -
$orderby=name desc: Orders the results by thenameproperty in descending order.
See more: