Tutorial: Uso de la API Video IndexerTutorial: Use the Video Indexer API

Video Indexer consolida varias tecnologías de inteligencia artificial (IA) de audio y vídeo ofrecidas por Microsoft en un servicio integrado que facilita el desarrollo.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. Las API están diseñadas para que los desarrolladores puedan centrarse en el uso de las tecnologías de IA de multimedia sin preocuparse por la escala, el alcance global, la disponibilidad y la confiabilidad de las plataformas en la nube.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. Puede usar la API para cargar los archivos, obtener información de vídeo detallada, obtener direcciones URL de widgets de reproductor e información insertables, etc.You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

Al crear una cuenta de Video Indexer, puede optar entre una cuenta de evaluación gratuita (donde obtiene un número determinado de minutos gratuitos de indexación) o una opción de pago (donde no está limitado por la cuota).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). Con una versión de evaluación gratuita, Video Indexer proporciona hasta 600 horas de indexación gratuita a los usuarios de sitios web y hasta 2400 minutos de indexación gratuita a los usuarios 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. Con una opción de pago, se crea una cuenta de Video Indexer que está conectada a la suscripción de Azure y a una cuenta de 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. Se paga por minutos de indexación y por los cargos relacionados con la cuenta de Azure Media Services.You pay for minutes indexed as well as the Azure Media Services account related charges.

En este artículo se muestra cómo los desarrolladores pueden sacar partido de Video Indexer API.This article shows how the developers can take advantage of the Video Indexer API.

Suscripción a la APISubscribe to the API

  1. Inicie sesión en el portal para desarrolladores de Video Indexer.Sign in to Video Indexer Developer Portal.

    Inicio de sesión en el Portal para desarrolladores de Video Indexer

    Importante

    • Debe usar el mismo proveedor que utilizó al suscribirse a Video Indexer.You must use the same provider you used when you signed up for Video Indexer.
    • Las cuentas personales de Google y Microsoft (Outlook/Live) solo se pueden usar para las cuentas de evaluación gratuita.Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. Las cuentas conectadas a Azure requieren Azure AD.Accounts connected to Azure require Azure AD.
    • Solo puede haber una cuenta activa por correo electrónico.There can be only one active account per email. Si un usuario intenta iniciar sesión con user@gmail.com para LinkedIn y después con user@gmail.com para Google, este último muestra una página de error que indica que el usuario ya 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. Suscríbase.Subscribe.

    Seleccione la pestaña Products (Productos). Seleccione Authorization y suscríbase.Select the Products tab. Then, select Authorization and subscribe.

    Pestaña Productos del Portal para desarrolladores de Video Indexer

    Nota

    Los nuevos usuarios se suscriben automáticamente a Authorization.New users are automatically subscribed to Authorization.

    Después de suscribirse, puede ver la suscripción y las claves principal y secundaria.Once you subscribe, you can see your subscription and your primary and secondary keys. Debe proteger las claves.The keys should be protected. Las claves solo debe usarlas el código del servidor.The keys should only be used by your server code. No deben estar disponibles en el cliente (.js, .html, etc.).They shouldn't be available on the client side (.js, .html, and so on).

    Suscripción y claves en el Portal para desarrolladores de Video Indexer

Sugerencia

El usuario de Video Indexer puede usar una clave de suscripción única para conectarse a varias cuentas de Video Indexer.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. A continuación, puede vincular estas cuentas de Video Indexer a diferentes cuentas de Media Services.You can then link these Video Indexer accounts to different Media Services accounts.

Obtención del token de acceso mediante Authorization APIObtain access token using the Authorization API

Una vez suscrito a la API de autorización, puede obtener tokens de acceso.Once you subscribe to the Authorization API, you can obtain access tokens. Estos tokens de acceso se usan para autenticarse en Operations API.These access tokens are used to authenticate against the Operations API.

Cada llamada a Operations API debe asociarse con un token de acceso, correspondiente al ámbito de autorización de la llamada.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Nivel de usuario: los tokens de acceso de nivel de usuario permiten realizar operaciones en el nivel de usuario.User level: User level access tokens let you perform operations on the user level. Por ejemplo, obtener cuentas asociadas.For example, get associated accounts.
  • Nivel de cuenta: los tokens de acceso de nivel de cuenta permiten realizar operaciones en el nivel de cuenta o de vídeo.Account level: Account level access tokens let you perform operations on the account level or the video level. Por ejemplo, cargar vídeo, enumerar todos los vídeos, obtener información de vídeo, etc.For example, upload video, list all videos, get video insights, and so on.
  • Nivel de vídeo: los tokens de acceso de nivel de vídeo permiten realizar operaciones en un vídeo concreto.Video level: Video level access tokens let you perform operations on a specific video. Por ejemplo, obtener información de vídeo, descargar títulos, obtener widgets, etc.For example, get video insights, download captions, get widgets, and so on.

Para controlar si estos tokens son de solo lectura o si permiten editar, especifique allowEdit=true/false.You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

En la mayoría de los escenarios de servidor a servidor probablemente use el mismo token de cuenta, porque abarca tanto operaciones de cuenta como 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. Pero si va a realizar llamadas de cliente a Video Indexer (por ejemplo, desde JavaScript), probablemente quiera usar un token de acceso de vídeo para evitar que los clientes tengan acceso a toda la cuenta.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. Ese es también el motivo por el que, cuando se inserta código de cliente de Video Indexer en el cliente (por ejemplo, mediante los widgets Obtener información u Obtener reproductor), se debe proporcionar un token de acceso 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 las cosas, puede usar Authorization API > GetAccounts para obtener las cuentas sin obtener un token de usuario primero.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. También puede solicitar las cuentas con tokens válidos, para ahorrarse una llamada al obtener un token de cuenta.You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

Los tokens de acceso expiran en 1 hora.Access tokens expire after 1 hour. Asegúrese de que el token de acceso es válido antes de usar Operations API.Make sure your access token is valid before using the Operations API. Si expira, vuelva a llamar a la API de autorización para obtener un nuevo token de acceso.If it expires, call the Authorization API again to get a new access token.

Ya está listo para iniciar la integración con la API.You're ready to start integrating with the API. Consulte la descripción detallada de cada API REST de Video Indexer.Find the detailed description of each Video Indexer REST API.

Identificador de cuentaAccount ID

El parámetro accountId es obligatorio en todas las llamadas a las API de operaciones.The Account ID parameter is required in all operational API calls. El identificador de cuenta es un GUID que puede obtenerse de las siguientes maneras:Account ID is a GUID that can be obtained in one of the following ways:

  • Use el sitio web de Video Indexer para obtener el identificador de cuenta:Use the Video Indexer website to get the Account ID:

    1. Vaya al sitio web de Video Indexer e inicie sesión.Browse to the Video Indexer website and sign in.

    2. Vaya a la página Configuración.Browse to the Settings page.

    3. Copie el identificador de cuenta.Copy the account ID.

      Configuración de Video Indexer e identificador de cuenta

  • Use el portal para desarrolladores de Video Indexer para obtener mediante programación el identificador de cuenta.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Use la API Get accounts.Use the Get accounts API.

    Sugerencia

    Para generar tokens de acceso para las cuentas, puede definir generateAccessTokens=true.You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • Obtenga el identificador de cuenta de la dirección URL de una página de reproductor en su cuenta.Get the account ID from the URL of a player page in your account.

    Cuando vea un vídeo, el identificador aparece después de la sección accounts y antes de la sección 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/
    

RecomendacionesRecommendations

En esta sección se enumeran algunas recomendaciones para usar Video Indexer API.This section lists some recommendations when using Video Indexer API.

  • Si va a cargar un vídeo, se recomienda colocar el archivo en una ubicación de red pública (por ejemplo, OneDrive).If you're planning to upload a video, it's recommended to place the file in some public network location (for example, OneDrive). Obtenga el vínculo al vídeo y proporcione la dirección URL como parámetro del archivo de carga.Get the link to the video and provide the URL as the upload file param.

    La dirección URL proporcionada a Video Indexer debe apuntar a un archivo multimedia (audio o vídeo).The URL provided to Video Indexer must point to a media (audio or video) file. Algunos de los vínculos generados por OneDrive son los de una página HTML que contiene el archivo.Some of the links generated by OneDrive are for an HTML page that contains the file. Para comprobar la dirección URL fácilmente, péguela en un explorador: si el archivo inicia la descarga, probablemente es una dirección URL válida.An easy verification for the URL is to paste it into a browser—if the file starts downloading, it's likely a good URL. Si el explorador representa alguna visualización, probablemente no es un vínculo a un archivo, sino a una página HTML.If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • Cuando se llama a la API que obtiene información detallada del vídeo especificado, se obtiene una salida JSON detallada como contenido de la respuesta.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. Consulte más información sobre el código JSON devuelto en este tema.See details about the returned JSON in this topic.

Código de ejemploCode sample

El siguiente fragmento de código de C# muestra el uso de todas las API de Video Indexer juntas.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);

Otras referenciasSee also

Pasos siguientesNext steps

Examen detallado de la salida JSON.Examine details of the output JSON.