Tutorial: Utilizar a API do Video Indexer do Azure

O Azure Video Indexer consolida várias tecnologias de inteligência artificial (IA) de áudio e vídeo oferecidas pela Microsoft num serviço integrado, facilitando o desenvolvimento. As APIs foram concebidas para permitir que os programadores se concentrem no consumo de tecnologias de IA de Multimédia sem se preocuparem com o dimensionamento, alcance global, disponibilidade e fiabilidade das plataformas na cloud. Pode utilizar a API para carregar os seus ficheiros, obter informações de vídeo detalhadas, obter URLs de informações incorporadas e widgets de leitor e muito mais.

Quando visita o site do Azure Video Indexer pela primeira vez, é criada automaticamente uma conta de avaliação. Com a conta de avaliação, obtém alguns minutos de indexação gratuitos. Mais tarde, pode adicionar uma conta paga. Com a opção paga, paga por minutos indexados. Para obter detalhes sobre as contas disponíveis (opções de avaliação e pagas), veja Tipos de contas do Azure Video Indexer.

Este artigo mostra como os programadores podem tirar partido da API do Azure Video Indexer.

Pré-requisito

Antes de começar, consulte a secção Recomendações (que se segue mais adiante neste artigo).

Subscrever a API

  1. Inicie sessão no portal de programador da API do Azure Video Indexer.

    Importante

    • Tem de utilizar o mesmo fornecedor que utilizou quando se inscreveu no Azure Video Indexer.
    • As contas Pessoais google e Microsoft (Outlook/Live) só podem ser utilizadas para contas de avaliação. As contas ligadas ao Azure necessitam do Azure AD.
    • Só pode existir uma conta ativa por e-mail. Se um utilizador tentar iniciar sessão no LinkedIn e posteriormente no user@gmail.comuser@gmail.com para o Google, este último apresentará uma página de erro a indicar que o utilizador já existe.

    Iniciar sessão no portal de programador da API do Azure Video Indexer

  2. Subscreva.

    Selecione o separador Produtos . Em seguida, selecione Autorização e subscreva.

    Nota

    Os utilizadores novos estão automaticamente subscritos em Autorização.

    Depois de subscrever, pode encontrar a sua subscrição em Produtos ->Perfil. Na secção subscrições, encontrará as chaves primárias e secundárias. As chaves devem ser protegidas. As chaves só devem ser utilizadas pelo seu código do servidor. Não devem estar disponíveis no lado do cliente (.js, .html, etc.).

    Subscrição e chaves no portal de programador da API do Azure Video Indexer

Um utilizador do Azure Video Indexer pode utilizar uma única chave de subscrição para ligar a várias contas do Azure Video Indexer. Em seguida, pode ligar estas contas do Video Indexer do Azure a diferentes contas dos Serviços de Multimédia.

Obter o token de acesso com a API de Autorização

Depois de subscrever a API de Autorização, pode obter tokens de acesso. Utilizam-se estes tokens de acesso para efetuar a autenticação na API de Operações.

Cada chamada efetuada para a API de Operações deve estar associada a um token de acesso que corresponda ao âmbito de autorização da chamada.

  • Nível de utilizador: os tokens de acesso ao nível do utilizador permitem-lhe realizar operações ao nível do utilizador . Permitem, por exemplo, obter contas associadas.
  • Nível da conta: os tokens de acesso ao nível da conta permitem-lhe realizar operações ao nível da conta ou ao nível do vídeo . Por exemplo, carregue vídeo, liste todos os vídeos, obtenha informações de vídeo e assim sucessivamente.
  • Nível de vídeo: os tokens de acesso ao nível do vídeo permitem-lhe realizar operações num vídeo específico. Por exemplo, obtenha informações de vídeo, transfira legendas, obtenha widgets, etc.

Pode controlar o nível de permissão dos tokens de duas formas:

  • Para tokens de Conta, pode utilizar a API Obter Token de Acesso à Conta com Permissão e especificar o tipo de permissão (ProprietáriomyAccessManager/do Contribuidor/ do Leitor/).
  • Para todos os tipos de tokens (incluindo tokens de conta ), pode especificar allowEdit=true/false. falso é o equivalente a uma permissão de Leitor (só de leitura) e verdadeiro é o equivalente a uma permissão contribuidor (leitura-escrita).

Para a maioria dos cenários servidor a servidor, provavelmente utilizará o mesmo token de conta , uma vez que abrange operações de conta e operações de vídeo . No entanto, se estiver a planear fazer chamadas do lado do cliente para o Video Indexer do Azure (por exemplo, a partir de JavaScript), deve utilizar um token de acesso de vídeo para impedir que os clientes tenham acesso a toda a conta. Esta é também a razão pela qual, ao incorporar código de cliente do Azure Video Indexer no seu cliente (por exemplo, ao utilizar o Widget Get Insights ou Obter Widget do Leitor), tem de fornecer um token de acesso de vídeo .

Para facilitar o processo, pode utilizar a API > de AutorizaçãoGetAccounts para obter as suas contas sem obter primeiro um token de utilizador. Também pode pedir para obter as contas com tokens válidos, o que evita a realização de uma chamada adicional para obter um token de conta.

Os tokens de acesso expiram após uma hora. Certifique-se de que o seu token de acesso é válido antes de utilizar a API de Operações. Se expirar, chame novamente a API de Autorização para obter um novo token de acesso.

Está pronto para começar a integrar com a API. Encontre a descrição detalhada de cada API REST do Azure Video Indexer.

Chamadas à API Operacional

O parâmetro de ID da Conta é necessário em todas as chamadas à API operacionais. O ID da Conta é um GUID que pode ser obtido de uma das seguintes formas:

  • Utilize o site do Azure Video Indexer para obter o ID da Conta:

    1. Navegue para o site do Azure Video Indexer e inicie sessão.

    2. Navegue para a página Settings (Definições).

    3. Copie o ID da Conta.

      Definições e ID da conta do Video Indexer do Azure

  • Utilize o Portal do Programador do Azure Video Indexer para obter programaticamente o ID da Conta.

    Utilize a API Obter conta .

    Dica

    Pode gerar tokens de acesso para as contas ao definir generateAccessTokens=true.

  • Obtenha o ID da Conta a partir do URL de uma página do leitor na sua conta.

    Quando vê um vídeo, o ID aparece a seguir à secção accounts e antes da secção videos.

    https://www.videoindexer.ai/accounts/00000000-f324-4385-b142-f77dacb0a368/videos/d45bf160b5/
    

Recomendações

Esta secção lista algumas recomendações ao utilizar a API do Video Indexer do Azure.

A carregar

  • Se estiver a planear carregar um vídeo, recomenda-se que coloque o ficheiro numa localização de rede pública (por exemplo, uma conta Armazenamento de Blobs do Azure). Obtenha a ligação do vídeo e forneça o URL enquanto parâmetro de carregamento de ficheiro.

    O URL fornecido ao Video Indexer do Azure tem de apontar para um ficheiro de multimédia (áudio ou vídeo). Uma verificação fácil para o URL (ou URL de SAS) é colá-lo num browser. Se o ficheiro começar a ser reproduzido/transferido, é provável que seja um bom URL. Se o browser estiver a compor alguma visualização, é provável que não seja uma ligação para um ficheiro, mas para uma página HTML. Ao carregar vídeos com a API, tem as seguintes opções:

  • Carregue o vídeo a partir de um URL (preferencial).
  • Envie o ficheiro de vídeo como uma matriz de bytes no corpo do pedido.
  • Utilize um recurso dos Serviços de Multimédia do Azure existente ao fornecer o ID do recurso. Esta opção é suportada apenas em contas pagas.

Obter saída JSON

  • Quando chama a API que obtém informações de vídeo para o vídeo especificado, obtém uma saída JSON detalhada como conteúdo de resposta. Veja os detalhes sobre o JSON devolvido neste artigo.

  • A saída JSON produzida pela API contém Insights e SummarizedInsights elementos. Recomendamos vivamente que utilize Insights e não utilize SummarizedInsights (que está presente para retrocompatibilidade).

  • Não recomendamos que utilize dados diretamente da pasta artefactos para fins de produção. Os artefactos são saídas intermédias do processo de indexação. São essencialmente saídas não processadas dos vários motores de IA que analisam os vídeos; o esquema dos artefactos pode mudar ao longo do tempo.

    Recomenda-se que utilize a API Obter Índice de Vídeo , conforme descrito em Obter informações e artefactos produzidos pela API e nãoGet-Video-Artifact-Download-Url.

Exemplo de código

O fragmento de código C# seguinte demonstra a utilização de todas as APIs do Azure Video Indexer em conjunto.

Nota

O exemplo seguinte destina-se apenas a contas clássicas e não é compatível com contas baseadas em ARM. Para obter um exemplo atualizado do ARM (recomendado), veja este repositório de exemplo do ARM.

var apiUrl = "https://api.videoindexer.ai";
var accountId = "..."; 
var location = "westus2"; // replace with the account's location, or with “trial” if this is a trial account
var apiKey = "..."; 

System.Net.ServicePointManager.SecurityProtocol = System.Net.ServicePointManager.SecurityProtocol | System.Net.SecurityProtocolType.Tls12;

// create the http client
var handler = new HttpClientHandler(); 
handler.AllowAutoRedirect = false; 
var client = new HttpClient(handler);
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", apiKey); 

// obtain account access token
var accountAccessTokenRequestResult = client.GetAsync($"{apiUrl}/auth/{location}/Accounts/{accountId}/AccessToken?allowEdit=true").Result;
var accountAccessToken = accountAccessTokenRequestResult.Content.ReadAsStringAsync().Result.Replace("\"", "");

client.DefaultRequestHeaders.Remove("Ocp-Apim-Subscription-Key");

// upload a video
var content = new MultipartFormDataContent();
Debug.WriteLine("Uploading...");
// get the video from URL
var videoUrl = "VIDEO_URL"; // replace with the video URL

// as an alternative to specifying video URL, you can upload a file.
// remove the videoUrl parameter from the query string below and add the following lines:
  //FileStream video =File.OpenRead(Globals.VIDEOFILE_PATH);
  //byte[] buffer = new byte[video.Length];
  //video.Read(buffer, 0, buffer.Length);
  //content.Add(new ByteArrayContent(buffer));

var uploadRequestResult = client.PostAsync($"{apiUrl}/{location}/Accounts/{accountId}/Videos?accessToken={accountAccessToken}&name=some_name&description=some_description&privacy=private&partition=some_partition&videoUrl={videoUrl}", content).Result;
var uploadResult = uploadRequestResult.Content.ReadAsStringAsync().Result;

// get the video id from the upload result
var videoId = JsonConvert.DeserializeObject<dynamic>(uploadResult)["id"];
Debug.WriteLine("Uploaded");
Debug.WriteLine("Video ID: " + videoId);           

// obtain video access token
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", apiKey);
var videoTokenRequestResult = client.GetAsync($"{apiUrl}/auth/{location}/Accounts/{accountId}/Videos/{videoId}/AccessToken?allowEdit=true").Result;
var videoAccessToken = videoTokenRequestResult.Content.ReadAsStringAsync().Result.Replace("\"", "");

client.DefaultRequestHeaders.Remove("Ocp-Apim-Subscription-Key");

// wait for the video index to finish
while (true)
{
  Thread.Sleep(10000);

  var videoGetIndexRequestResult = client.GetAsync($"{apiUrl}/{location}/Accounts/{accountId}/Videos/{videoId}/Index?accessToken={videoAccessToken}&language=English").Result;
  var videoGetIndexResult = videoGetIndexRequestResult.Content.ReadAsStringAsync().Result;

  var processingState = JsonConvert.DeserializeObject<dynamic>(videoGetIndexResult)["state"];

  Debug.WriteLine("");
  Debug.WriteLine("State:");
  Debug.WriteLine(processingState);

  // job is finished
  if (processingState != "Uploaded" && processingState != "Processing")
  {
      Debug.WriteLine("");
      Debug.WriteLine("Full JSON:");
      Debug.WriteLine(videoGetIndexResult);
      break;
  }
}

// search for the video
var searchRequestResult = client.GetAsync($"{apiUrl}/{location}/Accounts/{accountId}/Videos/Search?accessToken={accountAccessToken}&id={videoId}").Result;
var searchResult = searchRequestResult.Content.ReadAsStringAsync().Result;
Debug.WriteLine("");
Debug.WriteLine("Search:");
Debug.WriteLine(searchResult);

// get insights widget url
var insightsWidgetRequestResult = client.GetAsync($"{apiUrl}/{location}/Accounts/{accountId}/Videos/{videoId}/InsightsWidget?accessToken={videoAccessToken}&widgetType=Keywords&allowEdit=true").Result;
var insightsWidgetLink = insightsWidgetRequestResult.Headers.Location;
Debug.WriteLine("Insights Widget url:");
Debug.WriteLine(insightsWidgetLink);

// get player widget url
var playerWidgetRequestResult = client.GetAsync($"{apiUrl}/{location}/Accounts/{accountId}/Videos/{videoId}/PlayerWidget?accessToken={videoAccessToken}").Result;
var playerWidgetLink = playerWidgetRequestResult.Headers.Location;
Debug.WriteLine("");
Debug.WriteLine("Player Widget url:");
Debug.WriteLine(playerWidgetLink);

Limpar os recursos

Depois de terminar este tutorial, elimine os recursos que não está a planear utilizar.

Ver também

Passos seguintes

  • Examinar os detalhes do JSON de saída
  • Veja o código de exemplo que demonstra um aspeto importante do carregamento e indexação de um vídeo. Seguir o código irá dar-lhe uma boa ideia de como utilizar a nossa API para funcionalidades básicas. Certifique-se de que lê os comentários inline e repare nos nossos conselhos de melhores práticas.