Tutorial: Usar a API do Video IndexerTutorial: Use the Video Indexer API

O Video Indexer consolida várias tecnologias de inteligência artificial (AI) de áudio e vídeo oferecidas pela Microsoft em um único serviço integrado, tornando o desenvolvimento mais simples.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft in one integrated service, making development simpler. As APIs são projetadas para permitir que os desenvolvedores se concentrem no consumo de tecnologias de AI de mídia sem se preocupar com escala, alcance global, disponibilidade e confiabilidade da plataforma de nuvem.The APIs are designed to enable developers to focus on consuming Media AI technologies without worrying about scale, global reach, availability, and reliability of cloud platform. Você pode usar a API para fazer upload de seus arquivos, obter insights de vídeo detalhados, obter URLs de insights e widgets de player para incorporá-los ao seu aplicativo e outras tarefas.You can use the API to upload your files, get detailed video insights, get URLs of insight and player widgets in order to embed them into your application, and other tasks.

Ao criar uma conta do Video Indexer, você pode escolher uma conta de avaliação gratuita (em que você obtém um determinado número de minutos de indexação gratuitos) ou uma opção paga (onde você não está limitado pela cota).When creating a Video Indexer account, you can choose a free trial account (where you get a certain number of free indexing minutes) or a paid option (where you are not limited by the quota). Com o teste gratuito, o Video Indexer fornece até 600 minutos de indexação gratuita para usuários do site e até 2400 minutos de indexação gratuita para usuários da API.With free trial, Video Indexer provides up to 600 minutes of free indexing to website users and up to 2400 minutes of free indexing to API users. Com a opção paga, você cria uma conta do Video Indexer que está conectada à sua assinatura do Azure e a uma conta dos Serviços de Mídia do Azure.With paid option, you create a Video Indexer account that is connected to your Azure subscription and an Azure Media Services account. Você paga pelos minutos indexados, bem como os encargos relacionados à conta dos Serviços de Mídia do Azure.You pay for minutes indexed as well as the Azure Media Services account related charges.

Este artigo mostra como os desenvolvedores podem aproveitar a API do Video Indexer.This article shows how the developers can take advantage of the Video Indexer API.

Inscrever-se à APISubscribe to the API

  1. Entre no Portal do Desenvolvedor do Video Indexer.Sign in to Video Indexer Developer Portal.

    Entrar

    Importante

    • Você deve usar o mesmo provedor usado quando se inscreveu no Video Indexer.You must use the same provider you used when you signed up for Video Indexer.
    • As contas pessoais Google e Microsoft (perspectiva / vida) só podem ser usadas para contas de avaliação.Personal Google and Microsoft (outlook/live) accounts can only be used for trial accounts. Contas conectadas ao Azure exigem o Azure AD.Accounts connected to Azure require Azure AD.
    • Pode haver apenas uma conta ativa por email.There can be only one active account per E-Mail. Se um usuário tenta entrar com user@gmail.com para o LinkedIn e, depois disso com user@gmail.com para Google o posterior exibirá uma página de erro, informando que o usuário já existe.If a user tries to sign-in with user@gmail.com for LinkedIn and after that with user@gmail.com for Google the later will display an error page, saying the user already exist.
  2. Inscrever-se.Subscribe.

    Selecione a guia Produtos. Em seguida, selecione a autorização e inscrever-se.Select the Products tab. Then, select Authorization and subscribe.

    Inscrição

    Observação

    Novos usuários são automaticamente inscritos na Autorização.New users are automatically subscribed to Authorization.

    Depois de se inscrever, você poderá ver sua assinatura e suas chaves primárias e secundárias.Once you subscribe, you will be able to see your subscription and your primary and secondary keys. As chaves devem ser protegidas.The keys should be protected. As chaves só devem ser usadas pelo seu código do servidor.The keys should only be used by your server code. Eles não devem estar disponíveis no lado do cliente (.js, .html, etc.).They should not be available on the client side (.js, .html, etc.).

    Inscrição

Dica

O usuário do Video Indexer pode usar uma chave de assinatura única para se conectar a várias contas do aplicativo.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. Depois você pode vincular essas contas do Video Indexer para diferentes contas de Serviços de Mídia.You can then link these Video Indexer accounts to different Media Services accounts.

Obter o token de acesso usando a API de autorizaçãoObtain access token using the Authorization API

Depois de se inscrever na API de autorização, você poderá obter tokens de acesso.Once you subscribed to the Authorization API, you will be able to obtain access tokens. Esses tokens de acesso são usados para autenticar na API de operações.These access tokens are used to authenticate against the Operations API.

Cada chamada para a API de operações deve estar associada a um token de acesso, correspondendo ao escopo de autorização da chamada.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Nível de usuário - os tokens de acesso no nível do usuário permitem que você execute operações no nível do usuário.User level - user level access tokens let you perform operations on the user level. Por exemplo, obter contas associadas.For example, get associated accounts.
  • Nível da conta - os tokens de acesso no nível da conta permitem que você execute operações no nível da conta ou no nível do vídeo.Account level – account level access tokens let you perform operations on the account level or the video level. Por exemplo, carregar o vídeo, listar todos os vídeos, obtenha insights de vídeo, etc.For example, Upload video, list all videos, get video insights, etc.
  • Nível de vídeo - os tokens de acesso ao nível de vídeo permitem que você realize operações em um vídeo específico.Video level – video level access tokens let you perform operations on a specific video. Por exemplo, obtenha informações sobre vídeos, faça o download de legendas, obtenha widgets etc.For example, get video insights, download captions, get widgets, etc.

Você pode controlar se esses tokens são somente leitura ou se eles permitem editar especificando allowEdit = true / false.You can control whether these tokens are readonly or they allow editing by specifying allowEdit=true/false.

Na maioria dos cenários de servidor para servidor, você provavelmente usará o mesmo conta de token, pois ele abrange conta operações e vídeo operações.For most server-to-server scenarios, you will probably use the same account token since it covers both account operations and video operations. No entanto, se você estiver planejando fazer chamadas do lado do cliente para o Video Indexer (por exemplo, do javascript), convém usar um token de acesso video para impedir que os clientes obtenham acesso a toda a conta.However, if you are planning to make client side calls to Video Indexer (for example, from javascript), you would want to use a video access token, to prevent clients from getting access to the entire account. Essa também é a razão pela qual ao incorporar o código do cliente VideoIndexer em seu cliente (por exemplo, usando Get Insights Widget ou Get Player Widget) você deve fornecer um vídeo token de acesso.That is also the reason that when embedding VideoIndexer client code in your client (for example, using Get Insights Widget or Get Player Widget) you must provide a video access token.

Para facilitar, você pode usar a API de autorização> GetAccounts para obter suas contas sem obter primeiro um token de usuário.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. Você também pode pedir para obter as contas com tokens válidos, permitindo que você ignore uma chamada adicional para obter um token de conta.You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

Os tokens de acesso expiram após 1 hora.Access tokens expire after 1 hour. Certifique-se de que seu token de acesso seja válido antes de usar a API de operações.Make sure your access token is valid before using the Operations API. Se expirar, chame a API de autorização novamente para obter um novo token de acesso.If expires, call the Authorization API again to get a new access token.

Você está pronto para começar a integrar com a API.You are ready to start integrating with the API. Encontre a descrição detalhada de cada API REST do Indexador de Vídeo.Find the detailed description of each Video Indexer REST API.

ID da ContaAccount ID

O parâmetro de ID da conta é obrigatório em todas as chamadas da API operacional.The Account ID parameter is required in all operational API calls. O ID da conta é um GUID que pode ser obtido de uma das seguintes maneiras:Account ID is a GUID that can be obtained in one of the following ways:

  • Use o site do Video Indexer para obter a ID da conta:Use the Video Indexer website to get the Account ID:

    1. Navegue até o site do Video Indexer e entre.Browse to the Video Indexer website and sign in.

    2. Navegue até a configurações página.Browse to the Settings page.

    3. Copie a ID de conta.Copy the account ID.

      ID da Conta

  • Use o Portal do Desenvolvedor do Video Indexer para obter a ID da conta de maneira programática.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Use o obter contas API.Use the Get accounts API.

    Dica

    Você pode gerar tokens de acesso para as contas definindo generateAccessTokens=true.You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • Obtenha o ID da conta a partir do URL de uma página do player em sua conta.Get the account ID from the URL of a player page in your account.

    Quando você assiste a um vídeo, o ID aparece após a accountsseção e antes davideos seção.When you watch a video, the ID appears after the accounts section and before the videos section.

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

RecomendaçõesRecommendations

Esta seção lista algumas recomendações ao usar a API do Video Indexer.This section lists some recommendations when using Video Indexer API.

  • Se você planeja carregar um vídeo, é recomendável colocar o arquivo em algum local de rede pública (por exemplo, OneDrive).If you are planning to upload a video, it is recommended to place the file in some public network location (for example, OneDrive). Obter o link para vídeo e fornecer a URL como o parâmetro de arquivo de upload.Get the link to the video and provide the URL as the upload file param.

    A URL fornecida ao Video Indexer deve apontar para um arquivo de mídia (áudio ou vídeo).The URL provided to Video Indexer must point to a media (audio or video) file. Alguns dos links gerados pelo OneDrive são para uma página HTML que contém o arquivo.Some of the links generated by OneDrive are for an HTML page that contains the file. Uma verificação fácil para o URL seria colá-lo em um navegador. Se o arquivo começar a ser baixado, provavelmente é um bom URL.An easy verification for the URL would be to paste it into a browser – if the file starts downloading, it's likely a good URL. Se o navegador estiver processando alguma visualização, provavelmente não será um link para um arquivo, mas uma página HTML.If the browser is rendering some visualization, it's likely not a link to a file but an HTML page.

  • Quando você chama a API que recebe insights de vídeo para o vídeo especificado, você obtém uma saída JSON detalhada como o conteúdo da resposta.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. Ver detalhes sobre o JSON retornado neste tópico.See details about the returned JSON in this topic.

Exemplo de códigoCode sample

O seguinte snippet de código em C# demonstra o uso de todas as APIs do indexador de vídeo juntos.The following C# code snippet demonstrates the usage of all the Video Indexer APIs together.

var apiUrl = "https://api.videoindexer.ai";
var accountId = "..."; 
var location = "westus2";
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 =newbyte[video.Length];
  //video.Read(buffer, 0, buffer.Length);
  //content.Add(newByteArrayContent(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);

Consulte tambémSee also

Próximas etapasNext steps

Examinar os detalhes da saída JSON.Examine details of the output JSON.