Visão geral da API REST das operações dos Serviços de Mídia

logotipo dos Serviços de Mídia


Observação

Atualize os SDKs e a API REST de Serviços de Mídia do Azure para a v3 até 29 de fevereiro de 2024. A versão 3 da API REST de Serviços de Mídia do Azure e dos SDKs de cliente para .NET e Java oferece mais funcionalidades do que a versão 2. Estamos desativando a versão 2 da API REST de Serviços de Mídia do Azure e dos SDKs de cliente para .NET e Java.

Ação necessária: para minimizar a interrupção nas suas cargas de trabalho, examine o guia de migração para fazer a transição do código da API e dos SDKs da versão 2 para a API e o SDK da versão 3 antes de 29 de fevereiro de 2024. Após 29 de fevereiro de 2024, os Serviços de Mídia do Azure deixarão de aceitar o tráfego na API REST da versão 2, na API de gerenciamento de contas do ARM versão 2015-10-01 ou nos SDKs de cliente .NET da versão 2. Isso inclui todos os SDKS de cliente de código aberto de terceiros que possam chamar a API da versão 2. Saiba mais sobre a última versão, começando com a Visão geral dos Serviços de Mídia v3.

A API REST das Operações dos Serviços de Mídia é usada para criar trabalhos, ativos, canais ao vivo e outros recursos em uma conta de Serviços de Mídia do Azure. Para saber mais, consulte Referência da API REST das Operações dos Serviços de Mídia.

Os Serviços de Mídia do Microsoft Azure fornecem uma API REST que aceita o formato JSON ou XML atom+pub. API REST do Serviços de Mídia do Microsoft Azure requer cabeçalhos HTTP específicos que cada cliente deve enviar ao se conectar aos Serviços de Mídia do Microsoft Azure, bem como um conjunto de cabeçalhos opcionais. As seções a seguir descrevem os cabeçalhos e verbos HTTP que podem ser usados ao criar solicitações e receber respostas dos serviços de mídia.

A autenticação para a API REST de Serviços de Mídia do Azure é feita por meio da autenticação do Microsoft Azure Active Directory que está descrita no artigo Usar a autenticação do Azure AD para acessar a API de Serviços de Mídia do Azure com REST

Considerações

As seguintes considerações se aplicam ao usar REST.

  • Ao consultar entidades, um limite de 1.000 entidades podem ser retornadas ao mesmo tempo porque a REST v2 pública limita os resultados da consulta a 1.000 resultados. Você precisa usar Skip e Take (.NET)/ top (REST), conforme descrito neste exemplo de .NET e neste exemplo de API REST.

  • Ao usar o JSON e especificar para usar a palavra-chave __metadata na solicitação (por exemplo, para fazer referência a um objeto vinculado), é NECESSÁRIO definir o cabeçalho Accept para o formato JSON Detalhado (veja o exemplo a seguir). O Odata não entende a propriedade __metadata na solicitação, a menos que você a defina como detalhado.

    POST https://media.windows.net/API/Jobs HTTP/1.1
    Content-Type: application/json;odata=verbose
    Accept: application/json;odata=verbose
    DataServiceVersion: 3.0
    MaxDataServiceVersion: 3.0
    x-ms-version: 2.19
    Authorization: Bearer <ENCODED JWT TOKEN> 
    Host: media.windows.net
    
    {
        "Name" : "NewTestJob", 
        "InputMediaAssets" : 
            [{"__metadata" : {"uri" : "https://media.windows.net/api/Assets('nb%3Acid%3AUUID%3Aba5356eb-30ff-4dc6-9e5a-41e4223540e7')"}}]
    . . . 
    

Os cabeçalhos de solicitação HTTP padrão suportados pelos serviços de mídia

Para todas as chamadas feitas nos serviços de mídia, há um conjunto de cabeçalhos necessários que você deve incluir na solicitação e também um conjunto de cabeçalhos opcionais você talvez queira incluir. A tabela abaixo lista os cabeçalhos necessários:

parâmetro Tipo Valor
Autorização Portador Portador é o único mecanismo de autorização aceito. O valor também deve incluir o token de acesso fornecido pelo Microsoft Azure Active Directory.
x-ms-version Decimal 2.17 (ou versão mais recente)
DataServiceVersion Decimal 3.0
MaxDataServiceVersion Decimal 3.0

Observação

Como os Serviços de Mídia do Microsoft Azure usam o OData para expor seu APIs REST, os cabeçalhos DataServiceVersion e MaxDataServiceVersion devem ser incluídos em todas as solicitações. No entanto, se não forem, então os Serviços de Mídia do Microsoft Azure assumem que o valor DataServiceVersion em uso é 3.0.

Este é um conjunto de cabeçalhos opcional:

parâmetro Tipo Valor
Data Data do RFC 1123 Carimbo de hora da solicitação
Aceitar Tipo de conteúdo O conteúdo solicitado para a resposta, como o seguinte:

-application/json;odata=verbose

- application/atom+xml

As respostas podem ter tipos de conteúdo diferentes como uma busca de blob, em que uma resposta bem-sucedida contém o fluxo de blob como carga.

Codificação aceita Gzip, deflate Codificar GZIP e DEFLATE, quando aplicável. Observação: para grandes recursos, os Serviços de Mídia podem ignorar esse cabeçalho e retornar dados não compactados.
Idioma aceito "en", "es", e assim por diante. Especifica o idioma preferencial para a resposta.
Conjunto de caracteres aceito Tipo de conjunto de caracteres como "UTF-8" Padrão é UTF-8.
Método X-HTTP Método HTTP Permite que os clientes ou firewalls que não suportam métodos HTTP como PUT ou DELETE usem esses métodos, desviados via uma chamada GET.
Tipo de conteúdo Tipo de conteúdo Tipo de conteúdo do corpo da solicitação em solicitações PUT ou POST.
ID da solicitação de cliente String Um valor definido pelo chamador que identifica a solicitação em questão. Se especificado, esse valor será incluído na mensagem de resposta como uma maneira de mapear a solicitação.

Importante

Os valores devem ser limitados a 2096b (2K).

Cabeçalhos de resposta HTTP padrão suportados pelos serviços de mídia

Este é um conjunto de cabeçalhos que podem ser retornados para você, dependendo do recurso que você solicitou e da ação que você pretende executar.

parâmetro Tipo Valor
ID da solicitação String Um identificador exclusivo para a operação atual, serviço gerado.
ID da solicitação de cliente String Um identificador especificado pelo chamador na solicitação original, se presente.
Data Data do RFC 1123 A data/hora em que a solicitação foi processada.
Tipo de conteúdo Varia O tipo de conteúdo do corpo da resposta.
Codificação de conteúdo Varia Gzip ou deflate, conforme apropriado.

Verbos HTTP padrão suportados pelos serviços de mídia.

A seguir está uma lista completa de verbos HTTP que podem ser usados quando fazem solicitações HTTP:

Verbo Descrição
GET Retorna o valor atual de um objeto.
POST Cria um objeto com base nos dados fornecidos ou envia um comando.
PUT Substitui um objeto ou cria um objeto nomeado (quando aplicável).
Delete (excluir) Exclui um objeto.
MESCLAR Atualiza um objeto existente com alterações de propriedade nomeada.
HEAD Retorna metadados de um objeto para uma resposta GET.

Descobrir e procurar o modelo de entidade dos Serviços de Mídia do Azure

Para tornar as entidades de serviços de mídia mais detectáveis, a operação de $metadata pode ser usada. Ele permite que você recupere todos os tipos de entidade válidos, propriedades da entidade, associações, funções, ações e assim por diante. Adicionando a operação $metadata ao final do seu ponto de extremidade de API REST de Serviços de Mídia do Azure, você pode acessar esse serviço de descoberta.

/api/$metadata.

Você deve acrescentar "?api-version=2.x" ao final do URI se desejar exibir os metadados em um navegador, ou não incluir o cabeçalho x-ms-version na solicitação.

Autenticar com o REST de Serviços de Mídia do Microsoft Azure usando o Azure Active Directory

A autenticação da API REST é feita por meio do Azure Active Directory (AAD). Para obter detalhes sobre como obter os detalhes de autenticação necessários para sua conta de Serviços de Mídia do Microsoft Azure do Portal do Azure, consulte Acessar a API de Serviços de Mídia do Microsoft Azure com a autenticação do Microsoft Azure Active Directory.

Para obter detalhes sobre como gravar um código que se conecte à API REST usando a autenticação do Azure AD, consulte o artigo Usar a autenticação do Microsoft Azure Active Directory para acessar a API de Serviços de Mídia do Microsoft Azure com REST.

Próximas etapas

Para saber como usar a autenticação do Azure AD com a API REST de Serviços de Mídia do Microsoft Azure, consulte Usar a autenticação do Microsoft Azure Active Directory para acessar a API de Serviços de Mídia do Microsoft Azure com REST.

Roteiros de aprendizagem dos Serviços de Mídia

Serviços de Mídia v3 (mais recente)

Confira a versão mais recente dos Serviços de Mídia do Azure.

Serviços de Mídia v2 (herdado)

Fornecer comentários

Use o fórum User Voice para fazer comentários e sugestões sobre como melhorar os Serviços de Mídia do Azure. Você também pode ir diretamente para uma das seguintes categorias: