サポート問い合わせ先| システムステータス
ページコンテンツ

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

    このトピックでは、人気のあるInsomniaHTTPクライアントをセットアップしてBrightcove RESTful APIにリクエストを送信する方法を学習します。

    はじめに

    プラットフォーム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にも使用できます。

    Set Header in Insomnia
    Insomniaヘッダーを設定する

    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リクエストを作成するため、資格情報には少なくとも次の権限が必要です。

    • VideoRead/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
      OpenAPI仕様をダウンロードする

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

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

    環境に変数を追加する

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

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

    認証を設定する

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

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

    リクエストする

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

    1. これはGETリクエストなので、あとはSendをクリックするだけです。
    2. レスポンスエリアにJSONレスポンスが表示されるのが確認できるはずです。
      API Response
      API レスポンス
    3. Queryパラメータを使用することで、異なる動画セットを取得できることに注意してください。リクエストのQueryタブをクリックすると、Insomniaが、OpenAPI仕様に基づいたパラメータを設定していることがわかります。使いたいパラメータにチェックを入れて、値を設定するだけです。
      Query Params
      クエリパラメータ

    POSTリクエストの送信

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

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

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

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

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

    まとめ

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


    ページの最終更新日17 Feb 2023