All Products
Search
Document Center

ApsaraVideo VOD:Protocol for media asset search

Last Updated:Feb 07, 2023

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. The protocol is a real-time search protocol that integrates the retrieval, filtering, sorting, and pagination features. You can use the protocol to query information about media assets such as videos, audio, and images in ApsaraVideo VOD.

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: fields used as returned 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 fields used as sort fields. For more information about all media asset fields supported by ApsaraVideo VOD and the applicable syntax rules, see the Media asset information section of this topic.

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 the Special characters section of this topic.

The following table describes the syntax that is defined in the protocol for media asset search and provides search examples.

Category

Description

Syntax

Example

Fields used as returned fields

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

Returned field

Fields used for exact match

Queries information about the media assets that match the exact value of a specified field.

field = value

Exact match

Fields 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

Fields 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

Fields 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)

Range query

Fields used as sort fields

Specifies the fields that you want to use for sorting the search results and specify the sorting method. 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 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')

( )

The parentheses that are used to enclose a specified open or closed interval for a range query.

field = ('value1','value2')

( )

The parentheses that are used to enclose multiple filter conditions in the OR relationship.

(field1 = 'value1' or field2 = 'value2')

' '

The single quotation marks that are used to enclose field values of the STRING type.

field = 'value'

,

The comma that is used 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 supported items and × indicates items that are not supported.

Important
  • You can specify a maximum of three values for multi-value queries.

  • Each string for fuzzy queries can contain a maximum of 60 characters.

  • If you cannot obtain a precise hit from fuzzy queries by using the Title field together with another field, check your statement for format errors. Example of a correct statement: (Title = 'Test' and Description = 'Description').

Video: specifies information about a video

Field

Type

Description

Used as a returned 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 tag 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 is created.

×

×

×

ModificationTime

String

The time when the video is last updated.

×

×

×

CoverURL

String

The URL of the thumbnail image.

×

×

×

×

×

Snapshots

String[]

The list of automatic snapshots.

×

×

×

×

×

SpriteSnapshots

String[]

The list of image sprites.

×

×

×

×

×

DownloadSwitch

String

Specifies whether offline download is enabled.

×

×

×

×

×

TranscodeMode

String

The transcoding mode of the video.

×

×

×

×

×

Audio: specifies information about an audio file

Field

Type

Description

Used as a returned 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 tag 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 is created.

×

×

×

ModificationTime

String

The time when the audio is last updated.

×

×

×

CoverURL

String

The URL of the thumbnail image.

×

×

×

×

×

Snapshots

String[]

The list of automatic snapshots.

×

×

×

×

×

SpriteSnapshots

String[]

The list of image sprites.

×

×

×

×

×

DownloadSwitch

String

Specifies whether offline download is enabled.

×

×

×

×

×

TranscodeMode

String

The transcoding mode of the audio.

×

×

×

×

×

Image: specifies information about an image

Field

Type

Description

Used as a returned 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 tag of the image.

×

×

×

Description

String

The description of the image.

×

×

×

×

Status

String

The status of the image.

×

×

×

×

CreationTime

String

The time when the image is created.

×

×

×

ModificationTime

String

The time when the image is last updated.

×

×

×

URL

String

The URL of the image.

×

×

×

×

×

AttachedMedia: specifies information about an auxiliary media asset

Field

Type

Description

Used as a returned 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 tag 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 is created.

×

×

×

ModificationTime

String

The time when the auxiliary media asset is last updated.

×

×

×

URL

String

The URL of the auxiliary media asset.

×

×

×

×

×

BusinessType

String

The type of the business.

×

×

×

×

AttachedMedia: specifies information about an auxiliary media asset

PreprocessStatus: specifies 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: specifies 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: specifies 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: specifies the transcoding mode

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

The media asset is 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

After a media asset is uploaded, it is immediately distributed and transcoded.

After a media asset is uploaded to ApsaraVideo VOD, it can be immediately played and asynchronously transcoded.