The media search protocol is a real-time search protocol that integrates retrieval, filtering, sorting, and pagination. You can use the protocol to query information about media assets such as videos, audio, and images in ApsaraVideo VOD. This topic describes the syntax of the protocol that is used for media asset search in ApsaraVideo VOD. You must use the protocol together with the SearchMedia operation. You can configure the Match parameter to query media assets based on 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.
Syntax
Media asset fields are classified into the following categories based on the syntax rules that are defined in the protocol for media asset search: 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. For more information about all media asset fields supported by ApsaraVideo VOD and the applicable syntax rules, see Media asset information.
When you call the SearchMedia operation to query media asset information, you must perform URL encoding on the query statement. In addition, you must use single-byte punctuation marks such as equal signs (=), double quotation marks ("), single quotation marks ('), and parentheses () in the query statement. For more information about special characters that are defined in the protocol for media asset search, see Special characters.
The following table describes the syntax that is defined in the protocol for media asset search and provides search examples.
Category | Description | Syntax | Example |
Return field | Specifies the fields that you want to return in the search results. By default, only the ID, creation time, and type of each media asset are returned. | field1,field2 | |
Field used for exact match | Queries information about the media assets that match the exact value of a specified field. | field = value | |
Field used for fuzzy match | Queries information about the media assets whose value of a specified field contains the specified characters or strings. | field in ('value1','value2') or field = 'value' | |
Field used for a multi-value query | Queries information about the media assets that match one of the values of a specified field. | field in ('value1','value2') | |
Field used for a range query | Queries information about the media assets whose value of a specified field falls in a specified open or closed interval. | field = (value1,value2) | |
Sort fields | Specifies the fields based on which the search results are sorted and the order in which the search results are sorted. The descending order and ascending order are supported. Multiple sort fields are displayed from left to right based on their priorities in descending order. | SortBy = field:Desc |
Special characters
Character | Description | Syntax |
and | Connects two filter conditions to query information about the media assets that meet both filter conditions. | field1 = 'value' and field2 = 'value' |
or | Connects two filter conditions to query information about the media assets that meet one of the filter conditions. If you use the OR operator in the query statement, you must enclose the filter conditions in a pair of parentheses (). | (field1 = 'value1' or field2 = 'value2') |
( ) | Encloses a specified open or closed interval for a range query. | field = ('value1','value2') |
( ) | Encloses multiple filter conditions in the OR relationship. | (field1 = 'value1' or field2 = 'value2') |
' ' | Encloses field values of the STRING type. | field = 'value' |
, | Separates multiple field values for a multi-value query. You can separate multiple field values with commas (,). | field in ('value1','value2') |
( ) [ ] | Specifies an open or closed interval for a range query. You can specify whether to include or exclude the left endpoint and right endpoint of the interval. | field = ['value1','value2'] |
in | Specifies multiple values for a field in a multi-value query to query information about the media assets that match one of the values of the specified field. | field in ('value1','value2') |
Media asset information
ApsaraVideo VOD allows you to query information about specified video, audio, and image files, and auxiliary media assets. The following tables describe the syntax rules that are applicable to various media asset fields. √ in the following tables indicates that the field is supported and × indicates that the field is not supported.
You can specify a maximum of three values for multi-value queries.
Each string for fuzzy match can be up to 60 characters in length.
If you cannot obtain a precise hit from fuzzy search by using the Title field together with another field, check your statement for format errors. Example of fuzzy search:
(Title = 'Test' and Description = 'Description')
.
Video: information about a video
Field | Type | Description | Used as a return field | Used for exact match | Used for fuzzy match | Used for a multi-value query | Used for a range query | Used as a sort field |
VideoId | String | The ID of the video. | ✓ | ✓ | × | ✓ | × | × |
AppId | String | The ID of the application. | ✓ | × | × | ✓ | × | × |
CateId | Long | The ID of the category to which the video belongs. | ✓ | ✓ | × | × | × | × |
CateName | String | The name of the category to which the video belongs. | ✓ | × | × | × | × | × |
StorageLocation | String | The region where the video is stored. | ✓ | ✓ | × | ✓ | × | × |
Title | String | The title of the video. | ✓ | × | ✓ | × | × | × |
Tags | String | The tags of the video. | ✓ | × | ✓ | ✓ | × | × |
Description | String | The description of the video. | ✓ | × | ✓ | × | × | × |
Status | String | ✓ | × | × | ✓ | × | × | |
MediaSource | String | ✓ | × | × | ✓ | × | × | |
PreprocessStatus | String | ✓ | × | × | ✓ | × | × | |
Size | Long | The size of the video. | ✓ | × | × | × | ✓ | × |
Duration | Float | The duration of the video. | ✓ | × | × | × | ✓ | × |
CreationTime | String | The time when the video was created. | ✓ | × | × | × | ✓ | ✓ |
ModificationTime | String | The time when the video was last updated. | ✓ | × | × | × | ✓ | ✓ |
CoverURL | String | The URL of the thumbnail. | ✓ | × | × | × | × | × |
Snapshots | String[] | The list of automatic snapshots. | ✓ | × | × | × | × | × |
SpriteSnapshots | String[] | The list of image sprites. | ✓ | × | × | × | × | × |
DownloadSwitch | String | ✓ | × | × | × | × | × | |
TranscodeMode | String | ✓ | × | × | × | × | × | |
StorageClass | String | ✓ | × | × | ✓ | × | × |
Audio: information about an audio file
Field | Type | Description | Used as a return field | Used for exact match | Used for fuzzy match | Used for a multi-value query | Used for a range query | Used as a sort field |
AudioId | String | The ID of the audio. | ✓ | ✓ | × | × | × | × |
AppId | String | The ID of the application. | ✓ | × | × | ✓ | × | × |
CateId | Long | The ID of the category to which the audio belongs. | ✓ | ✓ | × | × | × | × |
CateName | String | The name of the category to which the audio belongs. | ✓ | × | × | × | × | × |
StorageLocation | String | The region where the audio is stored. | ✓ | × | × | ✓ | × | × |
Title | String | The title of the audio. | ✓ | × | ✓ | × | × | × |
Tags | String | The tags of the audio. | ✓ | × | ✓ | ✓ | × | × |
Description | String | The description of the audio. | ✓ | × | ✓ | × | × | × |
Status | String | ✓ | × | × | ✓ | × | × | |
MediaSource | String | ✓ | × | × | ✓ | × | × | |
PreprocessStatus | String | ✓ | × | × | ✓ | × | × | |
Size | Long | The size of the audio. | ✓ | × | × | × | ✓ | × |
Duration | Float | The duration of the audio. | ✓ | × | × | × | ✓ | × |
CreationTime | String | The time when the audio was created. | ✓ | × | × | × | ✓ | ✓ |
ModificationTime | String | The time when the audio was last updated. | ✓ | × | × | × | ✓ | ✓ |
CoverURL | String | The URL of the thumbnail. | ✓ | × | × | × | × | × |
Snapshots | String[] | The list of automatic snapshots. | ✓ | × | × | × | × | × |
SpriteSnapshots | String[] | The list of image sprites. | ✓ | × | × | × | × | × |
DownloadSwitch | String | ✓ | × | × | × | × | × | |
TranscodeMode | String | ✓ | × | × | × | × | × | |
StorageClass | String | ✓ | × | × | ✓ | × | × |
Image: information about an image
Field | Type | Description | Used as a return field | Used for exact match | Used for fuzzy match | Used for a multi-value query | Used for a range query | Used as a sort field |
ImageId | String | The ID of the image. | ✓ | ✓ | × | × | × | × |
AppId | String | The ID of the application. | ✓ | × | × | ✓ | × | × |
CateId | Long | The ID of the category to which the image belongs. | ✓ | ✓ | × | × | × | × |
CateName | String | The name of the category to which the image belongs. | ✓ | × | × | × | × | × |
StorageLocation | String | The region where the image is stored. | ✓ | ✓ | × | ✓ | × | × |
FileName | String | The file name of the image. | ✓ | × | ✓ | × | × | × |
Title | String | The title of the image. | ✓ | × | ✓ | × | × | × |
Tags | String | The tags of the image. | ✓ | × | ✓ | ✓ | × | × |
Description | String | The description of the image. | ✓ | × | ✓ | × | × | × |
Status | String | ✓ | × | × | ✓ | × | × | |
CreationTime | String | The time when the image was created. | ✓ | × | × | × | ✓ | ✓ |
ModificationTime | String | The time when the image was last updated. | ✓ | × | × | × | ✓ | ✓ |
URL | String | The URL of the image. | ✓ | × | × | × | × | × |
AttachedMedia: information about an auxiliary media asset
Field | Type | Description | Used as a return field | Used for exact match | Used for fuzzy match | Used for a multi-value query | Used for a range query | Used as a sort field |
MediaId | String | The ID of the auxiliary media asset. | ✓ | ✓ | × | × | × | × |
AppIdString | String | The ID of the application. | ✓ | × | × | ✓ | × | × |
CateId | Long | The ID of the category to which the auxiliary media asset belongs. | × | ✓ | × | × | × | × |
Categories | Category[] | The list of category IDs. | ✓ | × | × | × | × | × |
StorageLocation | String | The region where the auxiliary media asset is stored. | ✓ | ✓ | × | ✓ | × | × |
FileName | String | The file name of the auxiliary media asset. | ✓ | × | ✓ | × | × | × |
Title | String | The title of the auxiliary media asset. | ✓ | × | ✓ | × | × | × |
Tags | String | The tags of the auxiliary media asset. | ✓ | × | ✓ | ✓ | × | × |
Description | String | The description of the auxiliary media asset. | ✓ | × | ✓ | × | × | × |
Status | String | ✓ | × | × | ✓ | × | × | |
CreationTime | String | The time when the auxiliary media asset was created. | ✓ | × | × | × | ✓ | ✓ |
ModificationTime | String | The time when the auxiliary media asset was last updated. | ✓ | × | × | × | ✓ | ✓ |
URL | String | The URL of the auxiliary media asset. | ✓ | × | × | × | × | × |
BusinessType | String | The type of the business. | ✓ | ✓ | × | × | × | × |
Parameter description
PreprocessStatus: the preprocessing status of a media asset
Only preprocessed media assets can be used for live streaming in a production studio.
Value | Description | Remarks |
UnPreprocess | The media asset is not preprocessed. | The initial state. |
Preprocessing | The media asset is being preprocessed. | None. |
PreprocessSucceed | The preprocessing is complete. | None. |
PreprocessFailed | The preprocessing failed. | None. |
DownloadSwitch: whether offline download is enabled for a media asset
A media asset can be downloaded in offline mode only when offline download is enabled.
Value | Description | Remarks |
on | Offline download is enabled. | The initial state. The media asset can be downloaded in offline mode. |
off | Offline download is disabled. | The media asset cannot be downloaded in offline mode. |
MediaSource: the source of a media asset
Value | Description | Remarks |
general | The media asset is uploaded to ApsaraVideo VOD by using the console. | The simple upload mode. |
short_video | The media asset is uploaded to ApsaraVideo VOD by using the short video SDK. | For more information, see Overview. |
editing | The media asset is uploaded to ApsaraVideo VOD by creating a video production task. | For more information, see ProduceEditingProjectVideo. |
live | The media asset is uploaded to ApsaraVideo VOD as a live recording. | None. |
TranscodeMode: the transcoding mode of a media asset
After a media asset is uploaded to ApsaraVideo VOD, it can be played only after it is processed. Processing methods vary based on transcoding modes.
Value | Description | Remarks |
FastTranscode | Regular transcoding | The default mode. The media asset is immediately transcoded after it is uploaded to ApsaraVideo VOD. The media asset can be played only after it is transcoded. |
NoTranscode | Distributed without transcoding | Media assets in the following formats can be immediately played without transcoding after they are uploaded to ApsaraVideo VOD: MP4, FLV, M3U8, MP3, and WEBM. |
AsyncTranscode | Immediately distributed and transcoded once uploaded | After a media asset is uploaded to ApsaraVideo VOD, it can be immediately played and asynchronously transcoded. |
StorageClass: the storage class of a media asset
Value | Description | Remarks |
Standard | Standard storage class | All media resources including source files and transcoded streams are stored as Standard objects. Resources such as snapshots are not stored as Standard objects. |
IA | Infrequent access (IA) storage class | All media resources including source files and transcoded streams are stored as IA objects. Resources such as snapshots are not stored as IA objects. |
Archive | Archive storage class | All media resources including source files and transcoded streams are stored as Archive objects. Resources such as snapshots are not stored as Archive objects. |
ColdArchive | Cold Archive storage class | All media resources including source files and transcoded streams are stored as Cold Archive objects. Resources such as snapshots are not stored as Cold Archive objects. |
SourceIA | IA storage for source files | Only the source files are IA objects. Resources other than source files are stored as Standard objects. |
SourceArchive | Archive storage for source files | Only the source files are Archive objects. Resources other than source files are stored as Standard objects. |
SourceColdArchive | Cold Archive storage for source files | Only the source files are Cold Archive objects. Resources other than source files are stored as Standard objects. |
Changing | Storage class of media resources being changed | The storage class of media resources is being changed. |
SourceChanging | Storage class of source file being changed | The storage class of the source file is being changed. |