Queries information about videos, audio, images, and auxiliary media assets. You can call this operation and specify the search protocol to query media assets based on the return fields, fields used for exact match, fields used for fuzzy match, fields used for a multi-value query, fields used for a range query, and sort fields.
Operation description
The maximum number of data records that you can query varies based on the method used to query the data. You can use the following methods to query data:
-
Method 1: Traverse data by page
You can use the PageNo and PageSize parameters to traverse up to 5,000 data records that meet the specified filter condition. PageNo specifies the page number and PageSize specifies the number of data records displayed on a page. If the number of data records that meet the specified filter condition exceeds 5,000, change the filter conditions to narrow down the results. You cannot use this method to traverse all data records. If you want to traverse more data records, use Method 2.
-
Method 2: Traverse all data (available only for audio and video files)
You can use this method to traverse up to 2 million data records related to audio and video files. If the number of data records that meet the specified filter condition exceeds 2 million, change the filter conditions to narrow down the results. To traverse data page by page, you must set the PageNo, PageSize, and ScrollToken parameters. The total number of data records from the current page to the target page cannot exceed 100. For example, you set PageSize to 20. The following content describes the traverse logic:
- When the PageNo parameter is set to 1, you can traverse data records from page 1 to page 5.
- When the PageNo parameter is set to 2, you can traverse data records from page 2 to page 6.
Make sure that you set the appropriate page number and page size, and use a traverse method based on the number of results that meet your filter condition.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| vod:SearchMedia | list | *All Resources * |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| SearchType | string | No | The type of the media asset that you want to query. Default value: video. Valid values:
Note
If this parameter is set to video or audio and you want to traverse all data that meets the filter criteria, you must set the ScrollToken parameter.
| video |
| Fields | string | No | The media asset fields to return in the query results. By default, only the basic media asset fields are returned. You can specify additional media asset fields that need to be returned in the request. For more information, see the "API examples" section of the Search for media asset information topic. | Title,CoverURL |
| Match | string | No | The filter condition. For more information about the syntax, see Protocol for media asset search. | field = value |
| SortBy | string | No | The sort field and order. Separate multiple values with commas (,). Default value: CreationTime:Desc. Valid values:
Note
| CreationTime:Desc |
| PageNo | integer | No | The number of the page to return. Default value: 1. Note
If the value of this parameter exceeds 200, we recommend that you set the ScrollToken parameter as well.
| 1 |
| PageSize | integer | No | The number of entries to return on each page. Default value: 10. Maximum value: 100. | 10 |
| ScrollToken | string | No | The pagination identifier. The password must be 32 characters in length The first time you call this operation for each new search, you do not need to specify this parameter. The value of this parameter is returned each time data records that meet the specified filter condition are found. The value is used to record the current position of queried data. Record the returned parameter value and set this parameter according to the following requirements during the next search:
| 24e0fba7188fae707e146esa54**** |
Response parameters
Examples
Sample success responses
JSONformat
{
"RequestId": "3E0CEF83-FB09-4E34-BA1451814B03****",
"Total": 10,
"ScrollToken": "24e0fba7188fae707e146esa54****",
"MediaList": [
{
"CreationTime": "2018-07-19T03:45:25Z",
"MediaType": "video",
"MediaId": "a82a2cd7d4e147bbed6c1ee372****",
"Video": {
"Status": "UploadSucc",
"CreationTime": "2018-07-19T03:45:25Z",
"StorageLocation": "outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com",
"CateId": 10000123,
"Tags": "tag1",
"ModificationTime": "2018-07-19T03:48:25Z",
"MediaSource": "general",
"Description": "Video test",
"AppId": "app-****",
"CoverURL": "https://example.aliyundoc.com/image01.png",
"VideoId": "a82a2asdasqadaf3faa0ed6c1ee372****",
"DownloadSwitch": "on",
"CateName": "video1",
"TranscodeMode": "FastTranscode",
"PreprocessStatus": "Preprocessing",
"RestoreExpiration": "2023-03-30T10:14:14Z",
"RestoreStatus": "Success",
"StorageClass": "Standard",
"Size": 123,
"Duration": 123,
"Title": "ceshi",
"SpriteSnapshots": [
"{“http://example.aliyundoc.com/image02.jpg”}"
],
"Snapshots": [
"{“http://example.aliyundoc.com/image03.jpg”}"
]
},
"Audio": {
"Status": "Normal",
"CreationTime": "2018-07-19T03:45:25Z",
"StorageLocation": "outin-aaa*****aa.oss-cn-shanghai.aliyuncs.com",
"CateId": 10000123,
"Tags": "tag1,tag2",
"ModificationTime": "2018-07-19T03:48:25Z",
"MediaSource": "general",
"Description": "audio description",
"AppId": "app-****",
"CoverURL": "http://example.com/image04.jpg",
"AudioId": "a82a2cd7d4e147bbed6c1ee372****",
"DownloadSwitch": "on",
"CateName": "ceshi",
"TranscodeMode": "FastTranscode",
"PreprocessStatus": "UnPreprocess",
"RestoreExpiration": "2023-03-30T10:14:14Z",
"RestoreStatus": "Success",
"StorageClass": "Standard",
"Size": 123,
"Duration": 123,
"Title": "audio",
"SpriteSnapshots": [
"{“http://example.aliyundoc.com/image02.jpg”}"
],
"Snapshots": [
"{“http://example.aliyundoc.com/image03.jpg”}"
]
},
"Image": {
"StorageLocation": "outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com",
"CreationTime": "2018-07-19T03:45:25Z",
"Status": "Uploading",
"CateId": 1000123,
"Tags": "tag1",
"ModificationTime": "2018-07-19T03:48:25Z",
"CateName": "beauty",
"Description": "image test",
"AppId": "app-****",
"URL": "https://example.com/****.png",
"Title": "image1",
"ImageId": "11130843741se99wqmoes****"
},
"AttachedMedia": {
"CreationTime": "2018-07-19T03:45:25Z",
"Status": "Normal",
"StorageLocation": "outin-bfefbb90a47c11*****7426.oss-cn-shanghai.aliyuncs.com",
"Tags": "test2",
"ModificationTime": "2018-07-19T03:48:25Z",
"MediaId": "a82a2cd7d4e147ba0ed6c1ee372****",
"BusinessType": "watermark",
"Description": "test3",
"AppId": "app-****",
"URL": "https://example.com/****.png",
"Title": "test",
"Categories": [
{
"ParentId": -1,
"CateName": "test1",
"CateId": 10027394,
"Level": 1
}
]
},
"AiData": {
"AiLabelInfo": [
{
"Category": "Transportation",
"LabelName": "Vehicles",
"LabelId": "10310250338",
"Occurrences": [
{
"Score": 0.75287705,
"From": 1.4,
"To": 2.5
}
]
}
],
"OcrInfo": [
{
"From": 1.4,
"To": 2.5,
"Content": "I'm Jane."
}
]
},
"AiRoughData": {
"SaveType": "TEXT\n",
"Status": "SaveSuccess",
"AiJobId": "cd35b0b0025f71edbfcb472190a9xxxx",
"AiCategory": "TV series"
}
}
]
}Error codes
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2023-04-11 | The response structure of the API has changed | View Change Details |
Common errors
The following table describes the common errors that this operation can return.
| Error code | Error message | HTTP status code | Description |
|---|---|---|---|
| SortByExceededMax | The SortBy parameter only supports one sort field when traversing all data. | 400 | The error message returned because more than one sort field is specified to traverse all data. |
| ErrorMatchSyntax | The parameter Match.%s has an error syntax, please check it. | 400 | The error message returned because the syntax of the Match parameter is invalid. Check the syntax and try again. |
| InvalidScrollToken.Expired | The ScrollToken is expired, please refresh it. | 400 | The error message returned because the value of the ScrollToken parameter is invalid. Obtain data again from Page 1. |