チュートリアル:Video Indexer API の使用Tutorial: Use the Video Indexer API

Video Indexer は、Microsoft が提供するさまざまなオーディオおよびビデオの人工知能 (AI) テクノロジが 1 つに統合されたサービスです。このサービスを利用すると、開発がより簡単になります。Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. API は、開発者がクラウド プラットフォームの規模、世界的な展開、可用性、信頼性を気にすることなく、Media 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.

Video Indexer アカウントを作成する場合、無料試用アカウント (一定分数の無料インデックス作成を利用可能) または有料オプション (クォータによる制限がありません) を選択できます。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). 無料試用アカウントで Video Indexer を使用すると、Web サイト ユーザーは最大 600 分間の無料インデックス作成、API ユーザーは最大 2,400 分間の無料インデックス作成を利用できます。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 Media Services アカウントに接続される Video Indexer アカウントを作成します。With a paid option, you create a Video Indexer account that's connected to your Azure subscription and an Azure Media Services account. Azure Media Services アカウント関連の料金と同様に、インデックス作成時間 (分単位) の料金がかかります。You pay for minutes indexed as well as the Azure Media Services account related charges.

この記事では、開発者が Video Indexer API を利用する方法について説明します。This article shows how the developers can take advantage of the Video Indexer API.

API にサブスクライブするSubscribe to the API

  1. Video Indexer 開発者ポータルにサインインします。Sign in to Video Indexer Developer Portal.

    Video Indexer 開発者ポータルにサインインする

    重要

    • Video Indexer へのサインアップ時と同じプロバイダーを使用する必要があります。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.
    • 1 つのメール アドレスで有効にすることができるアカウントは 1 つのみです。There can be only one active account per email. ユーザーが user@gmail.com を使用して LinkedIn にサインインし、後から user@gmail.com を使用して Google にサインインしようとすると、ユーザーは既に存在しているというエラー ページが表示されます。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.

    Video Indexer 開発者ポータルの [製品] タブ

    注意

    新しいユーザーは自動的に Authorization にサブスクライブされます。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 開発者ポータルでのサブスクリプションとキー

ヒント

Video Indexer ユーザーは、単一のサブスクリプション キーを使用して複数の Video Indexer アカウントに接続することができます。Video Indexer user can use a single subscription key to connect to multiple Video Indexer accounts. さらに、それらの Video Indexer アカウントを異なる Media Services アカウントにリンクさせることができます。You can then link these Video Indexer accounts to different Media Services accounts.

Authorization API を使用してアクセス トークンを取得するObtain access token using the Authorization API

Authorization API にサブスクライブしたら、アクセス トークンを取得できます。Once you subscribe to the Authorization API, you can obtain access tokens. これらのアクセス トークンは、Operations API の認証を受けるために使用されます。These access tokens are used to authenticate against the Operations API.

Operations 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 など) から Video Indexer を呼び出す予定がある場合は、クライアントがアカウント全体へのアクセス権を取得できないように、ビデオ アクセス トークンを使用することもあります。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. また、(たとえば、Get Insights ウィジェットまたは Get Player ウィジェットを使用して) 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.

わかりやすくするために、ユーザー トークンを最初に取得せずに、Authorization 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. Operations API を使用する前に、アクセス トークンが有効であることを確認してください。Make sure your access token is valid before using the Operations API. 期限切れの場合は、もう一度 Authorization 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. 各 Video Indexer REST API の詳細な説明を参照してください。Find the detailed description of each Video Indexer REST API.

Account IDAccount ID

アカウント ID パラメーターは、すべての操作 API 呼び出しに必要です。The Account ID parameter is required in all operational API calls. アカウント ID は、次のいずれかの方法で取得できる GUID です。Account ID is a GUID that can be obtained in one of the following ways:

  • Video Indexer Web サイトを使用して、アカウント ID を取得します。Use the Video Indexer website to get the Account ID:

    1. Video Indexer Web サイトに移動してサインインします。Browse to the Video Indexer website and sign in.

    2. [設定] ページを表示します。Browse to the Settings page.

    3. アカウント ID をコピーします。Copy the account ID.

      Video Indexer の設定とアカウント ID

  • Video Indexer 開発者ポータルを使用して、プログラムからアカウント ID を取得します。Use Video Indexer Developer Portal to programmatically get the Account ID.

    Get account API を使用します。Use the Get account API.

    ヒント

    generateAccessTokens=true を定義することで、アカウントのアクセス トークンを生成できます。You can generate access tokens for the accounts by defining generateAccessTokens=true.

  • アカウントのプレーヤー ページの URL からアカウント ID を取得します。Get the account ID from the URL of a player page in your account.

    ビデオを見ると、accounts セクションの後と videos セクションの前に ID が表示されます。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/
    

RecommendationsRecommendations

このセクションでは、Video Indexer 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.

    Video Indexer に指定する 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# コード スニペットは、すべての Video Indexer 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.