Tutorial: Verwenden der Video Indexer-APITutorial: Use the Video Indexer API

In Video Indexer ist unterschiedliche KI-Technologie (Künstliche Intelligenz) für Audio- und Videodaten zusammengefasst, und der Dienst wird von Microsoft als integrierter Dienst angeboten, um die Entwicklung zu vereinfachen.Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. Die APIs sind so konzipiert, dass sich Entwickler auf die Nutzung der KI-Technologie für Medien konzentrieren können, ohne sich um Dinge wie die Skalierung, globale Reichweite, Verfügbarkeit und Zuverlässigkeit von Cloudplattformen kümmern zu müssen.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. Sie können die API verwenden, um Ihre Dateien hochzuladen, ausführliche Videoinformationen zu erhalten, URLs von einbettbaren Erkenntnisse- und Player-Widgets abzurufen, usw.You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

Beim Erstellen eines Video Indexer-Kontos können Sie ein kostenloses Testkonto (mit einer bestimmten Anzahl von kostenlosen Indizierungsminuten) oder eine kostenpflichtige Option wählen (ohne Einschränkung durch eine Kontingentvorgabe).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). Bei einer kostenlosen Testversion stellt Video Indexer bis zu 600 Minuten an kostenloser Indizierungszeit für Websitebenutzer und bis zu 2400 Minuten an kostenloser Indizierungszeit für API-Benutzer bereit.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. Bei einer kostenpflichtigen Option erstellen Sie ein Video Indexer-Konto, das mit Ihrem Azure-Abonnement und einem Azure Media Services-Konto verbunden ist.With a paid option, you create a Video Indexer account that's connected to your Azure subscription and an Azure Media Services account. Die Indizierungszeit wird minutenweise abgerechnet. Außerdem fallen Gebühren für das Azure Media Services-Konto an.You pay for minutes indexed as well as the Azure Media Services account related charges.

In diesem Artikel wird veranschaulicht, wie Entwickler die Video Indexer-API nutzen können.This article shows how the developers can take advantage of the Video Indexer API.

Abonnieren der APISubscribe to the API

  1. Melden Sie sich beim Portal für Video Indexer-Entwickler an.Sign in to Video Indexer Developer Portal.

    Beim Video Indexer-Entwicklerportal anmelden

    Wichtig

    • Sie müssen denselben Anbieter verwenden, den Sie beim Anmelden für Video Indexer genutzt haben.You must use the same provider you used when you signed up for Video Indexer.
    • Persönliche Google- und Microsoft-Konten (Outlook/Live) können nur für Testkonten verwendet werden.Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. Für Konten, die über eine Verbindung mit Azure verfügen, ist Azure AD erforderlich.Accounts connected to Azure require Azure AD.
    • Pro E-Mail-Adresse kann nur ein aktives Konto vorhanden sein.There can be only one active account per email. Wenn ein Benutzer versucht, sich mit user@gmail.com für LinkedIn anzumelden, und später user@gmail.com auch für Google verwendet, wird für die zweite Anmeldung eine Fehlerseite mit dem Hinweis angezeigt, dass der Benutzer bereits vorhanden ist.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. Führen Sie den Schritt zum Abonnieren aus.Subscribe.

    Wählen Sie die Registerkarte Produkte. Wählen Sie anschließend „Authorization“ (Autorisierung), und führen Sie den Vorgang für die Einrichtung des Abonnements durch.Select the Products tab. Then, select Authorization and subscribe.

    Registerkarte „Products“ im Video Indexer-Entwicklerportal

    Hinweis

    Für neue Benutzer wird das Abonnement der Autorisierung automatisch eingerichtet.New users are automatically subscribed to Authorization.

    Nachdem das Abonnement eingerichtet wurde, werden Ihr Abonnement und Ihre Primär- und Sekundärschlüssel angezeigt.Once you subscribe, you can see your subscription and your primary and secondary keys. Die Schlüssel sollten geschützt werden.The keys should be protected. Die Schlüssel sollten nur von Ihrem Servercode verwendet werden.The keys should only be used by your server code. Sie sollten nicht auf Clientseite (.js, .html usw.) verfügbar sein.They shouldn't be available on the client side (.js, .html, and so on).

    Abonnement und Schlüssel im Video Indexer-Entwicklerportal

Tipp

Video Indexer-Benutzer können einen einzelnen Abonnementschlüssel verwenden, um eine Verbindung mit mehreren Video Indexer-Konten herzustellen.Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. Sie können diese Video Indexer-Konten dann mit unterschiedlichen Media Services-Konten verknüpfen.You can then link these Video Indexer accounts to different Media Services accounts.

Abrufen von Zugriffstoken mit der Authorization-APIObtain access token using the Authorization API

Sobald Sie die Authorization-API abonniert haben, können Sie Zugriffstoken abrufen.Once you subscribe to the Authorization API, you can obtain access tokens. Diese Zugriffstoken werden zur Authentifizierung für die Operations-API verwendet.These access tokens are used to authenticate against the Operations API.

Jeder Aufruf der Operations-API sollte einem Zugriffstoken zugeordnet sein und mit dem Autorisierungsbereich des Aufrufs übereinstimmen.Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • Benutzerebene: Mit Zugriffstoken auf Benutzerebene können Sie Vorgänge auf der Benutzer-Ebene ausführen.User level: User level access tokens let you perform operations on the user level. Ein Beispiel hierfür ist das Abrufen von zugeordneten Konten.For example, get associated accounts.
  • Kontoebene: Mit Zugriffstoken auf Kontoebene können Sie Vorgänge auf der Konto-Ebene oder der Video-Ebene ausführen.Account level: Account level access tokens let you perform operations on the account level or the video level. Beispiele hierfür sind das Hochladen von Videos, Auflisten aller Videos, Abrufen von Videoerkenntnissen usw.For example, upload video, list all videos, get video insights, and so on.
  • Videoebene: Mit Zugriffstoken auf Videoebene können Sie Vorgänge für ein bestimmtes Video ausführen.Video level: Video level access tokens let you perform operations on a specific video. Beispiele hierfür sind das Abrufen von Videoinformationen, Herunterladen von Untertiteln, Abrufen von Widgets usw.For example, get video insights, download captions, get widgets, and so on.

Sie können durch Angeben von allowEdit=true/false steuern, ob diese Token schreibgeschützt sind oder bearbeitet werden können.You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

Für die meisten Server-zu-Server-Szenarien nutzen Sie voraussichtlich dasselbe Token vom Typ „Konto“ (account), da hiermit sowohl account-Vorgänge als auch video-Vorgänge abgedeckt sind.For most server-to-server scenarios, you'll probably use the same account token since it covers both account operations and video operations. Falls Sie planen, clientseitig Aufrufe von Video Indexer auszuführen (z. B. per JavaScript), sollten Sie aber ein video-Zugriffstoken verwenden, um zu verhindern, dass Clients Zugriff auf das gesamte Konto erhalten.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. Dies ist auch der Grund, warum Sie beim Einbetten von Video Indexer-Clientcode in Ihren Client (z. B. per Get Insights Widget (Insights-Widget abrufen) oder Get Player Widget (Player-Widget abrufen)) ein video-Zugriffstoken angeben müssen.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.

Zur Vereinfachung können Sie „Authorization-API“ > „GetAccounts“ verwenden, um Ihre Konten abzurufen, ohne dass Sie zuerst ein Benutzertoken beschaffen müssen.To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. Sie können auch darum bitten, dass Sie die Konten mit gültigen Token erhalten, um einen zusätzlichen Aufruf zum Abrufen eines Kontotokens zu sparen.You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

Zugriffstoken laufen nach einer Stunde ab.Access tokens expire after 1 hour. Stellen Sie sicher, dass Ihr Zugriffstoken gültig ist, bevor Sie die Operations-API verwenden.Make sure your access token is valid before using the Operations API. Wenn es abgelaufen ist, müssen Sie die Authorization-API erneut aufrufen, um ein neues Zugriffstoken zu erhalten.If it expires, call the Authorization API again to get a new access token.

Sie sind nun soweit, dass Sie mit dem Integrieren für die API beginnen können.You're ready to start integrating with the API. Lesen Sie sich die ausführliche Beschreibung zu den einzelnen Video Indexer-REST-APIs durch.Find the detailed description of each Video Indexer REST API.

Konto-IDAccount ID

Der Parameter für die Konto-ID (Account ID) ist in allen API-Aufrufen für Vorgänge erforderlich.The Account ID parameter is required in all operational API calls. Die Konto-ID ist eine GUID, die auf eine der folgenden Arten abgerufen werden kann:Account ID is a GUID that can be obtained in one of the following ways:

  • Rufen Sie auf der Video Indexer-Website die Konto-ID ab:Use the Video Indexer website to get the Account ID:

    1. Navigieren Sie zur Video Indexer-Website, und melden Sie sich an.Browse to the Video Indexer website and sign in.

    2. Navigieren Sie zur Seite Einstellungen.Browse to the Settings page.

    3. Kopieren Sie die Konto-ID.Copy the account ID.

      Einstellungen und Konto-ID für Video Indexer

  • Im Portal für Video Indexer-Entwickler können Sie die Konto-ID programmgesteuert abrufen.Use Video Indexer Developer Portal to programmatically get the Account ID.

    Verwenden Sie die API Get account (Konto abrufen).Use the Get account API.

    Tipp

    Sie können Zugriffstoken für die Konten generieren, indem Sie generateAccessTokens=true definieren.You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • Rufen Sie die Konto-ID aus der URL einer Playerseite in Ihrem Konto ab.Get the account ID from the URL of a player page in your account.

    Beim Wiedergeben eines Videos wird die ID nach dem Abschnitt accounts und vor dem Abschnitt videos angezeigt.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/
    

EmpfehlungenRecommendations

In diesem Abschnitt sind einige Empfehlungen für die Verwendung der Video Indexer-API aufgeführt.This section lists some recommendations when using Video Indexer API.

  • Wenn Sie planen, ein Video hochzuladen, wird empfohlen, die Datei in einem öffentlichen Netzwerkspeicherort abzulegen (z. B. OneDrive).If you're planning to upload a video, it's recommended to place the file in some public network location (for example, OneDrive). Rufen Sie den Link zum Video ab, und geben Sie die URL als Parameter für den Dateiupload an.Get the link to the video and provide the URL as the upload file param.

    Die für Video Indexer angegebene URL muss auf eine Mediendatei (Audio oder Video) verweisen.The URL provided to Video Indexer must point to a media (audio or video) file. Einige der Links, die von OneDrive generiert werden, sind für eine HTML-Seite bestimmt, die die Datei enthält.Some of the links generated by OneDrive are for an HTML page that contains the file. Eine einfache Möglichkeit zum Überprüfen der URL besteht darin, sie in einen Browser einzufügen: Wenn der Download der Datei beginnt, ist die URL mit hoher Wahrscheinlichkeit korrekt.An easy verification for the URL is to paste it into a browser—if the file starts downloading, it's likely a good URL. Falls im Browser eine Visualisierung gerendert wird, handelt es sich wahrscheinlich nicht um einen Link zu einer Datei, sondern zu einer HTML-Seite.If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • Wenn Sie die API aufrufen, mit der Videoinformationen für das angegebene Video abgerufen werden, erhalten Sie eine ausführliche JSON-Ausgabe als Inhalt der Antwort.When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. Lesen Sie die Details zum zurückgegebenen JSON-Code in diesem Thema.See details about the returned JSON in this topic.

CodebeispielCode sample

Mit dem folgenden C#-Codeausschnitt wird die Nutzung aller Video Indexer-APIs zusammen veranschaulicht.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);

Weitere InformationenSee also

Nächste SchritteNext steps

  • Untersuchen der Details der JSON-AusgabeExamine details of the output JSON
  • Sehen Sie sich den Beispielcode an, in dem wichtige Aspekte zum Hochladen und Indizieren eines Videos veranschaulicht werden.Check out the sample code that demonstrates important aspect of uploading and indexing a video. Wenn Sie sich an den Code halten, erhalten Sie eine gute Übersicht über die Verwendung unserer API für grundlegende Funktionen.Following the code wil give you a good idea of how to use our API for basic functionalities. Lesen Sie unbedingt die enthaltenen Kommentare, und beachten Sie unsere Hinweise zu bewährten Methoden.Make sure to read the inline comments and notice our best practices advices.