Skip to main content

Search

Ravnur Knowledge Base

RMS filtering, ordering, and paging

Alla Blinova
  • Updated

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:

Get started

What you can filter and order

Filters in AMSE (Azure Media Services Explorer)

Monitoring and performance considerations

Complex query building

 

Before you begin

Ensure you have access to the Ravnur Media API using RMS 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 AMS documentation for the 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 $skiptokenparameter 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

 

Filters in Azure Media Services Explorer

Azure Media Services Explorer (AMSE) simplifies many tasks associated with managing media services, making it a valuable tool for anyone involved in media processing and streaming on the Ravnur platform. Learn more.

When using AMSE, you can filter assets by:

82a85cfa-fcc7-4f1c-9c09-4614ad7d1b4b.png

  • Name: there are sorting options like equals, starts with, greater than (Z-A order), and less than (A-Z order).

  • ID: Filter by asset ID.

  • Alt ID: Alternate ID is a secondary identifier that users can assign to the asset. Unlike asset ID, it is optional and therefore can be empty. Example of the asset alternate ID: 001_XYZ.mp4

Common Parameters for Jobs and Assets

  • Date of creation. Access the filter list by clicking on Filter: All items.

Order records

  • select the ascending or descending order based on the creation date.

  • Choose alphabetical ordering (A-Z) or reverse (Z-A) for names.

Jobs parameters80ead486-7737-4c26-b8ff-7f0e9a5e405a.png

  • Job name

  • Job ID

  • State: filter jobs additionally by their State to view, for example, only those in the Queued or Finished states.

 

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

While AMSE doesn’t support combining filters or combining ordering options due to its limitations, the RMS API does support 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, you can create a range by using gt (greater than) for the start of the range and lt (less than) for the end of the range to search for assets created on the 14th of 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 the name property in descending order.

 

 

 

Powered by Zendesk