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

このトピックでは、Brightcove RESTful API にリクエストを行うための一般的な Insomnia HTTP クライアントをセットアップする方法について説明します。

はじめに

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

Insomnia のインストール

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

認証

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

Set Header in Insomnia
Set Header in Insomnia

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

Playback API
  BCOV-Policy: YOUR_POLICY_KEY
Live API
  X-API-KEY: YOUR_API_KEY
Zencoder API
  Zencoder-Api-Key: YOUR_API_KEY

クライアント認証情報の取得

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

  • Videos: Read/Write

必要なだけ権限を追加して、より広範囲の API リクエストに使用できる資格情報を取得できます。また、必要に応じて、複数のアカウントで機能する認証情報を取得できることにも注意してください。

Insomniaの使用

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

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

CMS API の OpenAPI 仕様を取得する

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

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

  1. Insomnia アプリを起動します。
  2. Insomnia の横のドロップダウンをクリックし、Import/Exportを選択します。
    Import/Export
    Import/Export
  3. 開いたダイアログで、Import Data をクリックし、From File を選択します。
    Import Data from File
    Import Data from File
  4. ダウンロードした openapi.yaml ファイルを選択し、データを現在のワークスペースにインポートするか、新しいワークスペースを作成するかを選択します。どちらでも機能しますが、API ごとに新しいワークスペースを作成することをお勧めします。
    Create New Workspace
    Create New Workspace
  5. 次に、データを Reuqest Collection としてインポートするか、Design Document としてインポートするかを尋ねられます。Request Collection を選択してください。
    Import as Request Collection
    Import as Request Collection
  6. データがインポートされたことを確認するダイアログが表示されます。
  7. 左上隅の Dashboard をクリックしてワークスペースを表示します。新しいワークスペースを作成した場合は、適切な名前で表示されます。
    CMS API Workspace
    CMS API Workspace
  8. ワークスペースをクリックして開きます。
  9. CMS API のさまざまなリクエストのグループが含まれるフォルダーのリストと、新しい OpenAPI 環境が表示されます。
    CMS API Requests and Environment
    CMS API Requests and Environment

環境に変数を追加する

これはオプションの手順ですが、後でリクエストの認証設定をするのが簡単になります。

  1. OpenAPI env ドロップダウン メニューをクリックし、Manage Environments を選択します。
    Manage Environments
    Manage Environments
  2. Insomnia が OpenAPI 仕様から作成した環境変数が JSON 形式で表示されます。
    Environment Variables
    Environment Variables
  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 は次のようになります。
    Environment Variables Added
    Environment Variables Added
  5. 右下隅の Done をクリックしてダイアログを終了します。

認証の設定

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

  1. Videos フォルダーをクリックし、Get Videos を取得します。
    New Request
    New Request
  2. リクエストの URL には既に 2 つの変数が含まれていることに注意してください。これらをクリックすると、その値を確認 (および変更) できます。 base_url は Insomnia によって OpenAPI 仕様から自動的に生成されます。account_id をクリックすると、その値が前のセクションで環境変数として入力した値と一致することがわかります。
  3. Auth タブをクリックし、Auth ドロップダウン メニューをクリックして、OAuth 2.0 を選択します。
    Select Auth Type
    Select Auth Type
  4. Grant Type ドロップダウンをクリックし、Client Credentials を選択します。
    Select Grant Type
    Select Grant Type
  5. Access Token URL フィールドで、"access_token_url" と入力し始めます。- オートコンプリート メニューが表示され、 access_token_url 環境変数を選択します。
    Autocomplete for Variables
    Autocomplete for Variables
  6. 前の手順を繰り返して、Client ID と Client Secret フィールドに client_id 変数と client_secret 変数を入力します。
    Auth Variables
    Auth Variables
  7. 下にスクロールして Fetch Token ボタンを表示し、それをクリックします。 Access Token フィールドにトークンが入力されていることを確認して下さい。
    Access Token
    Access Token
  8. Fetch Tokens をクリックして、これが機能することを確認して下さい。次のような応答が表示されるはずです。
    Access Token
    Access Token
  9. Header タブに移動し、Authorization ヘッダーを削除します (セットアップしたばかりの Authorization によってヘッドが処理されますが、これにより Authorization ヘッダーが壊れます)。
    Remove Authorization Header
    Remove Authorization Header

リクエストする

これで、Get Videos リクエストを行う準備が整いました。

  1. これは GET リクエストなので、Send をクリックするだけです。
  2. JSON レスポンスが Response 領域に表示されるはずです。
    API Response
    API Response
  3. Query パラメーターを使用すると、さまざまなビデオのセットを取得することができます。リクエストの Query タブをクリックすると、Insomnia が OpenAPI 仕様に基づいてリクエストを設定したことがわかります。使用するパラメータを確認し、値を設定して下さい。
    Query Params
    Query Params

POST リクエストの送信

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

  1. 上記の 認証のセットアップ セクションのすべての手順を繰り返して、この新しいリクエストの認証を設定します。
  2. このリクエストにはリクエスト本文が必要なので、JSON タブをクリックし、次の JSON コードを入力して null を置き換えます。 
    {
	"name": "Insomnia Test"
}
    Request Body
    Request Body
  3. Send をクリックすると、レスポンスで新しいビデオ オブジェクトが返されることがわかります。

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

Insomnia のもう 1 つの優れた機能は、さまざまな言語でリクエストを行うためのコードを生成することです。

  1. リクエストのドロップダウン メニューにカーソルを合わせてクリックします。
    Request Dropdown Menu
    Request Dropdown Menu
  2. メニューから Generate Code を選択します。
    Select Generate Code
    Select Generate Code
  3. 表示される Generate Client Code ダイアログで、コードに使用する言語を選択します。
    Select the Language
    Select the Language
  4. 多くの言語では、作成しているアプリの種類により適した言語を選択できます。
    Select Code Variant
    Select Code Variant
  5. コードをクリップボードにコピーするための便利なボタンもあります。
    View and Copy Code
    View and Copy Code

終わりに

これで、Insomnia を使用して Brightcove API にリクエストを行う基本を理解できました。無料の Insomnia アカウントをチーム アカウントにアップグレードすることを選択した場合は、すべてのリクエストと環境を同期し、他のチーム メンバーと共有することもできることに注意してください。