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

O Video Indexer consolida várias tecnologias de inteligência artificial áudio e vídeo (IA) oferecidas pela Microsoft num único serviço integrado, tornando o desenvolvimento mais simples.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. As APIs são projetadas para permitir que os desenvolvedores se concentrem em consumir tecnologias de IA dos Media sem se preocuparem com a escala, alcance global, disponibilidade e fiabilidade das plataformas cloud.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 platforms. Pode utilizar a API para carregar os seus ficheiros, obter informações detalhadas sobre o vídeo, obter URLs de insights incorporados e widgets de jogadores, e muito mais.You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

Ao criar uma conta de Indexer de Vídeo, pode escolher uma conta de teste gratuita (onde obtém um certo número de minutos de indexação gratuitos) ou uma opção paga (onde não está limitado pela quota).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're not limited by the quota). Com um teste gratuito, o Video Indexer fornece até 600 minutos de indexação gratuita aos utilizadores do site e até 2400 minutos de indexação gratuita aos utilizadores de API.With a 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 uma opção paga, cria uma conta De Indexer de Vídeo que está ligada à sua subscrição Azure e a uma conta Azure Media Services.With a paid option, you create a Video Indexer account that's connected to your Azure subscription and an Azure Media Services account. Irá pagar pelos minutos de indexação e pelas cobranças relacionadas com a conta dos Serviços de Multimédia do Azure.You pay for minutes indexed as well as the Azure Media Services account related charges.

Este artigo mostra como os programadores podem tirar partido da API do Video Indexer.This article shows how the developers can take advantage of the Video Indexer API.

Subscrever a APISubscribe to the API

  1. Inicie sessão no Video Indexer Developer Portal.Sign in to Video Indexer Developer Portal.

    Inscreva-se no Portal de Desenvolvimento do Indexante de Vídeo

    Importante

    • Tem de utilizar o mesmo fornecedor que utilizou quando se inscreveu no Video Indexer.You must use the same provider you used when you signed up for Video Indexer.
    • As contas pessoais do Google e da Microsoft (Outlook/Live) só podem ser utilizadas para contas de teste.Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. As contas ligadas ao Azure necessitam do Azure AD.Accounts connected to Azure require Azure AD.
    • Só pode haver uma conta ativa por e-mail.There can be only one active account per email. Se um utilizador tentar iniciar sessão com user@gmail.com para o LinkedIn e mais tarde com user@gmail.com para a Google, este apresentará uma página de erro, dizendo que o utilizador já existe.If a user tries to sign in with user@gmail.com for LinkedIn and later with user@gmail.com for Google, the latter will display an error page, saying the user already exists.
  2. Subscreva.Subscribe.

    Selecione o separador Produtos. Em seguida, selecione Autorização e subscreva.Select the Products tab. Then, select Authorization and subscribe.

    Separador de produtos no portal de desenvolvedor de indicadores de vídeo

    Nota

    Os utilizadores novos estão automaticamente subscritos em Autorização.New users are automatically subscribed to Authorization.

    Assim que se inscrever, pode ver a sua subscrição e as suas chaves primárias e secundárias.Once you subscribe, you can see your subscription and your primary and secondary keys. As chaves devem ser protegidas.The keys should be protected. As chaves só devem ser utilizadas pelo seu código do servidor.The keys should only be used by your server code. Não devem estar disponíveis do lado do cliente (.js, .html, e assim por diante).They shouldn't be available on the client side (.js, .html, and so on).

    Subscrição e chaves no Portal de Desenvolvimento do Indexante de Vídeo

Dica

O utilizador do Video Indexer pode utilizar uma chave de subscrição individual para ligar a várias contas do Video Indexer.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. Em seguida, pode associar estas contas do Video Indexer a diferentes contas dos Serviços de Multimédia.You can then link these Video Indexer accounts to different Media Services accounts.

Obter o token de acesso com a API de AutorizaçãoObtain access token using the Authorization API

Uma vez subscrita a API de Autorização, pode obter fichas de acesso.Once you subscribe to the Authorization API, you can obtain access tokens. Utilizam-se estes tokens de acesso para efetuar a autenticação na API de Operações.These access tokens are used to authenticate against the Operations API.

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.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Nível de utilizador: As fichas de acesso ao nível do utilizador permitem-lhe realizar operações ao nível do utilizador.User level: User level access tokens let you perform operations on the user level. Permitem, por exemplo, obter contas associadas.For example, get associated accounts.
  • Nível de conta: Fichas de acesso ao nível da conta permitem-lhe realizar operações ao nível da conta ou ao nível de vídeo.Account level: Account level access tokens let you perform operations on the account level or the video level. Por exemplo, faça upload de vídeo, liste todos os vídeos, obtenha informações de vídeo, e assim por diante.For example, upload video, list all videos, get video insights, and so on.
  • Nível de vídeo: Fichas de acesso ao nível de vídeo permitem-lhe realizar operações num vídeoespecífico .Video level: Video level access tokens let you perform operations on a specific video. Por exemplo, obtenha informações de vídeo, baixe legendas, obtenha widgets, e assim por diante.For example, get video insights, download captions, get widgets, and so on.

Pode controlar se estas fichas são apenas de leitura ou se permitem a edição especificando allowEdit=true/false.You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

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.For most server-to-server scenarios, you'll probably use the same account token since it covers both account operations and video operations. No entanto, se planeia fazer chamadas do lado do cliente para o Indexer de Vídeo (por exemplo, a partir do JavaScript), gostaria de usar um sinal de acesso de vídeo para impedir que os clientes tenham acesso a toda a conta.However, if you're 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 de cliente do Indexer de Vídeo no seu cliente (por exemplo, usando O Widget Get Insights ou Get Player Widget), deve fornecer um sinal de acesso de vídeo.That's also the reason that when embedding Video Indexer client code in your client (for example, using Get Insights Widget or Get Player Widget), you must provide a video access token.

Para facilitar o processo, pode aceder a APIS > Authorization (Autorização) > Get Accounts (Obter Contas) para obter as suas contas sem ter de obter primeiro um token de utilizador.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. 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.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 uma hora.Access tokens expire after 1 hour. Certifique-se de que o seu token de acesso é válido antes de utilizar a API de Operações.Make sure your access token is valid before using the Operations API. Se expirar, ligue novamente para a API de Autorização para obter um novo sinal de acesso.If it expires, call the Authorization API again to get a new access token.

Está pronto para começar a integrar-se com a API.You're ready to start integrating with the API. Veja a descrição detalhada de cada API REST do Video Indexer.Find the detailed description of each Video Indexer REST API.

ID da ContaAccount ID

O parâmetro de ID da Conta é necessário em todas as chamadas à API operacionais.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 formas:Account ID is a GUID that can be obtained in one of the following ways:

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

    1. Aceda ao site do Video Indexer e inicie sessão.Browse to the Video Indexer website and sign in.

    2. Navegue para a página Settings (Definições).Browse to the Settings page.

    3. Copie o ID da Conta.Copy the account ID.

      Definições do Indexante de Vídeo e ID da conta

  • Utilize o Video Indexer Developer Portal para obter o ID da Conta através de programação.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Use a Conta Get API.Use the Get account API.

    Dica

    Pode gerar tokens de acesso para as contas ao definir 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 leitor na sua conta.Get the account ID from the URL of a player page in your account.

    Quando vê um vídeo, o ID aparece a seguir à secção accounts e antes da secção videos.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 secção lista algumas recomendações que deve ter em conta durante a utilização da API do Video Indexer.This section lists some recommendations when using Video Indexer API.

  • Se estiver a planear fazer o upload de um vídeo, é aconselhável colocar o ficheiro em algum local de rede pública (por exemplo, OneDrive).If you're planning to upload a video, it's recommended to place the file in some public network location (for example, OneDrive). Obtenha a ligação do vídeo e forneça o URL enquanto parâmetro de carregamento de ficheiro.Get the link to the video and provide the URL as the upload file param.

    O URL fornecido ao Video Indexer tem de apontar para um ficheiro de multimédia (áudio ou vídeo).The URL provided to Video Indexer must point to a media (audio or video) file. Algumas das ligações geradas pelo OneDrive encaminham para uma página HTML que contém o ficheiro.Some of the links generated by OneDrive are for an HTML page that contains the file. Uma verificação fácil para o URL é colá-lo em um navegador - se o ficheiro começar a descarregar, é provavelmente um bom URL.An easy verification for the URL is to paste it into a browser—if the file starts downloading, it's likely a good URL. Se o navegador está a fazer alguma visualização, é provável que não seja um link para um ficheiro, mas para uma página HTML.If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • 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.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. Veja informações detalhadas sobre o JSON devolvido neste tópico.See details about the returned JSON in this topic.

Exemplo de códigoCode sample

O seguinte fragmento de código C# demonstra a utilização de todas as APIs do Video Indexer em conjunto.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);

Ver tambémSee also

Passos seguintesNext steps

  • Examinar detalhes da saída JSONExamine details of the output JSON
  • Confira o código da amostra que demonstra um aspeto importante de carregar e indexar um vídeo.Check out the sample code that demonstrates important aspect of uploading and indexing a video. Seguir o código dar-lhe-á uma boa ideia de como usar a nossa API para funcionalidades básicas.Following the code wil give you a good idea of how to use our API for basic functionalities. Leia os comentários inline e note os nossos conselhos de boas práticas.Make sure to read the inline comments and notice our best practices advices.