Kurz: Používání rozhraní API Video IndexeruTutorial: Use the Video Indexer API

Video Indexer slučuje různé technologie pro audio a video umělal Intelligence (AI), které Microsoft nabízí, do jedné integrované služby, což zjednodušuje vývoj.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. Rozhraní API jsou navržená tak, aby umožňovala vývojářům soustředit se na využívání technologií Media AI, aniž by se museli starat o škálování, globální dosah, dostupnost a spolehlivost cloudových platforem.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. Rozhraní API můžete použít k nahrání souborů, získání podrobných informací o videích, získání adres URL pro vložené widgety a pomůcky pro vkládání a další informace.You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

Při vytváření účtu Video Indexeru můžete zvolit účet bezplatné zkušební verze (ve kterém získáte určitý počet minut indexování zdarma) nebo placenou variantu (ve které nejste omezení kvótou).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). V bezplatné zkušební verzi Video Indexer poskytuje až 600 minut bezplatného indexování pro webové uživatele a až 2 400 minut bezplatného indexování pro uživatele rozhraní 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. Pomocí placené možnosti vytvoříte účet Video Indexer, který je připojený k vašemu předplatnému Azure a účet 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. Platíte za minuty, další informace najdete v tématu Media Services ceny.You pay for minutes indexed, for more information, see Media Services pricing.

Tento článek popisuje, jak můžou vývojáři využít výhod rozhraní API Video Indexeru.This article shows how the developers can take advantage of the Video Indexer API.

Přihlášení k odběru rozhraní APISubscribe to the API

  1. Přihlaste se k portálu Video Indexer Developer Portal.Sign in to Video Indexer Developer Portal.

    Přečtěte si poznámku k verzi týkající se přihlašovacích informací.Review a release note regarding login information.

    Přihlášení k Video Indexer portálu pro vývojáře

    Důležité

    • Musíte použít stejného zprostředkovatele, jakého jste použili při registraci k Video Indexeru.You must use the same provider you used when you signed up for Video Indexer.
    • Účty osobních účtů Google a Microsoft (Outlook/Live) se dají používat jenom pro zkušební účty.Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. Účty připojené k Azure vyžadují Azure AD.Accounts connected to Azure require Azure AD.
    • V jednom e-mailu může být jenom jeden aktivní účet.There can be only one active account per email. Pokud se uživatel pokusí přihlásit pomocí user@gmail.com LinkedInu a novějšího s aplikací user@gmail.com pro Google, zobrazí se mu chybová stránka s oznámením, že uživatel už existuje.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. Přihlaste se k odběru.Subscribe.

    Vyberte kartu produkty . Pak vyberte autorizace a přihlášení k odběru.Select the Products tab. Then, select Authorization and subscribe.

    Karta produkty na portálu pro vývojáře Video Indexer

    Poznámka

    Noví uživatelé jsou k odběru API Authorization automaticky přihlášení.New users are automatically subscribed to Authorization.

    Po přihlášení k odběru můžete najít předplatné v části autorizace produktů -> .After you subscribe, you can find your subscription under Products -> Authorization. Na stránce předplatné najdete primární a sekundární klíče.In the subscription page, you will find the primary and secondary keys. Klíče by měly být chráněné.The keys should be protected. Klíče by měl používat jenom kód vašeho serveru.The keys should only be used by your server code. Neměly by být k dispozici na straně klienta (. js,. html atd.).They shouldn't be available on the client side (.js, .html, and so on).

    Předplatné a klíče na portálu pro vývojáře Video Indexer

Tip

Uživatelé Video Indexeru se můžou pomocí jednoho klíče předplatného připojit k několika účtům Video Indexeru.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. Tyto účty Video Indexeru můžete propojit s různými účty Media Services.You can then link these Video Indexer accounts to different Media Services accounts.

Získání přístupového tokenu pomocí rozhraní API AuthorizationObtain access token using the Authorization API

Jakmile se přihlásíte k odběru autorizačního rozhraní API, můžete získat přístupové tokeny.Once you subscribe to the Authorization API, you can obtain access tokens. Tyto přístupové tokeny se používají k ověřování v API Operations.These access tokens are used to authenticate against the Operations API.

Každé volání do API Operations by mělo být přidružené k přístupovému tokenu s odpovídajícím oborem autorizace volání.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Úroveň uživatele: tokeny přístupu na úrovni uživatele umožňují provádět operace na úrovni uživatele .User level: User level access tokens let you perform operations on the user level. Třeba získat přidružené účty.For example, get associated accounts.
  • Úroveň účtu: přístupové tokeny na úrovni účtu umožňují provádět operace na úrovni účtu nebo na úrovni videa .Account level: Account level access tokens let you perform operations on the account level or the video level. Například nahrávání videa, vypsání všech videí, získání přehledů videí atd.For example, upload video, list all videos, get video insights, and so on.
  • Úroveň videa: přístupové tokeny na úrovni videa umožňují provádět operace na konkrétním videu.Video level: Video level access tokens let you perform operations on a specific video. Můžete například získat přehled o videích, stahovat titulky, získávat widgety atd.For example, get video insights, download captions, get widgets, and so on.

Můžete řídit, jestli jsou tyto tokeny jen pro čtení, nebo pokud umožňují úpravy zadáním allowEdit = true/false.You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

Pro většinu scénářů mezi servery budete pravděpodobně používat stejný token účtu , protože zahrnuje operace s účty a video operace.For most server-to-server scenarios, you'll probably use the same account token since it covers both account operations and video operations. Pokud ale plánujete, že na straně klienta chcete Video Indexer (například z JavaScriptu), budete chtít použít token přístupu k videu , abyste klientům zabránili v získání přístupu k celému účtu.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. To je také důvod, proč při vkládání Video Indexer kódu klienta do klienta (například pomocí widgetu Get Insights nebo Get widget Player) musíte zadat přístupový token videa .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.

Kvůli usnadnění můžete pomocí Autorization API > GetAccounts získat účty bez předchozího získání tokenu uživatele.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. Můžete také požádat o získání účtů s platnými tokeny. To vám umožní přeskočit další volání pro získání tokenu účtu.You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

Platnost přístupových tokenů vyprší za 1 hodinu.Access tokens expire after 1 hour. Před použitím API Operations se ujistěte, že je váš přístupový token platný.Make sure your access token is valid before using the Operations API. V případě vypršení platnosti zavolejte autorizační rozhraní API, abyste získali nový přístupový token.If it expires, call the Authorization API again to get a new access token.

Jste připraveni zahájit integraci s rozhraním API.You're ready to start integrating with the API. Najděte si podrobný popis každého REST API Video Indexeru.Find the detailed description of each Video Indexer REST API.

Account IDAccount ID

Parametr Account ID (ID účtu) se vyžaduje u všech volání API operací.The Account ID parameter is required in all operational API calls. ID účtu je globálně jedinečný identifikátor, který se dá získat jedním z těchto způsobů:Account ID is a GUID that can be obtained in one of the following ways:

  • K získání ID účtu použijte web Video Indexer:Use the Video Indexer website to get the Account ID:

    1. Přejděte na web Video Indexer a přihlaste se.Browse to the Video Indexer website and sign in.

    2. Přejděte na stránku Settings (Nastavení).Browse to the Settings page.

    3. Zkopírujte ID účtu.Copy the account ID.

      Nastavení Video Indexer a ID účtu

  • K získání ID účtu prostřednictvím programu použijte Video Indexer Developer Portal.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Použijte rozhraní Get Account API.Use the Get account API.

    Tip

    Přístupové tokeny pro účty můžete vygenerovat tak, že definujete generateAccessTokens=true.You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • Získejte ID účtu z adresy URL stránky přehrávače ve vašem účtu.Get the account ID from the URL of a player page in your account.

    Při sledování videa se ID zobrazuje za částí accounts a před částí 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/
    

DoporučeníRecommendations

Tato část uvádí několik doporučení pro používání rozhraní API Video Indexeru.This section lists some recommendations when using Video Indexer API.

  • Pokud plánujete odeslat video, doporučujeme umístit soubor do umístění v některé veřejné síti (například účet Azure Blob Storage).If you're planning to upload a video, it's recommended to place the file in some public network location (for example, an Azure Blob Storage account). Získejte odkaz na video a zadejte adresu URL jako parametr souboru k nahrání.Get the link to the video and provide the URL as the upload file param.

    Adresa URL poskytnutá Video Indexeru musí odkazovat na soubor média (zvukový nebo video).The URL provided to Video Indexer must point to a media (audio or video) file. Jednoduché ověření adresy URL (nebo adresy URL SAS) je vložení do prohlížeče, pokud se soubor začne přehrávat/stahovat, je to nejspíš dobrá adresa URL.An easy verification for the URL (or SAS URL) is to paste it into a browser, if the file starts playing/downloading, it's likely a good URL. Pokud prohlížeč vykresluje určitou vizualizaci, nejedná se nejspíš o odkaz na soubor, ale na stránku HTML.If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • Při volání rozhraní API, které získává přehledy ze zadaného videa získáte jako obsah odpovědi podrobný výstup JSON.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. Podrobnosti o vráceném JSON najdete v tomto tématu.See details about the returned JSON in this topic.

Ukázka kóduCode sample

Následující fragment kódu v jazyce C# předvádí společné použití všech rozhraní API Video Indexeru.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"; // 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);

Vyčištění prostředkůClean up resources

Po dokončení tohoto kurzu odstraňte prostředky, které neplánujete použít.After you are done with this tutorial, delete resources that you are not planning to use.

Viz takéSee also

Další krokyNext steps

  • Projděte si podrobnosti výstupního formátu JSON.Examine details of the output JSON
  • Podívejte se na vzorový kód , který ukazuje důležité aspekty nahrávání a indexování videa.Check out the sample code that demonstrates important aspect of uploading and indexing a video. Následující kód vám poskytne dobrý nápad na použití našeho rozhraní API pro základní funkce.Following the code will give you a good idea of how to use our API for basic functionalities. Nezapomeňte si přečíst vložené komentáře a poznamenat naše rady k osvědčeným postupům.Make sure to read the inline comments and notice our best practices advices.