Query media assets in ApsaraVideo VOD by using advanced search methods such as fuzzy match and multi-value query - ApsaraVideo VOD

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.

Important

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	Return field
Field used for exact match	Queries the media assets for which the value of a specific field is exactly matched.	field = value	Exact match
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'	Fuzzy match
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')	Multi-value query
Field used for a range query	Queries the media assets for which the value of a specific field falls in a specified open or closed interval.	field = (value1,value2)	Range query
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	Sort field

Special characters

Character	Description	Syntax
and	Connects two filter conditions to query the media assets that match both the 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.

Important

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	The status of the video.	✓	×	×	✓	×	×
MediaSource	String	The source of the video.	✓	×	×	✓	×	×
PreprocessStatus	String	The preprocessing status of the video.	✓	×	×	✓	×	×
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	Indicates whether offline download is enabled.	✓	×	×	×	×	×
TranscodeMode	String	The transcoding mode of the audio.	✓	×	×	×	×	×
StorageClass	String	The storage class of the audio.	✓	×	×	✓	×	×

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	The status of the audio.	✓	×	×	✓	×	×
MediaSource	String	The source of the audio.	✓	×	×	✓	×	×
PreprocessStatus	String	The preprocessing status of the audio.	✓	×	×	✓	×	×
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	Indicates whether offline download is enabled.	✓	×	×	×	×	×
TranscodeMode	String	The transcoding mode of the audio.	✓	×	×	×	×	×
StorageClass	String	The storage class of the audio.	✓	×	×	✓	×	×

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	The status of the image.	✓	×	×	✓	×	×
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	The status of the auxiliary media asset.	✓	×	×	✓	×	×
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.	-
PreprocessSucceed	The preprocessing is complete.	-
PreprocessFailed	The preprocessing failed.	-

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.	If 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	The 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.