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

注意

Video Indexer V1 API は 2018 年 8 月 1 日に非推奨になりました。The Video Indexer V1 API was deprecated on August 1st, 2018. 今後は Video Indexer v2 API を使用してください。You should now use the Video Indexer v2 API.
Video Indexer v2 API を使用して開発する場合は、こちらの手順を参照してください。To develop with Video Indexer v2 APIs, please refer to the instructions found here.

Video Indexer は、Microsoft が提供するさまざまなオーディオおよびビデオの人工知能 (AI) テクノロジが 1 つに統合されたサービスです。このサービスを利用すると、開発がより簡単になります。Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft in 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 platform. この API を使用すると、ファイルをアップロードし、詳細なビデオの分析情報を取得し、アプリケーションに埋め込む分析情報とプレーヤー ウィジェットの URL を取得するなどのタスクを実行できます。You can use the API to upload your files, get detailed video insights, get URLs of insight and player widgets in order to embed them into your application, and other tasks.

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 are not limited by the quota). 無料試用アカウントで Video Indexer 使用すると、Web サイト ユーザーは最大 600 分間の無料インデックス作成、API ユーザーは最大 2,400 分間の無料インデックス作成を利用できます。With 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 paid option, you create a Video Indexer account that is connected to your Azure subscription and a 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 へのサインアップ時と同じプロバイダーを使用する必要があります。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 E-Mail. ユーザーが user@gmail.com を使用して LinkedIn にサインインした後に、user@gmail.com を使用して Google にサインインしようとすると、ユーザーは既に存在しているというエラー ページが表示されます。If a user tries to sign-in with user@gmail.com for LinkedIn and after that with user@gmail.com for Google the later will display an error page, saying the user already exist.
  2. サブスクライブします。Subscribe.

    [製品] タブを選択します。次に、[承認] を選択し、サブスクライブします。Select the Products tab. Then, select Authorization and subscribe.

    サインアップ

    注意

    新しいユーザーは自動的に Authorization にサブスクライブされます。New users are automatically subscribed to Authorization.

    サブスクライブすると、サブスクリプション、プライマリ キー、セカンダリ キーが表示されます。Once you subscribe, you will be able to 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 should not be available on the client side (.js, .html, etc.).

    サインアップ

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

Authorization API にサブスクライブすると、アクセス トークンを取得できるようになります。Once you subscribed to the Authorization API, you will be able to 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, etc.
  • ビデオ レベル - ビデオ レベルのアクセス トークンを使用すると、特定のビデオに対して操作を実行できます。Video level – video level access tokens let you perform operations on a specific video. たとえば、ビデオの分析情報、キャプションのダウンロード、ウィジェットの取得などです。For example, get video insights, download captions, get widgets, etc.

allowEdit=true/false を指定することで、これらのトークンを読み取り専用にするか編集を許可するかを制御できます。You can control whether these tokens are readonly or they allow editing by specifying allowEdit=true/false.

アカウント操作とビデオ操作の両方がカバーされるので、ほとんどのサーバー間シナリオにおそらく同じアカウント トークンを使用します。For most server-to-server scenarios, you will probably use the same account token since it covers both account operations and video operations. ただし、クライアント側 (JavaScript など) から Video Indexer を呼び出す予定がある場合は、クライアントがアカウント全体へのアクセス権を取得できないように、ビデオ アクセス トークンを使用することもあります。However, if you are 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 is also the reason that when embedding VideoIndexer 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 expires, call the Authorization API again to get a new access token.

これで API との統合を開始する準備が整いました。You are ready to start integrating with the API. 各 Video Indexer REST API の詳細な説明を参照してください。Find the detailed description of each Video Indexer REST API.

LocationLocation

すべての操作 API には Location パラメーターが必要です。このパラメーターは、呼び出しがルーティングされ、アカウントが作成されたリージョンを示します。All operation APIs require a Location parameter, which indicates the region to which the call should be routed and in which the account was created.

次の表で説明する値が適用されます。The values described in the following table apply. パラメーター値は、API を使用するときに渡す値です。The Param value is the value you pass when using the API.

名前Name パラメーター値Param value 説明Description
試用版Trial 試用trial 試用アカウントに使用されます。Used for trial accounts.
米国西部West US westus2westus2 Azure 米国西部 2 リージョンに使用されます。Used for the Azure West US 2 region.
北ヨーロッパNorth Europe northeuropenortheurope Azure 北ヨーロッパ リージョンに使用されます。Used for the Azure North Europe region.
東アジアEast Asia eastasiaeastasia Azure 東アジア リージョンに使用されます。Used for the Azure East Asia region.

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.

      Account ID

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

    Get accounts API を使用します。Use the Get accounts 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 are planning to upload a video, it is 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 would be 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 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";
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);

次の手順Next steps

出力 JSON の詳細を調べるExamine details of the output JSON.

Video Indexer の概要Video Indexer overview