教學課程:使用影片索引器 APITutorial: Use the Video Indexer API

影片索引器會將 Microsoft 提供的各種音訊和視訊人工智慧 (AI) 技術合併成一個整合式服務,讓開發變得更簡單。Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. API 可讓開發人員將焦點放在使用媒體 AI 技術上,而不需擔心雲端平台的規模、全球觸達率、可用性和可靠性。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. 您可使用 API 來上傳檔案、取得詳細的影片見解、取得可內嵌見解和播放程式介面控件的 URL 等等。You can use the API to upload your files, get detailed video insights, get URLs of embeddable insight and player widgets, and more.

建立影片索引器帳戶時,您可以選擇免費試用帳戶 (您可取得特定的免費編製索引分鐘數) 或付費選項 (您不會受限於配額)。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). 使用免費試用時,影片索引器最多可為網站使用者提供 600 分鐘的免費編製索引,以及為 API 使用者提供 2400 分鐘的免費索引編製。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. 使用付費選項時,您建立的影片索引器帳戶會連線到您的 Azure 訂用帳戶和 Azure 媒體服務帳戶With a paid option, you create a Video Indexer account that's connected to your Azure subscription and an Azure Media Services account. 您需支付已編製索引的分鐘數,以及 Azure 媒體服務帳戶相關費用。You pay for minutes indexed as well as the Azure Media Services account related charges.

本文說明開發人員可以如何善用影片索引器 APIThis article shows how the developers can take advantage of the Video Indexer API.

訂閱 APISubscribe to the API

  1. 登入影片索引器開發人員入口網站Sign in to Video Indexer Developer Portal.

    登入影片索引器開發人員入口網站

    重要

    • 您必須使用註冊影片索引器時所使用的提供者。You must use the same provider you used when you signed up for Video Indexer.
    • 個人 Google 和 Microsoft (Outlook/Live) 帳戶僅能用於試用帳戶。Personal Google and Microsoft (Outlook/Live) accounts can only be used for trial accounts. 連線至 Azure 的帳戶需要 Azure AD。Accounts connected to Azure require Azure AD.
    • 每個電子郵件只能有一個使用中的帳戶。There can be only one active account per email. 如果使用者嘗試在使用 LinkedIn 的 user@gmail.com 登入後,然後使用 Google 的 user@gmail.com 登入,則系統會顯示錯誤頁面,表示使用者已存在。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. 訂閱。Subscribe.

    選取 [產品] 索引標籤。然後,選取授權並訂閱。Select the Products tab. Then, select Authorization and subscribe.

    影片索引器開發人員入口網站中的 [產品] 索引標籤

    注意

    系統會自動完成新使用者的授權訂閱。New users are automatically subscribed to Authorization.

    當您完成訂閱時,即可看到您的訂用帳戶和主要及次要金鑰。Once you subscribe, you can see your subscription and your primary and secondary keys. 應妥善保護金鑰。The keys should be protected. 這些金鑰應只供伺服器程式碼使用。The keys should only be used by your server code. 不應該用於用戶端 (.js、.html 等等)。They shouldn't be available on the client side (.js, .html, and so on).

    影片索引器開發人員入口網站中的訂用帳戶和金鑰

提示

影片索引器使用者可以使用單一訂用帳戶金鑰來連線到多個影片索引器帳戶。Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. 接著,您可以將這些影片索引器帳戶連結到不同媒體服務帳戶。You can then link these Video Indexer accounts to different Media Services accounts.

使用授權 API 取得存取權杖Obtain access token using the Authorization API

訂閱授權 API 後,您即可取得存取權杖。Once you subscribe to the Authorization API, you can obtain access tokens. 這些存取權杖可用來對作業 API 進行驗證。These access tokens are used to authenticate against the Operations API.

作業 API 的每次呼叫皆應與存取權杖相關聯,以符合呼叫的授權範圍。Each call to the Operations API should be associated with an access token, matching the authorization scope of the call.

  • 使用者層級:使用者層級的存取權杖可讓您在使用者層級上執行作業。User level: User level access tokens let you perform operations on the user level. 例如,取得相關聯的帳戶。For example, get associated accounts.
  • 帳戶層級:帳戶層級的存取權杖可讓您在帳戶層級或影片層級上執行作業。Account level: Account level access tokens let you perform operations on the account level or the video level. 例如,上傳影片、列出所有影片、取得影片見解等等。For example, upload video, list all videos, get video insights, and so on.
  • 影片層級:影片層級的存取權杖可讓您在特定影片上執行作業。Video level: Video level access tokens let you perform operations on a specific video. 例如,取得影片見解、下載字幕、取得介面控件等等。For example, get video insights, download captions, get widgets, and so on.

您可藉由指定 allowEdit=true/false 來控制這些權杖是唯讀還是可編輯。You can control whether these tokens are read-only or if they allow editing by specifying allowEdit=true/false.

針對大部分的伺服器對伺服器案例,您可能會使用相同的帳戶權杖,因為其同時涵蓋帳戶作業和影片作業。For most server-to-server scenarios, you'll probably use the same account token since it covers both account operations and video operations. 不過,如果您打算讓用戶端呼叫影片索引器 (例如,從 javascript),您可以使用影片存取權杖,以防止用戶端取得整個帳戶的存取權。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. 這也是為什麼當您將 VideoIndexer 用戶端程式碼內嵌到用戶端 (例如使用取得見解介面控件取得播放程式介面控件) 時,您必須提供影片存取權杖。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.

為了方便起見,您可以使用授權 API > GetAccounts 來取得您的帳戶,而不需先取得使用者權杖。To make things easier, you can use the Authorization API > GetAccounts to get your accounts without obtaining a user token first. 您也可以透過有效權杖來要求取得帳戶,以略過用於取得帳戶權杖的額外呼叫。You can also ask to get the accounts with valid tokens, enabling you to skip an additional call to get an account token.

存取權杖會在 1 小時後過期。Access tokens expire after 1 hour. 請先確定您的存取權杖有效,再使用作業 API。Make sure your access token is valid before using the Operations API. 如果過期,請再次呼叫授權 API 以取得新的存取權杖。If it expires, call the Authorization API again to get a new access token.

您已可以開始整合 API。You're ready to start integrating with the API. 請探索每個影片索引器 REST API 的詳細描述Find the detailed description of each Video Indexer REST API.

帳戶識別碼Account ID

帳戶識別碼參數是所有作業 API 呼叫的必要項目。The Account ID parameter is required in all operational API calls. 帳戶識別碼是 GUID,可使用下列其中一個方法取得:Account ID is a GUID that can be obtained in one of the following ways:

  • 使用影片索引器網站來取得帳戶識別碼:Use the Video Indexer website to get the Account ID:

    1. 瀏覽至影片索引子網站並登入。Browse to the Video Indexer website and sign in.

    2. 瀏覽至 [設定] 頁面。Browse to the Settings page.

    3. 複製帳戶識別碼。Copy the account ID.

      影片索引器設定和帳戶識別碼

  • 使用影片索引器開發人員入口網站,以程式設計方式取得帳戶識別碼。Use Video Indexer Developer Portal to programmatically get the Account ID.

    使用取得帳戶 API。Use the Get account API.

    提示

    您可以藉由定義 generateAccessTokens=true 來產生帳戶的存取權杖。You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • 從帳戶中的播放程式頁面 URL 取得帳戶識別碼。Get the account ID from the URL of a player page in your account.

    當您觀看影片時,識別碼會出現在 accounts 區段之後及 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/
    

建議Recommendations

本節會列出使用影片索引器 API 時的一些建議。This section lists some recommendations when using Video Indexer API.

  • 如果您打算上傳影片,建議您將檔案放在某個公用網路位置 (例如 OneDrive)。If you're planning to upload a video, it's recommended to place the file in some public network location (for example, OneDrive). 取得影片的連結,並將此 URL 作為上傳檔案參數。Get the link to the video and provide the URL as the upload file param.

    提供給影片索引器的 URL 必須指向媒體 (音訊或視訊) 檔案。The URL provided to Video Indexer must point to a media (audio or video) file. 有些 OneDrive 所產生的連結是包含檔案的 HTML 網頁。Some of the links generated by OneDrive are for an HTML page that contains the file. 驗證 URL 的簡單方式是將其貼到瀏覽器中,如果檔案開始下載,表示這可能是好的 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. 如果瀏覽器呈現一些視覺效果,則表示這可能不是檔案的連結,而是 HTML 網頁的連結。If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

  • 當您呼叫 API 以取得指定影片的影片深入解析時,取得的回應內容會是詳細的 JSON 輸出。When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. 請在本主題中參閱傳回的 JSON 詳細資料See details about the returned JSON in this topic.

程式碼範例Code sample

下列 C# 程式碼片段會示範一起使用所有影片索引器 API 的方式。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);

另請參閱See also

後續步驟Next steps

  • 查看輸出 JSON 的詳細資料Examine details of the output JSON
  • 查看範例程式碼,其示範上傳影片和編製其索引的重要層面。Check out the sample code that demonstrates important aspect of uploading and indexing a video. 遵循程式碼可讓您了解如何使用我們的 API 來執行基本功能。Following the code wil give you a good idea of how to use our API for basic functionalities. 請務必閱讀內嵌註解,並注意我們建議的最佳做法。Make sure to read the inline comments and notice our best practices advices.