Samouczek: używanie interfejsu API usługi Video IndexerTutorial: Use the Video Indexer API

Video Indexer konsoliduje różne technologie audio i wideo sztuczne inteligencje (AI) oferowane przez firmę Microsoft w ramach jednej zintegrowanej usługi, co upraszcza programowanie.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. Interfejsy API zostały zaprojektowane, aby umożliwić deweloperom skoncentrowanie się na zużywaniu technologii multimedialnych, bez konieczności przejmowania się skalowaniem, globalnym zasięgiem, dostępnością i niezawodnością platform chmurowych.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. Możesz użyć interfejsu API do przekazywania plików, uzyskiwać szczegółowe informacje o wideo, uzyskiwać adresy URL z możliwością osadzania i elementów widget i nie tylko.You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

Podczas tworzenia konta Video Indexer możesz wybrać bezpłatne konto próbne (w przypadku wybrania pewnej liczby bezpłatnych minut indeksowania) lub opcji płatnej (w przypadku których limit przydziału nie jest ograniczony).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). Dzięki bezpłatnej wersji próbnej Video Indexer zapewnia do 600 minut bezpłatnego indeksowania do użytkowników witryny sieci Web oraz do 2400 minut wolnego indeksowania do użytkowników interfejsu 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. Za pomocą płatnej opcji utworzysz konto Video Indexer, które jest połączone z subskrypcją platformy Azure i kontem 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. Naliczane są opłaty za minuty indeksowania, a także opłaty powiązane z kontem usługi Azure Media Services.You pay for minutes indexed as well as the Azure Media Services account related charges.

W tym artykule pokazano, jak deweloperzy mogą korzystać z interfejsu API usługi Video Indexer.This article shows how the developers can take advantage of the Video Indexer API.

Subskrybowanie interfejsu APISubscribe to the API

  1. Zaloguj się w portalu dla deweloperów usługi Video Indexer.Sign in to Video Indexer Developer Portal.

    Zaloguj się do portalu Video Indexer Developer

    Ważne

    • Musisz użyć tego samego dostawcy, który został użyty podczas tworzenia konta w usłudze Video Indexer.You must use the same provider you used when you signed up for Video Indexer.
    • Osobiste konta Google i Microsoft (Outlook/Live) mogą być używane tylko w przypadku kont próbnych.Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. Konta połączone z platformą Azure wymagają usługi Azure AD.Accounts connected to Azure require Azure AD.
    • Na adres e-mail może istnieć tylko jedno aktywne konto.There can be only one active account per email. Jeśli użytkownik próbuje zalogować się przy użyciu usługi user@gmail.com LinkedIn lub nowszej w user@gmail.com przypadku usługi Google, zostanie wyświetlona strona błędu z informacją o tym, że użytkownik już istnieje.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. Subskrybuj.Subscribe.

    Wybierz kartę produkty . Następnie wybierz pozycję autoryzacja i Subskrybuj.Select the Products tab. Then, select Authorization and subscribe.

    Karta produkty w portalu Video Indexer Developer

    Uwaga

    Nowi użytkownicy automatycznie subskrybują autoryzację.New users are automatically subscribed to Authorization.

    Po zasubskrybowaniu możesz zobaczyć swoją subskrypcję oraz klucze podstawowe i pomocnicze.Once you subscribe, you can see your subscription and your primary and secondary keys. Te klucze należy chronić.The keys should be protected. Powinno się ich używać tylko w kodzie serwera.The keys should only be used by your server code. Nie powinny być dostępne po stronie klienta (. js,. html itp.).They shouldn't be available on the client side (.js, .html, and so on).

    Subskrypcja i klucze w portalu Video Indexer Developer

Porada

Usługa Video Indexer może używać klucza pojedynczej subskrypcji do łączenia się z wieloma kontami usługi Video Indexer.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. Te konta usługi Video Indexer można następnie połączyć z różnymi kontami usługi Media Services.You can then link these Video Indexer accounts to different Media Services accounts.

Uzyskiwanie tokenu dostępu przy użyciu interfejsu API autoryzacjiObtain access token using the Authorization API

Po zasubskrybowaniu interfejsu API autoryzacji można uzyskać tokeny dostępu.Once you subscribe to the Authorization API, you can obtain access tokens. Te tokeny dostępu są używane do uwierzytelniania w interfejsie API operacji.These access tokens are used to authenticate against the Operations API.

Każde wywołanie interfejsu API operacji powinno być skojarzone z tokenem dostępu zgodnym z zakresem autoryzacji wywołania.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Poziom użytkownika: tokeny dostępu na poziomie użytkownika umożliwiają wykonywanie operacji na poziomie użytkownika .User level: User level access tokens let you perform operations on the user level. Na przykład uzyskiwanie informacji o skojarzonych kontach.For example, get associated accounts.
  • Poziom konta: tokeny dostępu na poziomie konta umożliwiają wykonywanie operacji na poziomie konta lub wideo .Account level: Account level access tokens let you perform operations on the account level or the video level. Na przykład Przekaż wideo, Wyświetl wszystkie filmy wideo, Uzyskaj szczegółowe informacje wideo i tak dalej.For example, upload video, list all videos, get video insights, and so on.
  • Poziom wideo: tokeny dostępu na poziomie wideo umożliwiają wykonywanie operacji na konkretnym filmie wideo.Video level: Video level access tokens let you perform operations on a specific video. Na przykład Uzyskaj szczegółowe informacje wideo, pliki do pobrania, Pobierz widżety i tak dalej.For example, get video insights, download captions, get widgets, and so on.

Możesz kontrolować, czy te tokeny są tylko do odczytu, czy też zezwalają na edycję, określając AllowEdit = true/false.You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

W przypadku większości scenariuszy serwer-serwer prawdopodobnie używasz tego samego tokenu konta , ponieważ obejmuje on operacje na kontach i operacje wideo .For most server-to-server scenarios, you'll probably use the same account token since it covers both account operations and video operations. Jeśli jednak planujesz nawiązanie połączeń po stronie klienta z Video Indexer (na przykład z poziomu języka JavaScript), użyj tokenu dostępu wideo , aby uniemożliwić klientom uzyskiwanie dostępu do całego konta.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. Jest to również powód, aby podczas osadzania Video Indexer kod klienta na kliencie (na przykład za pomocą widżetu Get Insights lub uzyskać Widżet odtwarzacza), należy podać token dostępu wideo .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.

Aby ułatwić sprawę, można uzyskać informacje o kontach za pomocą pozycji Authorization API (Interfejs API autoryzacji) > GetAccounts (Pobierz konta) bez wcześniejszego pobierania tokenu użytkownika.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. Można również zażądać informacji o kontach z ważnymi tokenami, co umożliwia pominięcie dodatkowego wywołania w celu pobrania tokenu konta.You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

Tokeny dostępu wygasają po godzinie.Access tokens expire after 1 hour. Przed skorzystaniem z interfejsu API operacji upewnij się, że token dostępu jest ważny.Make sure your access token is valid before using the Operations API. Jeśli wygaśnie, wywołaj ponownie interfejs API autoryzacji, aby uzyskać nowy token dostępu.If it expires, call the Authorization API again to get a new access token.

Możesz rozpocząć Integrowanie z interfejsem API.You're ready to start integrating with the API. Zapoznaj się ze szczegółowymi opisami poszczególnych interfejsów API REST usługi Video Indexer.Find the detailed description of each Video Indexer REST API.

Identyfikator kontaAccount ID

Identyfikator konta to parametr wymagany we wszystkich wywołaniach interfejsu API operacji.The Account ID parameter is required in all operational API calls. Identyfikator konta jest identyfikatorem GUID, który można uzyskać w jeden z następujących sposobów:Account ID is a GUID that can be obtained in one of the following ways:

  • Uzyskiwanie identyfikatora konta za pomocą witryny internetowej usługi Video Indexer:Use the Video Indexer website to get the Account ID:

    1. Przejdź do witryny internetowej Video Indexer i zaloguj się.Browse to the Video Indexer website and sign in.

    2. Przejdź do strony Settings (Ustawienia).Browse to the Settings page.

    3. Skopiuj identyfikator konta.Copy the account ID.

      Ustawienia Video Indexer i identyfikator konta

  • Uzyskiwanie identyfikatora konta za pomocą portalu dla deweloperów usługi Video Indexer.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Użyj interfejsu API uzyskiwania konta .Use the Get account API.

    Porada

    Tokeny dostępu dla kont możesz wygenerować, definiując atrybutgenerateAccessTokens=true.You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • Pobierz identyfikator konta z adresu URL strony odtwarzacza na swoim koncie.Get the account ID from the URL of a player page in your account.

    Podczas odtwarzania pliku wideo identyfikator jest podany po sekcji accounts i przed sekcją 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/
    

ZaleceniaRecommendations

W tej sekcji przedstawiono kilka zaleceń dotyczących korzystania z interfejsu API usługi Video Indexer.This section lists some recommendations when using Video Indexer API.

  • Jeśli planujesz przekazać wideo, zaleca się umieszczenie pliku w pewnej lokalizacji w sieci publicznej (na przykład w usłudze OneDrive).If you're planning to upload a video, it's recommended to place the file in some public network location (for example, OneDrive). Uzyskaj link do pliku wideo, a następnie podaj ten adres URL jako parametr przekazywania pliku.Get the link to the video and provide the URL as the upload file param.

    Adres URL przekazywany do usługi Video Indexer musi wskazywać plik multimedialny (audio lub wideo).The URL provided to Video Indexer must point to a media (audio or video) file. Niektóre linki generowane przez usługę OneDrive prowadzą do zawierających te pliki stron HTML.Some of the links generated by OneDrive are for an HTML page that contains the file. Łatwą weryfikację adresu URL jest wklejenie go do przeglądarki — Jeśli plik rozpocznie pobieranie, prawdopodobnie jest to dobry adres 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. Jeśli przeglądarka renderuje wizualizację, prawdopodobnie nie jest to link do pliku, ale do strony HTML.If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • Wywołanie dla konkretnego pliku wideo interfejsu API, który pobiera szczegółowe informacje o wideo, powoduje pobranie w zawartości odpowiedzi szczegółowych danych wyjściowych JSON.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. W tym temacie omówiono szczegółowo zwracane informacje JSON.See details about the returned JSON in this topic.

Przykład koduCode sample

W poniższym fragmencie kodu języka C# pokazano używanie wszystkich interfejsów API usługi Video Indexer razem.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);

Zobacz teżSee also

Następne krokiNext steps

  • Badanie szczegółów wyjściowego JSONExamine details of the output JSON
  • Zapoznaj się z przykładowym kodem , który demonstruje istotny aspekt przekazywania i indeksowania wideo.Check out the sample code that demonstrates important aspect of uploading and indexing a video. Po będzie kodu zawarto informacje na temat korzystania z naszego interfejsu API na potrzeby podstawowych funkcji.Following the code wil give you a good idea of how to use our API for basic functionalities. Zapoznaj się z komentarzami wbudowanymi i zwróć uwagę na nasze wskazówki dotyczące najlepszych rozwiązań.Make sure to read the inline comments and notice our best practices advices.