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

Envia um trabalho de snapshot. Após a chamada desta operação, o ApsaraVideo Media Processing captura snapshots e gera sprites de imagem para o arquivo de entrada.

Descrição da operação

O tamanho máximo de um único arquivo de entrada é de 100 GB. Exceder esse limite pode causar a falha do trabalho.
Certifique-se de que o arquivo foi carregado com sucesso no OSS antes de enviar um trabalho de snapshot. Caso contrário, o trabalho pode falhar. Você pode configurar mensagens de callback do OSS para verificar o status de carregamento do arquivo.
Os trabalhos de snapshot suportam os modos síncrono e assíncrono.
- O modo síncrono suporta apenas um único snapshot. A imagem é gerada quando a resposta da API é retornada.
- O modo assíncrono não garante pontualidade. Após o envio de um trabalho de snapshot, a tarefa é adicionada a uma fila do MPS e agendada para execução. Portanto, o snapshot pode não ser gerado quando a resposta da API é retornada. Após a conclusão da execução, você deve chamar a operação consultar resultados do trabalho de snapshot para consultar os resultados da execução ou vincular uma mensagem MNS à fila do MPS para receber os resultados da execução. Para obter mais informações, consulte Receber notificações de mensagens.
- Se você especificar o parâmetro Interval ou Num, o modo assíncrono será usado.
Atualmente, apenas imagens JPG podem ser geradas.
Para obter mais perguntas frequentes sobre snapshots, consulte Perguntas frequentes sobre snapshots.

Limites de QPS

O limite de QPS para um único usuário chamar esta operação é de 50 solicitações por segundo. Se o limite for excedido, as chamadas de API serão limitadas, o que pode afetar seus negócios. Faça as chamadas de API adequadamente. Para obter mais informações, consulte Limites 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

*Todos os recursos.

*

Nenhuma

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
Input	string	Sim	A entrada do trabalho. Para obter mais informações, consulte Detalhes da entrada. Nota Nas operações da API do ApsaraVideo Media Processing, o parâmetro Object deve ser codificado em URL com base em UTF-8 antes do uso. A região do bucket do OSS deve ser a mesma região do MPS.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Sim	A configuração do snapshot. Para obter mais informações, consulte Detalhes do parâmetro SnapshotConfig.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	Não	Os dados personalizados do usuário. Suporta caracteres chineses e ingleses, dígitos e hifens (-). Não pode começar com um caractere especial e pode ter até 1.024 bytes de comprimento.	testid-001
PipelineId	string	Não	O ID da fila do MPS. Para obter mais informações, consulte Termos. Valores válidos: Você pode consultar e criar filas do MPS escolhendo Configurações globais > Pipelines no console do MPS. Se você precisar de notificações assíncronas, anexe uma mensagem MNS à fila do MPS. Para obter mais informações, consulte Aceitar notificações de mensagens.	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 trabalho de snapshot.
CreationTime	string	A hora em que o trabalho foi criado. A hora é exibida em UTC e segue o padrão ISO 8601 no formato AAAA-MM-DDTHH:mm:ssZ.	2021-05-19T03:11:48Z
SnapshotConfig	object	A configuração do snapshot.
Time	string	A hora de início do snapshot. Unidade: milissegundos.	5
TileOut	object	A configuração do sprite de imagem.
Padding	string	O espaçamento entre as imagens. Valor padrão: 0. Unidade: pixels.	0
Color	string	A cor de fundo. Valor padrão: black. Valores válidos: color keyword e random. Nota Uma palavra-chave de cor suporta três formatos. Por exemplo, preto pode ser representado como Black, black ou #000000.	black
CellSelStep	string	O tamanho do passo para selecionar imagens individuais.	3
CellHeight	string	A altura de uma imagem individual. Valor padrão: a altura da resolução de saída do snapshot.	100
CellWidth	string	A largura de uma imagem individual. Valor padrão: a largura da resolução de saída do snapshot.	100
Margin	string	A largura da moldura externa. Valor padrão: 0. Unidade: pixels.	5
Columns	string	O número de colunas no sprite de imagem. Valor padrão: 10.	10
IsKeepCellPic	string	Especifica se deve reter imagens individuais. Valores válidos: true: Reter imagens individuais. false: Não reter imagens individuais. Valor padrão: true.	false
Lines	string	O número de linhas no sprite de imagem. Valor padrão: 10.	10
Interval	string	O intervalo de tempo entre os snapshots. Se este parâmetro for especificado, snapshots sequenciais serão capturados e o valor deve ser maior que 0. Unidade: segundos. Valor padrão: 10.	20
FrameType	string	O tipo de snapshot. Valor padrão: normal. Valores válidos: normal: quadro normal. intra: I-frame (keyframe). Nota Se as configurações do parâmetro de solicitação FrameType estiverem definidas como I-frame (keyframe), apenas os keyframes serão capturados. Se o ponto de tempo especificado não for um keyframe, o keyframe mais próximo será capturado. Sob as mesmas regras de snapshot, a captura de keyframes é mais rápida do que a captura de quadros normais.	intra
Width	string	A largura da imagem de snapshot de saída.	8
Height	string	A altura da imagem de snapshot de saída.	8
OutputFile	object	A configuração do OSS para a saída do snapshot.
RoleArn	string	O ARN da função especificada. Formato: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	O arquivo de saída (objeto do OSS).	test.png
Location	string	O data center onde o bucket do OSS de saída está localizado (localização do OSS).	example-location
Bucket	string	O bucket do OSS onde o arquivo de saída é armazenado.	example
Num	string	O número de snapshots. Se este parâmetro for especificado, snapshots sequenciais serão capturados.	10
TileOutputFile	object	A configuração do OSS para o sprite de imagem de saída.
RoleArn	string	O ARN da função especificada. Formato: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	O arquivo de saída (objeto do OSS).	example.png
Location	string	O data center onde o bucket do OSS de saída está localizado (localização do OSS).	example-location
Bucket	string	O bucket do OSS onde o arquivo de saída é armazenado.	example
TimeArray	object
TimePointList	array	A matriz de pontos de tempo especificados.
	integer	A matriz de pontos de tempo especificados. Unidade: milissegundos. Os valores são números de ponto flutuante com duas casas decimais. Os valores podem ser duplicados e enviados em qualquer ordem, e são classificados pelo MPS. Um máximo de 100 pontos de tempo pode ser especificado. Quando este parâmetro é especificado, os parâmetros Num, Time e Interval não podem ser especificados. Caso contrário, o erro InvalidParameter.Ambiguity é retornado.	[10050, 50000, 110000, 1000500, 1100500]
State	string	O status do snapshot. Valores válidos: Submitted: O trabalho foi enviado. Snapshoting: O snapshot está sendo capturado. Success: O snapshot foi capturado com sucesso. Fail: Falha ao capturar o snapshot.	Snapshoting
Message	string	A mensagem de erro retornada quando o trabalho falha. Este parâmetro não é retornado se o trabalho for bem-sucedido.	The resource operated InputFile is bad
MNSMessageResult	object	O resultado da notificação MNS enviada ao usuário após a conclusão do trabalho.
MessageId	string	O ID da mensagem retornado quando a notificação é bem-sucedida. Este parâmetro não é retornado se a notificação falhar.	799454621135656C7F815F198A76****
ErrorMessage	string	A mensagem de erro retornada quando a notificação falha. Este parâmetro não é retornado se a notificação for bem-sucedida.	The resource operated InputFile is bad
ErrorCode	string	O código de erro retornado quando a notificação falha. Este parâmetro não é retornado se a notificação for bem-sucedida.	InvalidParameter
Input	object	A entrada do trabalho.
RoleArn	string	O ARN da função especificada. Formato: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	O arquivo de entrada (objeto do OSS).	example.flv
Location	string	O data center onde o bucket do OSS de entrada está localizado (localização do OSS).	example-location'
Bucket	string	O bucket do OSS onde o arquivo de entrada é armazenado.	example
Count	string	O número de imagens capturadas.	1
TileCount	string	O número de imagens no sprite de imagem.	5
UserData	string	Os dados personalizados do usuário.	testid-001
Code	string	O código de erro retornado quando o trabalho falha. Este parâmetro não é retornado se o trabalho for bem-sucedido.	ResourceContentBad
PipelineId	string	O ID da fila do MPS.	dd3dae411e704030b921e52698e5****
Id	string	O ID do trabalho 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.