SubmitSnapshotJob - ApsaraVideo Media Processing: Central de Documentação do Alibaba Cloud

Envia um job de snapshot. O Media Processing Service (MPS) capturará screenshots e gerará uma imagem sprite a partir do arquivo de entrada.

Descrição da operação

O tamanho máximo para um único arquivo de entrada é 100 GB. Exceder esse limite pode causar falha no job.
Antes de enviar um job de snapshot, certifique-se de que o arquivo foi carregado com sucesso no OSS. Caso contrário, o job pode falhar. Você pode configurar callbacks do OSS para confirmar o status do upload do arquivo.
Jobs de snapshot suportam os modos síncrono e assíncrono.
- O modo síncrono suporta apenas um único snapshot e gera a imagem quando a chamada de API retorna.
- O modo assíncrono não garante processamento imediato. Após o envio de um job de snapshot, ele entra em um pipeline, onde é enfileirado e agendado para execução. Portanto, não é garantido que o snapshot seja gerado quando a chamada de API retorna. Após a conclusão do job, você pode consultar os resultados chamando a API Consultar resultados do job de snapshot ou receber notificações de mensagem vinculando o MNS ao pipeline. Para mais informações, consulte Receber notificações de mensagem.
- Especificar o parâmetro Interval ou Num aciona o modo assíncrono.
Atualmente, apenas imagens no formato JPG são suportadas.
Para mais informações sobre problemas comuns de snapshot, consulte FAQ de Snapshot.

Limite de QPS

O limite de QPS para esta API é de 50 solicitações por segundo por usuário. Chamadas de API que excederem esse limite estão sujeitas a throttling, o que pode impactar seu negócio. Chame esta API a uma taxa razoável. Para mais informações, consulte Limite de QPS.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

mts:SubmitSnapshotJob

create

*All Resource

*

Nenhuma

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
Input	string	Sim	A entrada do job. Para mais informações, consulte Input. Nota Nas APIs do ApsaraVideo for Media Processing (MPS), você deve codificar em URL o valor de `Object` em UTF-8. A região do OSS deve ser a mesma que a região do MPS.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Sim	As configurações de snapshot. Para mais informações, consulte SnapshotConfig.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	Não	Os dados personalizados. O valor pode conter letras, dígitos e hifens (-), mas não pode começar com um caractere especial. O valor pode ter até 1.024 bytes de comprimento.	testid-001
PipelineId	string	Não	O ID da fila do MPS. Para mais informações, consulte Conceitos básicos. Você pode visualizar ou criar filas do MPS no console do MPS escolhendo Configurações Globais > Pipelines. Para receber notificações assíncronas, você deve vincular uma fila do Message Service (MNS) à fila do MPS. Para mais informações, consulte Receber notificações de mensagem.	dd3dae411e704030b921e52698e5****

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object	Os parâmetros de resposta.
RequestId	string	O ID da solicitação.	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	O job de snapshot.
CreationTime	string	A hora em que o job foi criado.	2021-05-19T03:11:48Z
SnapshotConfig	object	A configuração de snapshot.
Time	string	The snapshot start time. Unit: milliseconds.	5
TileOut	object	The tiling configuration.
Padding	string	The padding between images. Default value: 0. Unit: pixels.	0
Color	string	The background color. Default value: black. Valid values: color keyword or random. Nota Color keywords can be specified in three formats. For example, to specify black, you can use `Black`, `black`, or `#000000`.	black
CellSelStep	string	The step for selecting individual images to include in the tiled output.	3
CellHeight	string	The height of an individual image in the tiled output. Defaults to the height of the output snapshot.	100
CellWidth	string	The width of an individual image in the tiled output. Defaults to the width of the output snapshot.	100
Margin	string	The width of the outer margin for the tiled image. Default value: 0. Unit: pixels.	5
Columns	string	The number of columns in the tiled image. Default value: 10.	10
IsKeepCellPic	string	Specifies whether to keep the individual snapshots. Valid values: true: Keeps the individual snapshots. false: Deletes the individual snapshots. Default value: true.	false
Lines	string	The number of rows in the tiled image. Default value: 10.	10
Interval	string	The interval for capturing a sequence of snapshots. The value must be greater than 0. Unit: seconds. Default value: 10.	20
FrameType	string	The type of frames to capture. Default value: normal. Valid values: normal: normal frames. intra: I-frames (keyframes). Nota If this parameter is set to `intra`, only keyframes are captured. If a specified time point is not a keyframe, the system uses the nearest keyframe. Capturing keyframes is typically faster than capturing normal frames.	intra
Width	string	The width of the output snapshot.	8
Height	string	The height of the output snapshot.	8
OutputFile	object	The OSS configuration for the output snapshot.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the output OSS object.	test.png
Location	string	The data center of the output OSS bucket.	example-location
Bucket	string	The OSS bucket for the output file.	example
Num	string	The number of snapshots to capture in a sequence.	10
TileOutputFile	object	The OSS configuration for the output tiled image.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the output OSS object.	example.png
Location	string	The data center of the output OSS bucket.	example-location
Bucket	string	The OSS bucket for the output file.	example
TimeArray	object
TimePointList	array	An array of time points.
	integer	An array of up to 100 time points, in milliseconds, at which to capture snapshots. Values can be floating-point numbers with up to two decimal places. You can submit time points in any order and include duplicates; MPS automatically sorts them. If you specify this parameter, do not use the `Num`, `Time`, or `Interval` parameters. Otherwise, the API returns an `InvalidParameter.Ambiguity` error.	[10050, 50000, 110000, 1000500, 1100500]
State	string	O estado do job de snapshot. Valores válidos: Submitted: O job foi enviado. Snapshotting: O job de snapshot está em andamento. Success: O job foi bem-sucedido. Fail: O job falhou.	Snapshoting
Message	string	A mensagem de erro. Este parâmetro é retornado apenas se o job falhar.	The resource operated InputFile is bad
MNSMessageResult	object	O resultado da notificação MNS enviada ao usuário após a conclusão do job.
MessageId	string	The ID of the MNS message. This parameter is returned only on successful notification.	799454621135656C7F815F198A76****
ErrorMessage	string	The error message, returned only if the MNS notification fails.	The resource operated InputFile is bad
ErrorCode	string	The error code, returned only if the MNS notification fails.	InvalidParameter
Input	object	A entrada do job.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the input OSS object.	example.flv
Location	string	The data center of the input OSS bucket.	example-location'
Bucket	string	The OSS bucket that contains the input file.	example
Count	string	O número total de snapshots capturados.	1
TileCount	string	O número de imagens em mosaico.	5
UserData	string	Os dados definidos pelo usuário.	testid-001
Code	string	O código de erro. Este parâmetro é retornado apenas quando o status do job é Fail.	ResourceContentBad
PipelineId	string	O ID do pipeline.	dd3dae411e704030b921e52698e5****
Id	string	O ID do job de snapshot.	f4e3b9ba9f3840c39d6e288056f0****

Exemplos

Resposta de sucesso

JSON formato

{
  "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****"
  }
}

Códigos de erro

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.