Programar com as APIs dos Serviços de Multimédia v3

  • Artigo

Logótipo dos Serviços de Multimédia v3

Aviso

Os Serviços de Multimédia do Azure serão descontinuados a 30 de junho de 2024. Para obter mais informações, consulte o Guia de Descontinuação do AMS.

Enquanto programador, pode utilizar bibliotecas de cliente para (.NET, Python, Node.js, Java e Go) que lhe permitem interagir com a API REST para criar, gerir e manter facilmente fluxos de trabalho multimédia personalizados. A API dos Serviços de Multimédia v3 baseia-se na especificação OpenAPI (anteriormente conhecida como Swagger).

Este artigo aborda regras que se aplicam a entidades e APIs quando desenvolve com os Serviços de Multimédia v3.

Aviso

Não é aconselhável tentar moldar a API REST dos Serviços de Multimédia diretamente no seu próprio código de biblioteca, uma vez que fazê-lo corretamente para fins de produção exigiria que implementasse a lógica de repetição completa do Azure Resource Management e compreendesse como gerir operações de execução prolongada nas APIs de Gestão de Recursos do Azure. Isto é processado pelos SDKs de cliente para vários idiomas - .NET, Java, TypeScript, Python, etc. - automaticamente e reduz as probabilidades de ter problemas com a lógica de repetição ou chamadas à API falhadas. Os SDKs de cliente já processam tudo isto por si.

Aceder à API dos Serviços de Multimédia do Azure

Para obter autorização para aceder aos recursos dos Serviços de Multimédia e à API dos Serviços de Multimédia, primeiro tem de se autenticar. Os Serviços de Multimédia suportam a autenticação baseada no Azure Active Directory (AAD). As duas opções de autenticação comuns são:

  • Autenticação do principal de serviço: utilizada para autenticar um serviço (por exemplo: aplicações Web, aplicações de funções, aplicações lógicas, API e microsserviços). As aplicações que normalmente utilizam este método de autenticação são aplicações que executam serviços daemon, serviços de camada média ou tarefas agendadas. Por exemplo, para aplicações Web, deve haver sempre uma camada média que se ligue aos Serviços de Multimédia com um Principal de Serviço.
  • Autenticação do utilizador: utilizada para autenticar uma pessoa que está a utilizar a aplicação para interagir com os recursos dos Serviços de Multimédia. A aplicação interativa deve primeiro pedir ao utilizador as suas credenciais. Um exemplo é uma aplicação da consola de gestão utilizada pelos utilizadores autorizados para monitorizar as tarefas de codificação ou a transmissão em direto.

A API dos Serviços de Multimédia exige que o utilizador ou a aplicação que faz os pedidos da API REST tenha acesso ao recurso da conta dos Serviços de Multimédia e utilize uma função de Contribuidor ou Proprietário. A API pode ser acedida com a função Leitor, mas apenas as operações Obter ou Lista estarão disponíveis. Para obter mais informações, veja Controlo de acesso baseado em funções do Azure (RBAC do Azure) para contas de Serviços de Multimédia.

Em vez de criar um principal de serviço, considere utilizar identidades geridas para os recursos do Azure para aceder à API dos Serviços de Multimédia através do Azure Resource Manager. Para saber mais sobre as identidades geridas dos recursos do Azure, veja O que são identidades geridas dos recursos do Azure?.

Azure AD principal de serviço

O Azure AD principal de aplicação e serviço deve estar no mesmo inquilino. Depois de criar a aplicação, atribua acesso à função Contribuidor ou Proprietário da aplicação à conta dos Serviços de Multimédia.

Se não tiver a certeza se tem permissões para criar uma aplicação Azure AD, consulte Permissões necessárias.

Na figura seguinte, os números representam o fluxo dos pedidos por ordem cronológica:

Autenticação de aplicações de camada média com o AAD a partir de uma API Web

  1. Uma aplicação de camada média pede um token de acesso Azure AD que tenha os seguintes parâmetros:

    • Azure AD ponto final do inquilino.
    • URI de recurso dos Serviços de Multimédia.
    • URI de Recursos para Os Serviços de Multimédia REST.
    • Azure AD valores da aplicação: o ID de cliente e o segredo do cliente.

    Para obter todos os valores necessários, veja Aceder à API dos Serviços de Multimédia do Azure.

  2. O token de acesso Azure AD é enviado para a camada média.

  3. A camada média envia um pedido para a API REST de Multimédia do Azure com o token de Azure AD.

  4. A camada média obtém os dados dos Serviços de Multimédia.

Amostras

Veja os exemplos seguintes que mostram como se ligar ao principal de serviço Azure AD:

Convenções de nomenclatura

Os nomes de recursos dos Serviços de Multimédia do Azure v3 (por exemplo, Ativos, Tarefas, Transformações) estão sujeitos às restrições de nomenclatura do Azure Resource Manager. De acordo com o Azure Resource Manager, os nomes de recursos são sempre exclusivos. Desta forma, pode utilizar todas as cadeias de identificador exclusivo (por exemplo, GUIDs) para os nomes de recursos.

Os nomes de recursos dos Serviços de Multimédia não podem incluir: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', o caráter de plica ou quaisquer carateres de controlo. Todos os outros carateres são permitidos. O comprimento máximo de um nome de recurso é superior a 260 carateres.

Para obter mais informações sobre a nomenclatura de Resource Manager do Azure, veja Requisitos de nomenclatura e convenções de Nomenclatura.

Nomes de ficheiros/blobs num recurso

Os nomes dos ficheiros/blobs num recurso têm de seguir os requisitos de nome do blob e os requisitos de nome NTFS. O motivo para estes requisitos é que os ficheiros podem ser copiados do armazenamento de blobs para um disco NTFS local para processamento.

Operações de execução prolongada

As operações marcadas com x-ms-long-running-operation nos ficheiros swagger dos Serviços de Multimédia do Azure são operações de execução prolongada.

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

Os Serviços de Multimédia têm as seguintes operações de execução prolongada:

Após a submissão bem-sucedida de uma operação longa, recebe um "201 Criado" e tem de consultar a conclusão da operação com o ID da operação devolvida.

O artigo controlar operações assíncronas do Azure explica em profundidade como controlar o estado das operações assíncronas do Azure através dos valores devolvidos na resposta.

Apenas uma operação de execução prolongada é suportada para um determinado Evento em Direto ou qualquer uma das respetivas Saídas em Direto associadas. Uma vez iniciada, uma operação de execução prolongada tem de ser concluída antes de iniciar uma operação de execução prolongada subsequente no mesmo LiveEvent ou em quaisquer Saídas em Direto associadas. Para Eventos em Direto com várias Saídas em Direto, tem de aguardar a conclusão de uma operação de execução prolongada numa Saída em Direto antes de acionar uma operação de execução prolongada noutra Saída em Direto.

SDKs

Nota

Não é garantido que os SDKs v3 dos Serviços de Multimédia do Azure sejam seguros para threads. Ao desenvolver uma aplicação com vários threads, deve adicionar a sua própria lógica de sincronização de threads para proteger o cliente ou utilizar um novo objeto AzureMediaServicesClient por thread. Também deve ter cuidado com os problemas de vários threads introduzidos pelos objetos opcionais fornecidos pelo código ao cliente (como uma instância httpClient no .NET).

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

Ver também

Explorador dos Serviços de Multimédia do Azure

O Explorador de Serviços de Multimédia do Azure (AMSE) é uma ferramenta disponível para clientes do Windows que querem saber mais sobre os Serviços de Multimédia. O AMSE é uma aplicação Winforms/C# que carrega, transfere, codifica, transmite VOD e conteúdos em direto com os Serviços de Multimédia. A ferramenta AMSE destina-se a clientes que pretendem testar os Serviços de Multimédia sem escrever código. O código AMSE é fornecido como um recurso para os clientes que pretendem desenvolver com os Serviços de Multimédia.

O AMSE é um projeto Open Source, o suporte é fornecido pela comunidade (os problemas podem ser comunicados a https://github.com/Azure/Azure-Media-Services-Explorer/issues). Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com outras perguntas ou comentários.

Filtragem, ordenação, paginação de entidades dos Serviços de Multimédia

Veja Filtragem, ordenação, paginação de entidades dos Serviços de Multimédia do Azure.

Obter ajuda e suporte

Pode contactar os Serviços de Multimédia com perguntas ou seguir as nossas atualizações através de um dos seguintes métodos: