APIリクエストにInsomniaを使用する

はじめに

プラットフォームAPIドキュメントの多くの例で使用されているcurlステートメントとコマンドラインは、難しくて威圧的であると感じる人もいます。このような場合、Brightcove API のほとんどを含む REST ベースのサービスに HTTP リクエストを送信するためのツールが多数用意されています。このドキュメントでは、人気のあるツールの1つであるInsomniaアプリの使用方法を説明します。

Insomniaのインストール

https://insomnia.restからInsomniaを入手して下さい。Insomnia は、Mac、Linux、またはWindowsシステムにインストールすることができます。

認証

Insomnia は、BrightcoveのRESTfull APIへのリクエストに使用できます。ほとんどのAPIは認証にOAuth2を使用しており、このドキュメントの後半でInsomniaでそれを設定する方法を説明します。一方、適切なヘッダーを設定するだけで、OAuthを使用しないAPIにも使用できます。

Oauth2以外の認証方法を使用したリクエストのヘッダーは次のようになります。

Playback API

  BCOV-Policy: YOUR_POLICY_KEY

ライブAPI

  X-API-KEY: YOUR_API_KEY

Zencoder API

  Zencoder-Api-Key: YOUR_API_KEY

クライアント認証情報を取得する

大部分のBrightcove APIを使用するには、使用するアカウントとAPIのクライアント認証情報が必要です。 「API 認証資格情報の管理」の説明に従って、Studioでクライアント認証情報を取得します。以下の手順では、Insomniaを使用して CMS APIリクエストを作成するため、資格情報には少なくとも次の権限が必要です。

• Video：Read/Write

より広い範囲の API リクエストに使用できる認証情報を取得するために、好きなだけ追加のパーミッションを追加することができます。また、複数のアカウントで使用できる認証情報を取得することもできます。

Insomniaの使用

クライアントの認証情報を取得したら、Insomniaを使い始める準備ができています。CMS APIのOpenAPI仕様をインポートし、Insomnia で多くのセットアップ作業が行われます。以下の手順では、Insomniaを使っていくつかの CMS API リクエストを作成する手順を説明します。

CMS APIコレクションのInsomniaのセットアップ

CMS APIのOpenAPI仕様を取得します

1. CMS APIリファレンスを開きます。
2. ダウンロードボタンをクリックして、openapi.yamlファイルを再び見つけられる場所に保存して下さい：

   

OpenAPI仕様をInsomniaにインポートします

1. Insomniaアプリを起動します。
2. Insomniaの横にあるドロップダウンをクリックし、Import/Exportを選択します：

   

3. 開いたダイアログで、Import DataからFrom Fileをクリックします：

   

4. ダウンロードしたopenapi.yamlファイルを選択し、現在のワークスペースにインポートするか、新しいワークスペースを作成するかを選択します。どちらでも機能しますが、各APIごとに新しいワークスペースを作成することをお勧めします。

   

5. 次に、データをリクエストコレクションとしてインポートするかデザインドキュメントとしてインポートするかを尋ねられます。Request Collectionを選択します：

   

6. データがインポートされたことを確認するダイアログが表示されます。
7. 左上にあるDashboardをクリックすると、ワークスペースが表示されます。新しいワークスペースを作成した場合は、適切な名前で表示されます。

   

8. ワークスペースをクリックして開きます。
9. CMS APIに対するさまざまなリクエストのグループと、新しいOpenAPI環境を含むフォルダーのリストが表示されます。

   

環境に変数を追加する

これはオプションの手順ですが、後でリクエストの認証設定を簡略化することができます。

1. OpenAPI envのドロップダウンメニューをクリックし、Manage Environmentsを選択します：

   

2. Insomnia がOpenAPIの仕様から作成した環境変数がJSON形式で表示されます：

   

3. これらの追加変数をJSONに追加します (client_idとclient_secret については、上記のクライアントの資格情報を取得するを参照して下さい）：
   • "account_id"： " your_account_id「」
   • "client_id"： " your_client_id「」
   • "client_secret"： " your_client_secret「」
   • "access_token_url"： "https://oauth.brightcove.com/v4/access_token"
4. 終了すると、環境JSONは次のようになります。

   

5. 右下のDoneをクリックしてダイアログを終了します。

認証を設定する

これで、APIリクエストの認証を設定する準備が整いました。

1. Videoフォルダをクリックし、Get Videosを選択します：

   

2. リクエストのURLには既に2つの変数が含まれていることに注意してください。 base_urlはOpenAPI仕様からInsomniaが自動的に生成したものです。account_idをクリックすると、前のセクションで環境変数として入力した値と一致することがわかります。
3. >AuthタブとAuthドロップダウンメニューをクリックし、 OAuth 2.0を選択します：

   

4. Grant Typeドロップダウンをクリックし、Client Credentialsを選択します：

   

5. Access Token URLフィールドで、「access_token_url」と入力し始めます-オートコンプリートメニューが表示されますので、環境変数 access_token_urlを選択して下さい：

   

6. 前の手順を繰り返して、Client IDとClient Secretフィールドにclient_idとclient_secret変数を入力します：

   

7. 下にスクロールして、Fetch Tokenボタンをクリックしてクリックします。[Access Token]フィールドにトークンが入力されていることを確認します。

   

8. Fetch Tokenをクリックして、これが機能することを確認します。次のような応答が表示されます。

   

9. HeaderタブでAuthorizationヘッダーを削除して下さい（先程設定した認証でheadが処理され-これでheaderは壊れています）：

   

リクエストする

これでGet Videosのリクエストをする準備が整いました。

1. これはGETリクエストなので、あとはSendをクリックするだけです。
2. レスポンスエリアにJSONレスポンスが表示されるのが確認できるはずです。

   

3. Queryパラメータを使用することで、異なる動画セットを取得できることに注意してください。リクエストのQueryタブをクリックすると、Insomniaが、OpenAPI仕様に基づいたパラメータを設定していることがわかります。使いたいパラメータにチェックを入れて、値を設定するだけです。

   

POSTリクエストの送信

ここでは、いくつかのデータを含むPOSTリクエストを送信します。今回、CMS APIを使用して新しいビデオオブジェクトを作成します。VideoフォルダにあるCreate Videoリクエストを選択して開始します。

1. 上記の認証を設定セクションの全ての手順を繰り返して、この新しいリクエストの認証を設定します。
2. このリクエストにはリクエスト本文が必要なので、[JSON]タブをクリックし、このJSONコードを入力してnullを置き換えます：

   {
   	"name": "Insomnia Test"
   }

   

3. 送信をクリックすると、新しいビデオオブジェクトがレスポンスで表示されます。

コードジェネレーターの使用

Insomniaのもう一つの素晴らしい特徴は、様々な言語でリクエストを行うためのコードを生成するということです。

1. リクエストのドロップダウンメニューにカーソルを合わせます。

   

2. メニューからGenerate Codeを選択します：

   

3. Generate Client Codeダイアログが表示されたら、コードを作成する言語を選択します。

   

4. 多くの言語では、作成するアプリの種類に適した、選択可能なバリアントもあります。

   

5. コードをクリップボードにコピーするための便利なボタンもあります。

   

まとめ

Insomnia を使用してBrightcove APIにリクエストを行うための基本的な方法はご理解頂けたと思います。無料のInsomniaアカウントをチームアカウントにアップグレードすると、全てのリクエストと環境を同期して、他のチームメンバーと共有することもできますのでご注意ください。