Compartilhar via

Desenvolver com as APIs dos Serviços de Mídia v3

  • Artigo

Logotipo dos Serviços de Mídia v3

Aviso

Os Serviços de Mídia do Azure serão desativados em 30 de junho de 2024. Para obter mais informações, consulte o Guia de Desativação do AMS.

Como desenvolvedor, você pode usar bibliotecas de cliente para (.NET, Python, Node.js, Java e Go) que permitem interagir com a API REST para criar, gerenciar e manter fluxos de trabalho de mídia personalizados com facilidade. A API dos Serviços de Mídia v3 se baseia na especificação do OpenAPI (anteriormente conhecida como um Swagger).

Este artigo discute as regras que se aplicam a entidades e APIs ao desenvolver com os Serviços de Mídia v3.

Aviso

Não é recomendável tentar encapsular a API REST para Serviços de Mídia diretamente em seu próprio código de biblioteca, pois fazer isso corretamente para fins de produção exigiria que você implemente a lógica de repetição completa do Gerenciamento de Recursos do Azure e entenda como gerenciar operações de execução prolongada em APIs de Gerenciamento de Recursos do Azure. Isso é tratado pelos SDKs do cliente para várias linguagens (.NET, Java, TypeScript, Python etc.) para você automaticamente e reduz as chances de você ter problemas com a lógica de repetição ou chamadas de API com falha. Todos os SDKs de cliente tratam isso para você.

Acessar a API dos Serviços de Mídia do Azure

Para estar autorizado a acessar os recursos e a API dos Serviços de Mídia, primeiro você deve ser autenticado. Os Serviços de Mídia dão suporte à autenticação baseada no Azure AD (Azure Active Directory). Duas opções de autenticação comuns são:

  • Autenticação de entidade de serviço: Usado para autenticar um serviço (por exemplo: aplicativos Web, aplicativos de funções, aplicativos lógicos, API e microservices). Os aplicativos que geralmente usam esse método de autenticação são aplicativos que executam serviços daemon, serviços de camada intermediária ou trabalhos agendados. Por exemplo, para aplicativos Web, sempre deve haver uma camada intermediária que se conecte aos serviços de mídia com uma entidade de serviço.
  • Autenticação de usuário: Usada para autenticar uma pessoa que está usando o aplicativo para interagir com os recursos dos Serviços de Mídia. O aplicativo interativo deve primeiro solicitar ao usuário as credenciais do usuário. Um exemplo é um aplicativo de console de gerenciamento usado por usuários autorizados para monitorar trabalhos de codificação ou uma transmissão ao vivo.

A API dos serviços de mídia requer que o usuário ou aplicativo que faz as solicitações da API REST tenha acesso ao recurso de conta dos serviços de mídia e use uma função de Colaborador ou de Proprietário. A API pode ser acessada com a função de Leitor, mas somente as operações Get e List estarão disponíveis. Para obter mais informações, veja RBAC (controle de acesso baseado em função) do Azure para contas de Serviços de Mídia.

Em vez de criar uma entidade de serviço, considere o uso de identidades gerenciadas dos recursos do Azure para acessar a API dos serviços de mídia por meio de Azure Resource Manager. Para saber mais sobre as identidades gerenciadas para os recursos do Azure, confira o artigo O que são as identidades gerenciadas para recursos do Azure.

Entidade de serviço do Azure AD

O aplicativo e a entidade de serviço do Azure AD devem estar no mesmo locatário. Depois de criar o aplicativo, conceda o acesso da função de Colaborado ou Proprietário ao aplicativo à conta dos Serviços de Mídia.

Se você não tiver certeza se tem permissões para criar um aplicativo do Azure AD, consulte Permissões necessárias.

Na figura anterior, os números representam o fluxo das solicitações em ordem cronológica:

Autenticação de aplicativo de camada intermediária com o AAD de uma API da Web

  1. Um aplicativo de camada intermediária solicita um token de acesso do Microsoft Azure AD que tem os seguintes parâmetros:

    • Ponto de extremidade do locatário do Azure AD.
    • URI de recurso dos Serviços de Mídia.
    • URI de recurso dos Serviços de Mídia REST.
    • Valores do aplicativo do Microsoft Azure AD: a ID do cliente e o segredo do cliente.

    Para obter todos os valores necessários, consulte Acessar a API dos Serviços de Mídia do Microsoft Azure.

  2. O token de acesso do Azure AD é enviado à camada intermediária.

  3. A camada intermediária envia a solicitação à API REST da Mídia do Azure com o token do Azure AD.

  4. A camada intermediária obtém novamente os dados dos Serviços de Mídia.

Exemplos

Consulte os seguintes exemplos que mostram como se conectar à entidade de serviço do Microsoft Azure AD:

Convenções de nomenclatura

Nomes de recursos do Serviços de Mídia do Azure v3 (por exemplo, ativos, trabalhos, transformações) estão sujeitos a restrições de nomenclatura do Azure Resource Manager. De acordo com o Azure Resource Manager, os nomes dos recursos são sempre exclusivos. Desse modo, é possível usar qualquer cadeia de caracteres de identificador exclusivo (por exemplo, GUIDs) para os nomes dos recursos.

Os nomes de recursos dos Serviços de Mídia não podem incluir: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', o caractere de aspa única ou quaisquer caracteres de controle. Todos os outros caracteres são permitidos. O comprimento máximo de um nome de recurso é de 260 caracteres.

Para obter mais informações sobre a nomenclatura do Azure Resource Manager, consulte: Requisitos de nomenclatura e Convenções de nomenclatura.

Nomes de Arquivos/blobs em um ativo

Os nomes de Arquivos/blobs em um ativo devem seguir os requisitos de nome de blob e os requisitos de nome de NTFS. O motivo para esses requisitos é que os arquivos podem ser copiados do armazenamento de blobs para um disco NTFS local para processamento.

Operações de execução longa

As operações marcadas com x-ms-long-running-operation nos arquivos de Serviços de Mídia do Microsoft Azure Swagger são operações de execução prolongada.

Para obter detalhes sobre como rastrear operações assíncronas do Azure, consulte Operações assíncronas.

Os serviços de mídia têm as seguintes operações de execução longa:

Após o envio bem-sucedido de uma operação longa, você receberá um '201 criado' e deverá sondar a conclusão da operação usando a ID da operação retornada.

O artigo Acompanhar as operações assíncronas do Azure explica detalhadamente como acompanhar o status das operações assíncronas do Azure por meio dos valores retornados na resposta.

Somente uma operação de execução longa tem suporte para um determinado evento ao vivo ou qualquer uma de suas saídas dinâmicas associadas. Depois de iniciada, uma operação de execução prolongada deve ser concluída antes de iniciar uma operação de execução prolongada subsequente no mesmo LiveEvent ou em qualquer saída ao vivo associada. Para eventos ao vivo com várias saídas ao vivo, você deve aguardar a conclusão de uma operação de execução prolongada em uma saída dinâmica antes de disparar uma operação de execução prolongada em outra saída ao vivo.

SDKs

Observação

Os SDKs dos Serviços de Mídia do Azure v3 não têm garantia de serem thread-safe. Ao desenvolver um aplicativo com multi-thread, você deverá adicionar sua própria lógica de sincronização de thread para proteger o cliente ou usar um novo objeto AzureMediaServicesClient por thread. Você também deve tomar cuidado com problemas de multi-threading introduzidos por objetos opcionais fornecidos pelo código ao cliente (como uma instância do HttpClient no .NET).

. Referência
SDK .NET Referência do .NET
Java SDK Referência de Java
SDK do Python Referência do Python
SDK do Node.js Referência do Node.js
SDK do Go Referência do Go

Confira também

Gerenciador dos Serviços de Mídia do Azure

O AMSE (Gerenciador dos Serviços de Mídia do Azure) é uma ferramenta disponível para clientes do Windows que desejam saber mais sobre os Serviços de Mídia. O AMSE é um aplicativo do WinForms/C# que carrega, baixa, codifica e transmite VoD e conteúdo ao vivo com os Serviços de Mídia. A ferramenta AMSE destina-se aos clientes que desejam testar os Serviços de Mídia sem escrever nenhum código. O código AMSE é fornecido como um recurso para clientes que desejam desenvolver com os Serviços de Mídia.

O AMSE é um projeto de software livre, cujo suporte é fornecido pela comunidade (os problemas podem ser relatados a https://github.com/Azure/Azure-Media-Services-Explorer/issues). Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para saber mais, confira as Perguntas frequentes sobre o Código de Conduta ou contate o opencode@microsoft.com caso tenha outras dúvidas ou comentários.

Filtragem, classificação, paginação de entidades dos Serviços de Mídia

Confira Filtragem, classificação, paginação de entidades dos Serviços de Mídia do Microsoft Azure.

Obter ajuda e suporte

Você pode entrar em contato com os Serviços de Mídia com dúvidas ou seguir nossas atualizações por um dos seguintes métodos: