UploadMediaByURL - ApsaraVideo VOD: Central de Documentação do Alibaba Cloud

Obtém e faz o upload de arquivos de mídia de áudio e vídeo a partir de URLs de origem. Suporta uploads em lote.

Descrição da operação

Antes de chamar esta operação, certifique-se de compreender totalmente os métodos de cobrança e os preços do ApsaraVideo VOD. O upload de ativos de mídia para o ApsaraVideo VOD incorre em taxas de armazenamento. Para detalhes de cobrança, consulte Cobrança de armazenamento de ativos de mídia. Se você ativou a aceleração de transferência de armazenamento, o upload de ativos de mídia para o ApsaraVideo VOD também incorre em taxas de aceleração de upload. Para detalhes de cobrança, consulte Cobrança de aceleração de transferência de armazenamento.
Para os formatos de arquivo de mídia suportados por esta operação, consulte Formatos de mídia.
Esta operação é aplicável principalmente a cenários em que os arquivos não estão armazenados em servidores ou terminais locais e precisam ser enviados por upload por meio de URLs com acesso à rede pública.
Esta operação é uma operação de upload assíncrona. Não é em tempo real e não garante pontualidade. Geralmente, a migração e o upload são concluídos em horas ou até dias após o envio. Se você tiver altos requisitos de pontualidade, use o SDK de upload.
Se um callback estiver configurado, você receberá uma notificação de evento de Conclusão de upload de vídeo baseado em URL após a conclusão do upload. Você pode consultar o status do upload chamando a operação Obter informações de upload de URL.
Após o envio de uma tarefa de upload, uma tarefa executada de forma assíncrona é gerada na nuvem. As tarefas de upload de URL enviadas por todos os usuários na região de serviço correspondente são enfileiradas para execução. O tempo de conclusão é afetado pelo número de tarefas existentes. Após a conclusão do upload, você pode associar a tarefa com base na URL e no ID do vídeo retornados na notificação do evento (callback de mensagem).
Atualmente, esta operação é suportada apenas nas regiões China (Xangai), China (Pequim), China (Shenzhen), Cingapura e EUA (Vale do Silício).
Para a mesma URL de arquivo de mídia, cada tarefa de upload enviada gera um novo ativo de mídia no ApsaraVideo VOD (ou seja, um novo ID de mídia é gerado).
Se um único arquivo exceder 20 GB, isso resultará em falha no upload. Se você precisar fazer o upload de um único arquivo maior que 20 GB, use o SDK de upload. Para mais informações, consulte Visão geral do SDK de upload.

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

vod:UploadMediaByURL

create

*Todos os recursos.

*

Nenhuma

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
UploadURLs	string	Sim	As URLs dos arquivos de mídia de origem. A URL deve incluir uma extensão de nome de arquivo. Por exemplo, em `https://**.mp4`, mp4 é a extensão do nome do arquivo. Se a URL não contiver uma extensão de nome de arquivo, você poderá especificá-la passando `FileExtension` em `UploadMetadatas`. Se a URL contiver uma extensão de nome de arquivo e `FileExtension` também for passado, o `FileExtension` passado prevalece. Para extensões de nome de arquivo suportadas, consulte Visão geral do upload. Nota As URLs devem ser codificadas por URL. Separe várias URLs com vírgulas (,). Você pode especificar até 20 URLs. Para evitar falhas de upload causadas por caracteres especiais, codifique por URL** as URLs antes de concatená-las com vírgulas.	https://****.mp4
TemplateGroupId	string	Não	O ID do grupo de modelos de transcodificação. Você pode obter o ID usando um dos seguintes métodos: Faça logon no console do ApsaraVideo VOD e escolha Gerenciamento de configuração > Configuração de processamento de mídia > Grupos de modelos de transcodificação para visualizar o ID do grupo de modelos de transcodificação. Ao criar um grupo de modelos de transcodificação chamando a operação Criar um grupo de modelos de transcodificação, o ID do grupo de modelos de transcodificação é o valor do parâmetro de resposta TranscodeTemplateGroupId. Ao consultar grupos de modelos de transcodificação chamando a operação Consultar grupos de modelos de transcodificação, o ID é o valor do parâmetro de resposta TranscodeTemplateGroupId. Nota Se você não especificar o ID de um grupo de modelos de transcodificação, o grupo de modelos de transcodificação padrão será usado para a transcodificação. Se você especificar o ID de um grupo de modelos de transcodificação, o grupo de modelos especificado será usado para a transcodificação. Você também pode definir este parâmetro em `UploadMetadatas`. Se TemplateGroupId estiver definido tanto em `UploadMetadatas` quanto aqui, o TemplateGroupId definido em `UploadMetadatas` prevalece.	ca3a8f6e4957b65806709586****
StorageLocation	string	Não	O endereço de armazenamento do arquivo de mídia. Faça logon no console do ApsaraVideo VOD e escolha Gerenciamento de configuração > Configuração de gerenciamento de ativos de mídia > Gerenciamento de armazenamento para visualizar o endereço de armazenamento. Se você não especificar este parâmetro, o endereço de armazenamento padrão será usado.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
UploadMetadatas	string	Não	Os metadados dos arquivos de mídia a serem enviados por upload. O valor é uma string JSON. Os metadados entram em vigor apenas quando correspondem à URL em UploadURLs. Formato JSON: `[UploadMetadata, UploadMetadata,…]`. O valor deve ser convertido em uma string JSON. Para mais informações, consulte a tabela UploadMetadata abaixo.	[{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
UserData	string	Não	As configurações personalizadas. O valor é uma string JSON. Você pode definir configurações como callbacks de mensagem e aceleração de upload. Para mais informações, consulte UserData. Nota Para usar o recurso de callback de mensagem neste parâmetro, você deve configurar uma URL de callback HTTP e selecionar os tipos de evento de callback correspondentes no console. Caso contrário, as configurações de callback não entrarão em vigor. Para mais informações sobre como configurar callbacks HTTP no console, consulte Configurações de callback. Para usar o recurso de aceleração de upload, você deve enviar um ticket para solicitar a ativação. Para mais informações, consulte Instruções de upload. Para mais informações sobre como enviar um ticket, consulte Fale conosco.	{"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
AppId	string	Não	O ID do aplicativo. Valor padrão: app-1000000. Para mais informações, consulte Multiaplicativo.	app-****
WorkflowId	string	Não	O ID do fluxo de trabalho. Você pode fazer logon no console do ApsaraVideo VOD e escolher Gerenciamento de configuração > Configuração de processamento de mídia > Gerenciamento de fluxo de trabalho para visualizar o ID do fluxo de trabalho. Nota Se WorkflowId e TemplateGroupId forem passados, WorkflowId prevalece. Para instruções de uso, consulte Fluxos de trabalho.	e1e243b42548248197d6f74f9****
SessionId	string	Não	O identificador de deduplicação personalizado. Se este parâmetro for passado em uma solicitação e uma solicitação com o mesmo identificador for detectada nos últimos 10 minutos, um erro será retornado para a solicitação atual. Nota O identificador de deduplicação é personalizado. Pode ter até 50 caracteres e suporta letras maiúsculas e minúsculas, dígitos, hifens (-) e sublinhados (_). Se você não passar este parâmetro ou passar uma string vazia, a deduplicação não será realizada.	5c62d40299034bbaa4c195da330****
EnableFirstFrameCover	boolean	Não	Especifica se o primeiro quadro do vídeo deve ser usado como capa.
GenerateThumbnail	boolean	Não	Especifica se uma miniatura deve ser gerada para o vídeo.

UploadMetadata

Nome	Tipo	Obrigatório	Descrição
SourceURL	String	Sim	A URL do arquivo de mídia de origem a ser enviado por upload.
Title	String	Não	O título da mídia. O valor pode ter até 128 bytes de comprimento e deve ser codificado em UTF-8.
FileSize	String	Não	O tamanho do arquivo.
Description	String	Não	A descrição. O valor pode ter até 1.024 bytes de comprimento e deve ser codificado em UTF-8.
CoverURL	String	Não	A URL personalizada da capa do vídeo.
CateId	String	Não	O ID da categoria. Você pode fazer logon no console do ApsaraVideo VOD e escolher Gerenciamento de configuração > Configuração de gerenciamento de ativos de mídia > Gerenciamento de categorias para visualizar o ID da categoria.
Tags	String	Não	As tags. Uma única tag pode ter até 32 bytes de comprimento. Você pode especificar até 16 tags. Separe várias tags com vírgulas (,). Codifique o valor em UTF-8.
TemplateGroupId	String	Não	O ID do grupo de modelos de transcodificação. Este valor substitui o TemplateGroupId passado no nível externo.
WorkflowId	String	Não	O ID do fluxo de trabalho. Se WorkflowId e TemplateGroupId forem passados, WorkflowId prevalece. Para mais informações, consulte Fluxos de trabalho.
FileExtension	String	Não	A extensão do nome do arquivo de mídia. Para extensões de nome de arquivo suportadas, consulte Visão geral do upload.
ReferenceId	String	Não	O ID personalizado. O valor pode ter de 6 a 64 caracteres e suporta apenas letras minúsculas, letras maiúsculas, dígitos, hifens (-) e sublinhados (_). O ID deve ser exclusivo por usuário.

Nota

Os parâmetros em UploadMetadata (como Title, Description e Tags) não podem conter emojis.
Para garantir a reprodução normal, se você definir TemplateGroupId como "VOD_NO_TRANSCODE" para fazer o upload de arquivos de vídeo sem transcodificação, apenas arquivos nos seguintes formatos suportam reprodução direta sem transcodificação: MP4, FLV, MP3, M3U8 e WEBM. Arquivos em outros formatos são apenas armazenados (preste atenção à extensão do nome do arquivo de FileName). Se você usar o player do Alibaba Cloud, a versão deve ser 3.1.0 ou posterior.
Se você especificar um grupo de modelos que não transcodifica (TemplateGroupId definido como "VOD_NO_TRANSCODE"), apenas a notificação de evento de Conclusão de upload de vídeo será gerada após o upload do vídeo. A notificação de evento de Conclusão de transcodificação de definição única não é gerada.
Se um callback estiver configurado, após o upload do vídeo, você receberá a notificação de evento de Conclusão de upload de vídeo baseado em URL além das notificações de upload e transcodificação.
Ao enviar tarefas em lotes, cada SourceURL tem uma notificação independente.

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object	A resposta.
RequestId	string	O ID da solicitação.	25818875-5F78-4AF6-D7393642CA58****
UploadJobs	array<object>	A lista de tarefas de upload.
	object	Os detalhes da tarefa de upload.
SourceURL	string	A URL do arquivo de origem correspondente à tarefa de upload.	http://example****.mp4
JobId	string	O ID da tarefa de upload.	ad90a501b1b94fb72374ad005046****

Exemplos

Resposta de sucesso

JSON formato

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

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.