文档

UploadMediaByURL - URL批量拉取上传

更新时间:

基于源文件URL,拉取音视频媒体文件进行上传,支持批量上传。

接口说明

  • 请确保在使用该接口前,已充分了解视频点播产品的收费方式和价格。媒资文件上传到视频点播中会产生存储费用,计费详情,请参见媒资存储计费。如果您已开通了存储传输加速,则上传媒资文件到视频点播时还将涉及上传加速费用,计费详情请参见存储传输加速计费
  • 本接口主要适用于文件没有存储在本地服务器或终端,需要通过公网访问的 URL 地址上传的场景。
  • 本接口为异步上传接口,非实时,不保证时效性,一般提交后会在数小时、甚至数天内完成迁移上传。如果对时效性要求较高,建议使用上传 SDK 上传。
  • 如果配置了回调,则上传完成后会收到 URL 上传视频完成的事件通知,可以通过获取 URL 上传信息接口查询上传状态。
  • 上传任务提交成功后,会在云端生成异步执行的任务,相应服务地域下所有用户提交的 URL 上传任务进行排队执行,完成时间受已有任务数量影响;上传完成后可根据事件通知(消息回调)返回的 URL 和视频 ID 等信息进行关联。
  • 本接口目前仅支持华东 2(上海)新加坡地域。
  • 同一个媒体文件 URL,每次提交上传任务都会在点播中产生一个新的媒体资源(即产生新的媒体 ID)。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
vod:UploadMediaByURLWrite
  • 全部资源
    *

请求参数

名称类型必填描述示例值
UploadURLsstring

媒体源文件 URL。

  • URL 中需要包括扩展名, 比如https://****.mp4中 mp4 为扩展名。
    • 如果 URL 中不包含扩展名,可以在UploadMetadatas中传入FileExtension来指定。
    • 如果 URL 中有扩展名且同时传入FileExtension,以传入的FileExtension为准。
    • 指定支持的扩展名,请参见上传概述
  • URL 编码,多个地址之间以半角逗号(,)分隔,最多支持 20 个。
  • 避免存在特殊字符导致无法上传视频,需要 URL 编码后再做逗号拼接。
https://****.mp4
TemplateGroupIdstring

转码模板组 ID。可通过以下方式获取:

  • 登录点播控制台,选择配置管理 > 媒体处理配置 > 转码模板组查看转码模版组 ID。
  • 通过创建转码模板组接口创建转码模板组时,转码模板组 ID 为返回参数 TranscodeTemplateGroupId 的值。
  • 通过查询转码配置列表接口查询转码模板组时,为请求后返回参数 TranscodeTemplateGroupId 的值。
说明
  • 不设置转码模板组 ID,则按默认的转码模板组进行转码;设置了转码模板组 ID 时,会使用该指定的模板组进行转码。
  • 可以在UploadMetadatas中进行设置,如果在 UploadMetadatas 中设置了 TemplateGroupId,此处也设置了 TemplateGroupId,则以 UploadMetadatas 中设置的 TemplateGroupId 为准。
  • ca3a8f6e4957b65806709586****
    StorageLocationstring

    媒体文件存储地址。

    登录点播控制台,选择配置管理 > 媒资管理配置 > 存储管理查看存储地址。不指定时会使用默认存储地址。

    outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
    UploadMetadatasstring

    上传媒体文件的元数据信息,为 JSON 字符串。

    • 与 UploadURLs 里的 URL 匹配才能生效。
    • JSON 格式:[UploadMetadata, UploadMetadata,…],需转为 JSON 字符串 。
    • 更多信息,请参见下表 UploadMetadata
    [{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
    UserDatastring

    自定义设置。为 JSON 字符串,支持消息回调、上传加速等设置。更多信息,请参见 UserData

    说明
  • 此参数中消息回调的使用前提是需要在控制台配置 HTTP 回调地址和勾选对应的回调事件类型才能使用,否则回调设置不生效。控制台配置 HTTP 回调的操作,请参考回调设置
  • 如需使用上传加速功能,您需要填写宜搭信息申请开通,更多信息,请参见上传相关说明
  • {"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
    AppIdstring

    应用 ID。默认取值:app-1000000。 更多信息,请参见多应用

    app-****
    WorkflowIdstring

    工作流 ID。可登录点播控制台,选择配置管理 > 媒体处理配置 > 工作流管理查看工作流 ID。

    说明 如果同时传递了 WorkflowId 和 TemplateGroupId,以 WorkflowId 为准。使用说明,请参见工作流
    e1e243b42548248197d6f74f9****
    SessionIdstring

    自定义去重识别码,如果传递了该参数请求,当检测到在过去 10 分钟内曾有过相同识别码的请求,则会在本次请求时返回错误。 该去重识别码由您自定义设置,长度最长为 50 个字符,支持大小写英文字母、数字、短划线(-)和下划线(_),不传或者带空字符串表示不去重。

    5c62d40299034bbaa4c195da330****

    UploadMetadata

    名称类型是否必需描述
    SourceURLString需要上传的媒体源文件 URL。
    TitleString媒体标题。长度不超过 128 个字节。UTF-8 编码。
    FileSizeString文件大小。
    DescriptionString描述。长度不超过 1024 个字节。UTF-8 编码。
    CoverURLString自定义视频封面 URL 地址。
    CateIdString分类 ID。可通过登录点播控制台,选择配置管理 > 媒资管理配置 > 分类管理查看分类 ID。
    TagsString标签。单个标签不超过 32 字节,最多不超过 16 个标签。多个标签,请使用半角逗号(,)分隔。UTF8 编码。
    TemplateGroupIdString转码模板组 ID。会覆盖外层传入的 TemplateGroupId。
    WorkflowIdString工作流 ID。如果同时传入了 WorkflowId 和 TemplateGroupId,以 WorkflowId 为准。更多信息,请参见工作流
    FileExtensionString媒体文件扩展名,支持的扩展名,请参见上传概述
    说明
  • UploadMetadata 中的参数(如 Title、Description、Tags 等)不能包含表情符。
  • 为确保正常播放,当 TemplateGroupId 设置为“VOD_NO_TRANSCODE”不转码的方式上传视频文件后,目前仅以下格式的文件支持不转码直接播放:MP4、FLV、MP3、M3U8、WEBM,其他格式仅支持存储(关注 FileName 的扩展名)。若使用阿里云播放器,版本须为 3.1.0 或以上。
  • 指定不转码的模板组(TemplateGroupId 设置为“VOD_NO_TRANSCODE”),视频上传后仅有视频上传完成的事件通知,没有单个清晰度转码完成的事件通知。
  • 如果配置了回调,视频上传完成后,除了上传和转码通知,还有 URL 上传视频完成事件通知。
  • 批量提交时,每一个 SourceURL 有独立的通知。
  • 返回参数

    名称类型描述示例值
    object

    返回结果。

    RequestIdstring

    请求 ID。

    25818875-5F78-4AF6-D7393642CA58****
    UploadJobsobject []

    上传任务列表。

    SourceURLstring

    上传任务对应的源文件 URL。

    http://example****.mp4
    JobIdstring

    上传任务 ID。

    ad90a501b1b94fb72374ad005046****

    示例

    正常返回示例

    JSON格式

    {
      "RequestId": "25818875-5F78-4AF6-D7393642CA58****",
      "UploadJobs": [
        {
          "SourceURL": "http://example****.mp4",
          "JobId": "ad90a501b1b94fb72374ad005046****"
        }
      ]
    }

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2023-05-16OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:SessionId

    接口错误码

    下表列举了本接口特有的错误码。

    错误代码错误信息HTTP 状态码说明
    InvalidParameter.UploadURLsThe specified parameter UploadURLs is not valid.400参数 UploadURLs 无效。
    • 本页导读 (1)