搜索媒体信息

最近更新时间:2019-08-01 19:09:21

1. 接口描述

接口请求域名: vod.tencentcloudapi.com 。

搜索媒体信息,支持各种条件筛选,以及对返回结果进行排序、过滤等功能,具体包括:

  • 根据媒体文件名或描述信息进行文本模糊搜索。
  • 根据媒体分类、标签进行检索。
    • 指定分类集合 ClassIds(见输入参数),返回满足集合中任意分类的媒体。例如:假设媒体分类有电影、电视剧、综艺,其中电影又有子分类历史片、动作片、言情片。如果 ClassIds 指定了电影、电视剧,那么电影和电视剧下的所有子分类 都会返回;而如果 ClassIds 指定的是历史片、动作片,那么只有这 2 个子分类下的媒体才会返回。
    • 指定标签集合 Tags(见输入参数),返回满足集合中任意标签的媒体。例如:假设媒体标签有二次元、宫斗、鬼畜,如果 Tags 指定了二次元、鬼畜 2 个标签,那么只要符合这 2 个标签中任意一个的媒体都会被检索出来。
  • 允许指定筛选某一来源 Source(见输入参数)的媒体。
  • 允许根据直播推流码、Vid(见输入参数)筛选直播录制的媒体。
  • 允许根据媒体的创建范围筛选媒体。
  • 允许对上述条件进行任意组合,检索同时满足以上条件的媒体。例如可以筛选从 2018 年 12 月 1 日到 2018 年 12 月 8 日创建的电影、电视剧分类下带有宫斗、鬼畜标签的媒体。
  • 允许对结果进行排序,允许通过 Offset 和 Limit 实现只返回部分结果。

接口搜索限制:

  • 搜索结果超过 5000条,不再支持分页查询超过 5000 部分的数据。

默认接口请求频率限制:100次/秒。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:SearchMedia
Version String 公共参数,本接口取值:2018-07-17
Region String 公共参数,本接口不需要传递此参数。
Text String 搜索文本,模糊匹配媒体文件名称或描述信息,匹配项越多,匹配度越高,排序越优先。长度限制:64 个字符。
Tags.N Array of String 标签集合,匹配集合中任意元素。
  • 单个标签长度限制:8 个字符。
  • 数组长度限制:10。
  • ClassIds.N Array of Integer 分类 ID 集合,匹配集合指定 ID 的分类及其所有子类。数组长度限制:10。
    StartTime String 创建时间的开始时间。
  • 大于等于开始时间。
  • 格式按照 ISO 8601 标准表示,详见 ISO 日期格式说明
  • EndTime String 创建时间的结束时间。
  • 小于结束时间。
  • 格式按照 ISO 8601 标准表示,详见 ISO 日期格式说明
  • SourceType String 媒体文件来源,来源取值参见 SourceType
    StreamId String 推流直播码
    Vid String 直播录制文件的唯一标识。
    Sort SortBy 排序方式。
  • Sort.Field 可选值:CreateTime
  • 指定 Text 搜索时,将根据匹配度排序,该字段无效
  • Offset Integer 偏移量。
  • 默认值:0。
  • 取值范围:Offset + Limit 不超过 5000。
  • Limit Integer 返回记录条数,默认值:10。
    SubAppId Integer 点播子应用 ID。如果要访问子应用中的资源,则将该字段填写为子应用 ID;否则无需填写该字段。

    3. 输出参数

    参数名称 类型 描述
    TotalCount Integer 符合搜索条件的记录总数
  • 最大值:5000,即,当命中记录数超过 5000,该字段将返回 5000,而非实际命中总数。
  • MediaInfoSet Array of MediaInfo 媒体文件信息列表,只包含基础信息(BasicInfo)
    注意:此字段可能返回 null,表示取不到有效值。
    RequestId String 唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

    4. 示例

    示例1 搜索媒体信息

    输入示例

    https://vod.tencentcloudapi.com/?Action=SearchMedia
    &Text=测试
    &ClassIds.0=1
    &ClassIds.1=2
    &StartTime=2018-09-20T10:00:00Z
    &EndTime=2018-10-02T10:00:00Z
    &Sort.Field=CreatTime
    &Sort.Order=Desc
    &<公共请求参数>

    输出示例

    {
      "Response": {
        "MediaInfoSet": [
          {
            "FileId": "123",
            "BasicInfo": {
              "ClassId": 1,
              "ClassName": "测试",
              "ClassPath": "测试",
              "CoverUrl": "http://xx.vod2.myqcloud.com/xxxxxxxx/shotup/f0.100_0.jpg",
              "CreateTime": "2018-10-01T10:00:00Z",
              "Description": "",
              "ExpireTime": "2018-12-01T13:00:00Z",
              "Name": "test file",
              "MediaUrl": "http://xx.vod2.myqcloud.com/xx/xx/f0.mp4",
              "Type": "mp4",
              "TagSet": [],
              "StorageRegion": "ap-chongqing",
              "SourceInfo": {
                "SourceType": "Record",
                "SourceContext": "xxxxxxxx"
              },
              "Vid": "200025104_21313e19584d4b2a82af7c826581536c",
              "UpdateTime": "2018-10-01T13:10:03Z"
            }
          },
          {
            "FileId": "256",
            "BasicInfo": {
              "ClassId": 1,
              "ClassName": "测试",
              "ClassPath": "测试 - 体育",
              "CoverUrl": "http://xx.vod2.myqcloud.com/xxxxxxxx/shotup/f0.100_0.jpg",
              "CreateTime": "2018-09-21T14:00:03Z",
              "Description": "",
              "ExpireTime": "2018-11-21T14:00:03",
              "Name": "test file2",
              "MediaUrl": "http://xx.vod2.myqcloud.com/xx/xx/f0.mp4",
              "Type": "mp4",
              "TagSet": [],
              "StorageRegion": "ap-chongqing",
              "SourceInfo": {
                "SourceType": "Record",
                "SourceContext": "xxxxxxxxx"
              },
              "Vid": "1251883823_e247f6b09c5c4f168052355ce1e9c343",
              "UpdateTime": "2018-09-22T16:12:16Z"
            }
          }
        ],
        "RequestId": "requestId",
        "TotalCount": 2
      }
    }

    5. 开发者资源

    API Explorer

    该工具提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力,能显著降低使用云 API 的难度,推荐使用。

    SDK

    云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

    命令行工具

    6. 错误码

    以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

    错误码 描述
    InternalError 内部错误。
    InternalError.GetMediaListError 内部错误:获取媒体列表错误。
    InvalidParameterValue.ClassIds 参数值错误:ClassIds 无效。
    InvalidParameterValue.EndTime 参数值错误:EndTime 无效。
    InvalidParameterValue.Offset 参数值错误:Offset 无效。
    InvalidParameterValue.Sort 参数值错误:Sort 无效。
    InvalidParameterValue.SourceType 参数值错误:SourceType 无效。
    InvalidParameterValue.StartTime 参数值错误:StartTime 无效。
    InvalidParameterValue.SubAppId 参数值错误:子应用 ID。
    InvalidParameterValue.Tags 参数值错误:Tags 无效。
    InvalidParameterValue.Text 参数值错误:搜索文本。
    LimitExceeded 超过配额限制。
    UnauthorizedOperation 未授权操作。