文档

SubmitSnapshotJob - 提交截图作业

更新时间:

提交截图作业。调用本接口之后媒体处理MPS会对输入文件进行截图和拼图。

接口说明

  • 输入单个文件大小最大支持 100 GB,超过可能导致执行失败。

  • 请确认文件已成功上传至 OSS 后再提交截图作业,否则会导致执行失败。您可通过配置 OSS 回调消息确认文件上传状态。

  • 截图作业分为同步和异步模式。

    • 同步模式仅支持单张截图,会在接口返回时生成图片。
    • 异步模式不保证时效性,在提交截图作业后,任务会添加到管道中排队,被调度执行。所以在接口返回时,不保证截图已经生成。执行完成后需要调用查询截图作业结果接口轮询执行结果,或通过为管道绑定 MNS 消息接收执行结果,具体请参见接收消息通知
    • 只要设置了 IntervalNum 中的任何一个参数,就表示使用异步模式。
  • 目前仅支持生成 JPG 格式图片。

  • 更多截图常见问题,请参见截图常见问题

QPS 限制

本接口的单用户 QPS 限制为 50 次/秒。超过限制,API 调用会被限流,这可能会影响您的业务,请合理调用。更多信息,请参见 QPS 限制

调试

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

授权信息

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

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

请求参数

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

作业输入。详细说明请参见 Input 详情

说明
  • 在媒体处理 API 中,Object 必须经过URL Encoding(基于 UTF-8 编码)后使用。
    • OSS 的地域需要与当前 MPS 所在地域保持一致。
    {"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
    SnapshotConfigstring

    截图配置。详细说明,请参见 SnapshotConfig 参数详情

    {"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
    UserDatastring

    用户自定义数据。支持中英文、数字、短划线(-),不能以特殊字符开头,最大长度 1024 个字节。

    testid-001
    PipelineIdstring

    管道 ID,详细说明,请参见基本概念

    • 可选值:可以通过 MPS 控制台 > 全局设置 > 管道查询和创建管道。
    • 如果需要异步通知,请为管道绑定 MNS 消息,具体请参见接收消息通知
    dd3dae411e704030b921e52698e5****

    返回参数

    名称类型描述示例值
    object

    返回参数。

    RequestIdstring

    请求 ID。

    19B6D8C5-A5DD-467A-B435-29D393C71E2D
    SnapshotJobobject

    截图作业。

    CreationTimestring

    任务创建时间。

    2021-05-19T03:11:48Z
    SnapshotConfigobject

    截图配置。

    Timestring

    截图开始时间。单位:毫秒。

    5
    TileOutobject

    拼图配置。

    Paddingstring

    图片间距。

    • 默认:0

    • 单位:px。

    0
    Colorstring

    背景颜色。

    • 默认:black
    • 可取值范围:颜色关键字random
    说明 其中颜色关键字支持三种格式,比如黑色,支持 Black,black,#000000。
    black
    CellSelStepstring

    选取单图片步长。

    3
    CellHeightstring

    单图片高度。默认截图输出分辨率高度。

    100
    CellWidthstring

    单图片宽度。默认截图输出分辨率宽度。

    100
    Marginstring

    外框宽度。

    • 默认:0

    • 单位:px。

    5
    Columnsstring

    图片拼合列数。默认:10

    10
    IsKeepCellPicstring

    是否保留单图片。可取值:

    • true:保留。

    • false:不保留。

    • 默认:true

    false
    Linesstring

    图片拼合行数。默认:10

    10
    Intervalstring

    截图间隔时间。

    • 若指定则表示序列截图,且值大于 0。
    • 单位:秒。
    • 默认值:10
    20
    FrameTypestring

    截图类型。默认值:normal。可取值:

    • normal:普通帧。
    • intra:I 帧(关键帧)。
    说明 如果请求参数中将 FrameType 参数设置为 I 帧(关键帧),将只截取关键帧。如果指定的时间节点为非关键帧,则就近选取关键帧。在同等截图规则下,关键帧截图比普通帧截图速度快。
    intra
    Widthstring

    截图输出图片宽度。

    8
    Heightstring

    截图输出图片高度。

    8
    OutputFileobject

    截图输出 OSS 配置。

    RoleArnstring

    指定角色的 ARN。格式:acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Objectstring

    截图输出文件(OSS Object)。

    test.png
    Locationstring

    截图输出 OSS Bucket 所在数据中心(OSS Location)。

    example-location
    Bucketstring

    截图输出文件所在 OSS Bucket。

    example
    Numstring

    截图数量。若指定则表示序列截图。

    10
    TileOutputFileobject

    拼图任务大图的输出 OSS 配置。

    RoleArnstring

    指定角色的 ARN。格式:acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Objectstring

    输出文件 (OSS Object)。

    example.png
    Locationstring

    输出 OSS Bucket 所在数据中心(OSS Location)。

    example-location
    Bucketstring

    输出文件所在 OSS Bucket。

    example
    TimeArrayarray

    指定时间点数组。

    TimePointListlong

    指定时间点数组。单位毫秒,浮点数,保留 2 位小数,可重复,可无序提交,由 MPS 排序。最多 100 个时间点。指定该参数时,Num、Time、Interval 均不指定。如指定则提示参数指定错误 InvalidParameter.Ambiguity。

    [10050, 50000, 110000, 1000500, 1100500]
    Statestring

    截图状态。取值:

    • Submitted:已提交。

    • Snapshoting:截图中。

    • Success:截图成功。

    • Fail:截图失败。

    Snapshoting
    Messagestring

    分析失败时错误信息。若成功则不返回此参数。

    The resource operated InputFile is bad
    MNSMessageResultobject

    MNS 通知用户作业完成的结果。

    MessageIdstring

    成功时消息 ID。若失败则不返回此参数。

    799454621135656C7F815F198A76****
    ErrorMessagestring

    失败时错误信息。若成功则不返回此参数。

    The resource operated InputFile is bad
    ErrorCodestring

    失败时错误码。若成功则不返回此参数。

    InvalidParameter
    Inputobject

    作业输入。

    RoleArnstring

    指定角色的 ARN。格式:acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Objectstring

    输入文件(OSS Object)。

    example.flv
    Locationstring

    输入 OSS Bucket 所在数据中心(OSS Location)。

    example-location'
    Bucketstring

    输入文件所在 OSS Bucket。

    example
    Countstring

    截取图片的数量。

    1
    TileCountstring

    拼图图片数量。

    5
    UserDatastring

    用户自定义数据。

    testid-001
    Codestring

    分析失败时错误码。若成功则不返回此参数。

    ResourceContentBad
    PipelineIdstring

    管道 ID。

    dd3dae411e704030b921e52698e5****
    Idstring

    截图作业 ID。

    f4e3b9ba9f3840c39d6e288056f0****

    示例

    正常返回示例

    JSON格式

    {
      "RequestId": "19B6D8C5-A5DD-467A-B435-29D393C71E2D",
      "SnapshotJob": {
        "CreationTime": "2021-05-19T03:11:48Z",
        "SnapshotConfig": {
          "Time": "5",
          "TileOut": {
            "Padding": "0",
            "Color": "black",
            "CellSelStep": "3",
            "CellHeight": "100",
            "CellWidth": "100",
            "Margin": "5",
            "Columns": "10",
            "IsKeepCellPic": "false",
            "Lines": "10"
          },
          "Interval": "20",
          "FrameType": "intra",
          "Width": "8",
          "Height": "8",
          "OutputFile": {
            "RoleArn": "acs:ram::1:role/testrole",
            "Object": "test.png",
            "Location": "example-location",
            "Bucket": "example"
          },
          "Num": "10",
          "TileOutputFile": {
            "RoleArn": "acs:ram::1:role/testrole",
            "Object": "example.png",
            "Location": "example-location",
            "Bucket": "example"
          },
          "TimeArray": {
            "TimePointList": [
              0
            ]
          }
        },
        "State": "Snapshoting",
        "Message": "The resource operated InputFile is bad",
        "MNSMessageResult": {
          "MessageId": "799454621135656C7F815F198A76****",
          "ErrorMessage": "The resource operated InputFile is bad",
          "ErrorCode": "InvalidParameter"
        },
        "Input": {
          "RoleArn": "acs:ram::1:role/testrole",
          "Object": "example.flv",
          "Location": "example-location'",
          "Bucket": "example"
        },
        "Count": "1",
        "TileCount": "5",
        "UserData": "testid-001",
        "Code": "ResourceContentBad",
        "PipelineId": "dd3dae411e704030b921e52698e5****",
        "Id": "f4e3b9ba9f3840c39d6e288056f0****"
      }
    }

    错误码

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

    变更历史

    变更时间变更内容概要操作
    2024-04-24OpenAPI 返回结构发生变更查看变更详情
    2024-04-10API 内部配置变更,不影响调用查看变更详情