媒体服务实体的筛选、排序和分页Filtering, ordering, and paging of Media Services entities

媒体服务徽标 v3media services logo v3


本主题讨论在列出 Azure 媒体服务 v3 实体时可以使用的 OData 查询选项和分页支持。This topic discusses the OData query options and pagination support available when you're listing Azure Media Services v3 entities.

注意事项Considerations

  • 属于 Datetime 类型的实体的属性始终采用 UTC 格式。Properties of entities that are of the Datetime type are always in UTC format.
  • 在发送请求之前,应将查询字符串中的空格进行 URL 编码。White space in the query string should be URL-encoded before you send a request.

比较运算符Comparison operators

可以使用以下运算符将字段与常量值进行比较:You can use the following operators to compare a field to a constant value:

相等性运算符:Equality operators:

  • eq:测试某个字段是否等于某个常量值。eq: Test whether a field is equal to a constant value.
  • ne:测试某个字段是否不等于某个常量值。ne: Test whether a field is not equal to a constant value.

范围运算符:Range operators:

  • gt:测试某个字段是否大于某个常量值。gt: Test whether a field is greater than a constant value.
  • lt:测试某个字段是否小于某个常量值。lt: Test whether a field is less than a constant value.
  • ge:测试某个字段是否大于或等于 某个常数值。ge: Test whether a field is greater than or equal to a constant value.
  • le:测试某个字段是否小于或等于某个常量值。le: Test whether a field is less than or equal to a constant value.

筛选器Filter

使用 $filter 提供一个 OData 筛选器参数,以便只查找感兴趣的对象。Use $filter to supply an OData filter parameter to find only the objects you're interested in.

下面的 REST 示例根据资产的 alternateId 值进行筛选:The following REST example filters on the alternateId value of an asset:

GET https://management.chinacloudapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaServices/amstestaccount/assets?api-version=2018-07-01&$filter=properties/alternateId%20eq%20'unique identifier'

下面的 C# 示例根据资产的创建日期进行筛选:The following C# example filters on the asset's created date:

var odataQuery = new ODataQuery<Asset>("properties/created lt 2018-05-11T17:39:08.387Z");
var firstPage = await MediaServicesArmClient.Assets.ListAsync(CustomerResourceGroup, CustomerAccountName, odataQuery);

排序依据Order by

使用 $orderby 按指定的参数对返回的对象排序。Use $orderby to sort the returned objects by the specified parameter. 例如:For example:

GET https://management.chinacloudapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaServices/amstestaccount/assets?api-version=2018-07-01$orderby=properties/created%20gt%202018-05-11T17:39:08.387Z

若要按升序或降序对结果排序,请将用空格分隔的 ascdesc 追加到字段名称。To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space. 例如:$orderby properties/created descFor example: $orderby properties/created desc.

跳过令牌Skip token

如果查询响应包含许多项,则服务将返回一个 $skiptoken (@odata.nextLink) 值,用于获取下一页结果。If a query response contains many items, the service returns a $skiptoken (@odata.nextLink) value that you use to get the next page of results. 使用它可以逐页浏览整个结果集。Use it to page through the entire result set.

在媒体服务 v3 中,无法配置页面大小。In Media Services v3, you can't configure the page size. 页面大小因实体类型而异。The page size varies by the type of entity. 请阅读以下各个部分,了解详细信息。Read the individual sections that follow for details.

如果在对集合进行分页时创建或删除了实体,则返回的结果中会反映这些更改(如果这些更改位于集合中尚未下载的部分中)。If entities are created or deleted while you're paging through the collection, the changes are reflected in the returned results (if those changes are in the part of the collection that hasn't been downloaded).

提示

始终使用 nextLink 来枚举集合,而不依赖于特定的页面大小。Always use nextLink to enumerate the collection and don't depend on a particular page size.

nextLink 值存在的前提是有多个页面的实体。The nextLink value will be present only if there's more than one page of entities.

考虑以下使用 $skiptoken 的示例。Consider the following example of where $skiptoken is used. 请务必将 amstestaccount 替换为你的帐户名,并将 api-version 值设置为最新版本。Make sure you replace amstestaccount with your account name and set the api-version value to the latest version.

如果按如下所示请求列出资产:If you request a list of assets like this:

GET  https://management.chinacloudapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaServices/amstestaccount/assets?api-version=2018-07-01 HTTP/1.1
x-ms-client-request-id: dd57fe5d-f3be-4724-8553-4ceb1dbe5aab
Content-Type: application/json; charset=utf-8

将返回类似于以下内容的响应:You'll get back a response similar to this one:

HTTP/1.1 200 OK

{
"value":[
{
"name":"Asset 0","id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/amstestaccount/assets/Asset 0","type":"Microsoft.Media/mediaservices/assets","properties":{
"assetId":"00000000-0000-0000-0000-000000000000","created":"2018-12-11T22:12:44.98Z","lastModified":"2018-12-11T22:15:48.003Z","container":"asset-00000000-0000-0000-0000-0000000000000","storageAccountName":"amsacctname","storageEncryptionFormat":"None"
}
},
// lots more assets
{
"name":"Asset 517","id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/amstestaccount/assets/Asset 517","type":"Microsoft.Media/mediaservices/assets","properties":{
"assetId":"00000000-0000-0000-0000-000000000000","created":"2018-12-11T22:14:08.473Z","lastModified":"2018-12-11T22:19:29.657Z","container":"asset-00000000-0000-0000-0000-000000000000","storageAccountName":"amsacctname","storageEncryptionFormat":"None"
}
}
],"@odata.nextLink":"https:// management.chinaclouapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaServices/amstestaccount/assets?api-version=2018-07-01&$skiptoken=Asset+517"
}

然后通过发送 Get 请求来请求显示下一页:You would then request the next page by sending a get request for:

https://management.chinacloudapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mediaresources/providers/Microsoft.Media/mediaServices/amstestaccount/assets?api-version=2018-07-01&$skiptoken=Asset+517

以下 C# 示例显示如何枚举帐户中的所有流式处理定位符。The following C# example shows how to enumerate through all streaming locators in the account.

var firstPage = await MediaServicesArmClient.StreamingLocators.ListAsync(CustomerResourceGroup, CustomerAccountName);

var currentPage = firstPage;
while (currentPage.NextPageLink != null)
{
    currentPage = await MediaServicesArmClient.StreamingLocators.ListNextAsync(currentPage.NextPageLink);
}

使用逻辑运算符来组合查询选项Using logical operators to combine query options

媒体服务 v3 支持 ORAND 逻辑运算符。Media Services v3 supports OR and AND logical operators.

以下 REST 示例检查作业的状态:The following REST example checks the job's state:

https://management.chinacloudapi.cn/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/qbtest/providers/Microsoft.Media/mediaServices/qbtest/transforms/AdaptiveStreaming/jobs?$filter=properties/state%20eq%20Microsoft.Media.JobState'Scheduled'%20or%20properties/state%20eq%20Microsoft.Media.JobState'Processing'&api-version=2018-07-01

可以在 C# 中构造同一查询,如下所示:You construct the same query in C# like this:

var odataQuery = new ODataQuery<Job>("properties/state eq Microsoft.Media.JobState'Scheduled' or properties/state eq Microsoft.Media.JobState'Processing'");
client.Jobs.List(config.ResourceGroup, config.AccountName, AdaptiveStreaming, odataQuery);

实体的筛选和排序选项Filtering and ordering options of entities

下表显示了如何将筛选和排序选项应用于不同实体:The following table shows how you can apply the filtering and ordering options to different entities:

实体名称Entity name 属性名称Property name 筛选器Filter 订单Order
资产Assets namename eqgtltgeleeq, gt, lt, ge, le ascdescasc and desc
properties.alternateIdproperties.alternateId eq
properties.assetIdproperties.assetId eq
properties.createdproperties.created eqgtlteq, gt, lt ascdescasc and desc
内容密钥策略Content key policies namename eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.createdproperties.created eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.descriptionproperties.description eqnegelegtlteq, ne, ge, le, gt, lt
properties.lastModifiedproperties.lastModified eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.policyIdproperties.policyId eq, neeq, ne
作业Jobs namename eq ascdescasc and desc
properties.stateproperties.state eq, neeq, ne
properties.createdproperties.created gtgeltlegt, ge, lt, le ascdescasc and desc
properties.lastModifiedproperties.lastModified gtgeltlegt, ge, lt, le ascdescasc and desc
流式处理定位符Streaming locators namename eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.createdproperties.created eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.endTimeproperties.endTime eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
流式处理策略Streaming policies namename eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
properties.createdproperties.created eqnegelegtlteq, ne, ge, le, gt, lt ascdescasc and desc
转换Transforms namename eq ascdescasc and desc
properties.createdproperties.created gtgeltlegt, ge, lt, le ascdescasc and desc
properties.lastModifiedproperties.lastModified gtgeltlegt, ge, lt, le ascdescasc and desc

后续步骤Next steps