このページの一部は機械翻訳されている場合があります。

Bridge ユーティリティ: Call API

Call API (API 呼び出し) モジュールを使用すると、任意の外部システムに呼びかけ、アクションを自動化できます。

ご利用可能なユーザー

プラン:

  • Bridge by Smartsheet

Call API ユーティリティを使用すると、Bridge の自動化ワークフロー全体で行うパブリック API 呼び出しを管理できます。このツールには 2 つの主要コンポーネントがあります: 

  • プロファイル: ワークフローを接続したいシステム API に関する情報を保持します。 

  • Make API Call モジュール は、プロファイルデータと、ユーザーが提供する特定の詳細を使用して、システム API へ API 呼び出しを行います。

    この設定を行うには、API とコーディングの知識が必要です。

Bridge ビルダーのヒント

プロファイルは、認証トークンやベース URL などの重要な情報が変更された場合に、ワークフローの変更を簡素化します。プロファイルを更新することで、そのプロファイルを呼び出すすべてのモジュールが最新のデータを取得し、呼び出しを行えるようになります。

Make API Call モジュール 

これはユーティリティ内の唯一のモジュールで、以下のフィールドが含まれています:

エンドポイント

このフィールドでは、実行したいアクションを指定します（たとえば、シートを並べ替える）。この値に、Bridge トリガーからのデータ参照を追加できます。静的データまたは動的データの設定方法の例を以下に示します:

  • 静的 ID 値 — このデータタイプの URL 形式は次のとおりです: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort。この URL でシート ID を指定する必要があるため、API 呼び出しでは常にその特定のシートが並べ替えられます。 
  • 動的実行ログ データ参照 — このデータの URL 形式は次のとおりです: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort。ただし、シート ID を追加する代わりに、実行ログからシートデータ参照を追加する必要があります。これは、Bridge ワークフローが変更によってトリガーされる場合や、複数のシートからデータを取り込む場合に便利です。このタイプの URL を使用すると、API 呼び出しによって、この URL で参照されている特定のシートが並べ替えられます。

メソッド

メソッドは、実行したい操作の種類を定義します。Make API Call モジュール内の各 API 呼び出しに対してメソッドを定義します。ほとんどの API は、特定の API エンドポイントに必要なメソッドを概説しています。たとえば Smartsheet では、以下のようなメソッドを使用します:

  • GET: シートから行を「取得」して、Bridge ワークフローにデータを取り込みます。
  • POST: 何かを作成します。たとえば、シートに行を追加します。
  • PUT: 何かを更新します。たとえば、シートの行を更新します。
  • DELETE: 何かを削除します。たとえば、シートの行を削除します。

ヘッダー

ヘッダーは、リクエストに必要な値であり、キーと値のペアです。通常は承認 (許可) を扱うために使用されます。たとえば、Smartsheet 呼び出しでは、値が Bearer [各自の API トークンを入力] に設定された「Authorization」という名前のキー ヘッダーがあります。

プロファイルは、システムへのすべての呼び出しに必要なヘッダーを設定できます。ワークフロー内で、Make API Call モジュールを使用すると、特定のアクションに対して追加のヘッダーを構成できます。 

フォーム パラメーター 

フォーム パラメーターは、「クエリ パラメーター」または「引数」とも呼ばれます。フォーム パラメーターは、リクエストで定義できる追加の項目です。Make API Call モジュールで設定します。

サンプルシナリオとして、Smartsheet 呼び出しでページングを適用し、応答にいくつかの項目を含めることが考えられます。たとえば、2 万行のレポートの最初のページのみを取得したい場合です。

HTTP リクエストの本文

本文には、送信する必要のある関連リクエストの詳細が含まれています。通常は JSON 形式です。

フォーム パラメーターを送信すると、本文データが上書きされます。

「シートの並び替え」API 呼び出しでは、本文は次のようになります: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}。上記の例の本文では、以下のいずれかの値タイプを使用できます:

  • シートの特定の列の静的な値。
  • 列 ID が表示される、動的な実行ログのデータ参照。 

リクエストの種類によっては、本文が必要ない場合があります。たとえば、GET 呼び出しには本文は必要ありません。

出力

応答した API が JSON オブジェクトを送り返すと、実行ログに保存されます。これにより、返されたデータをワークフローの後の部分で参照できます。

始めるために必要なもの

  • シート 
    • シート ID
    • 行で変更されたときに、Bridge ワークフローをトリガーする列
  • Bridge
    • Smartsheet の統合機能
    • Bridge ワークフロー トリガー: Smartsheet - [When Column Values are Changed (列の値が変更された場合)]
    • Bridge モジュール: ユーティリティ > API を呼び出す > API コールを作成する
  • Smartsheet API キー。

Bridge でこのワークフローを構築するには、Smartsheet 統合を認証します。 

ワークフローの構築中は、シート、Smartsheet API ドキュメント、Bridge ワークフローを 3 つの個別のタブで開いたままにします。これにより、構築プロセスの進め方が簡単になります。

ステップ 1: 基本的なワークフロー モデルを構築する

ワークフローに必要なすべてのモジュールを取得します。 

  1. Bridge で新しいワークフローを作成します。 
  2. ワークフロー ビルダーで、パネルを使用して Make API Call モジュールを追加します。
  3. ワークフローを保存します。

完了すると、ワークフローに以下のように表示されます: 

Make API Call workflow

ワークフローのトリガーを設定する

  1. 「Trigger (トリガー)」モジュールを選択します。
  2. 「Integrations (統合)」セクションで、「Integrations Page (統合ページ)」を選択します。

  3. 統合リストから Smartsheet を選択します。

    Bridge ロゴの下にある 「Connected (接続済み)」オプションを使用すると、そのワークスペースに対して認証された統合のみのリストを表示できます。

  4. 「Triggers (トリガー)」行を展開します。
  5. 新しいトリガーを作成するには、「Add to Triggers (トリガーに追加)」を選択します。
  6. 次のフィールドに入力します。
    • Trigger Name (トリガー名): トリガーのカスタム ラベルを作成します。
    • Sheet ID (シート ID): 並べ替えたいシートのシート ID を貼り付けます。
    • Event Type (イベント タイプ): 「When Column Values are Changed (列の値が変更された場合)」を選択します。 
    • Column Name or ID (列名または ID): 応答を作成したい Smartsheet の列名を入力します。たとえば、優先度が変更されるたびにシートの行を並べ替える場合は、優先度列の名前を入力します。
    • Select Workflow (ワークフローの選択): ドロップダウン リストから、作成した新しいワークフローを選択します。
  7. [保存] を選択します。
  8. トリガー情報で列 ID をコピーします。ワークフロー トリガーを保存すると、列 ID がトリガー情報で使用できるようになります。
  9. メモ帳や任意のワープロに貼り付けます。後のステップでこの列 ID が必要です。 
  10. ワークフローに戻ります。

API 呼び出しの詳細を取得する

このワークフローでは、シートの優先度列の値が変更されます。ワークフローがこのトリガーを検出すると、同じシートに対して必要なアクションが実行されます。トリガーからの実行時間 (実行ログ) データ参照を使用して、「Smartsheet」モジュールに入力します。

このワークフローでは、「Smartsheet シートの並べ替え」のエンドポイントに API 呼び出しを行う必要があります。Smartsheet API ドキュメントを使用して、サンプルを cURL に変更します。

ステップ 2: 最初のプロファイルを設定する

プロファイルは、ワークフローを接続するシステム API の主要情報を保存する手段です。Make API Call モジュールでプロファイルを選択すると、API 呼び出しに必要な情報がすでに設定されています。 

  1. 統合タブに移動します。
  2. API 呼び出しユーティリティを選択します。
  3. プロファイルタブのプロファイルセクションを展開します。

  4. プロファイルに追加を選択します。

    Example of new profile setup page
  5. プロファイルに名前を付けます。それぞれのプロファイル名は一意でなければなりません。
  6. 接続するシステム API の Base URL (ベース URL) を追加します。 Smartsheet のベース URL は https://api.smartsheet.com/2.0/ です。
  7. シークレット ヘッダーの下に、トークンや秘密情報 (API トークンなど) を含むヘッダーを追加します。
    • たとえば、Smartsheet 呼び出しでは、通常 Authorization という名前のキー ヘッダーがあり、値は Bearer [各自の API トークンを入力] に設定されています。
  8. ヘッダーの下に、このプロファイルを使用して行うすべての API 呼び出しに含めるべきヘッダーを追加します。
    • この例では、ヘッダーとして Content-Type を使用し、値を application/json に設定しています。
  9. [保存] を選択します。
  10. ワークフローに戻ります。

Bridge ビルダーのヒント

ベース URL は、システム API の URL のうち、そのシステムで何をしようとしても常に変わらない部分です。Make API Call モジュールのエンドポイントには、その API 呼び出しで実行する必要がある特定の情報とアクションを含めることができます。

たとえば、Smartsheet API を使用してシートを並べ替える、などです。Smartsheet API プロファイルのベース URL は https://api.smartsheet.com/2.0 で、このモジュールを使用して実行する具体的なアクションは特定のシートの並べ替えですので、sheets/sheet_id_or_data_reference_here/sort をモジュールの エンドポイント フィールドに追加する必要があります。

ステップ 3: ワークフローで Make API Call モジュールを設定する

  1. Make API Call モジュールで、ドロップダウンから使用するAPI プロファイルを選択します。
  2. [Endpoint (エンドポイント)] フィールドに、[URL] フィールドのうちプロファイルの [Base URL (ベース URL)] フィールドに追加されなかった部分を含めます。
    • この例では、sheets/sheet_id_or_data_reference_here/sort を使用しました。
  3. 以下のフィールドに入力します。ただし、そのすべてを使用するとは限りません。
    • [Method (メソッド)] を [POST (POST)] に設定します。
    • [HTTP Request Body (HTTP リクエスト本文)] フィールドで、本文が {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]} のように表示されるはずです。
    • [Form Parameters (フォーム パラメータ)] (使用している場合 — このワークフローでは使用していません)

  4. 変更内容を保存します。

    Make API Call example

ステップ 4: ワークフローをテストする

  1. シートを開きます。 
  2. 優先度列の値を変更します。 
  3. シートを保存します。 

優先度列がドロップダウンの場合、並べ替えられた行は、(API 呼び出しの本文で定義した内容に応じて) 列設定に表示されている値の昇順または降順になります。 

モジュールのその他の設定

  • Make API Call モジュールは、すべての API 呼び出しを JSON オブジェクトとして返します。応答を文字列として返す必要がある場合は、モジュールの [Additional settings (その他の設定)] で [Return raw response (応答をそのまま返す)] チェックボックスをオンにします。
  • 特定の呼び出しに追加のヘッダーを含める必要がある場合は、[HTTP Request Headers (HTTP リクエスト ヘッダー)] セクションにコピーします。

このワークフローの代替オプション

ソリューション全体で Call API ツールを使用する

  • プロファイルはワークスペースに適用されるので、どの Make API Call モジュールを使用していても、ワークスペース内のすべてのワークフローで同じプロファイルを使用できます。
  • ユーザーの権限が変更されたり、システム API が変更を加えたりしたために、プロファイルの詳細を変更する必要がある場合、単一の場所でそうした変更を行い、そのプロファイルを使用しているワークスペースのワークフローに適用することができます。
  • 接続する必要がある追加のシステム API ごとに、新しいユニークなプロファイルを設定できます。
  • Make API Call モジュールは、ターゲット API からの応答を受け取ると成功します。エラーを受け取った場合も含まれます。これは、API からの予期しない応答に対するワークフロー内のパスを決定するために後のステップで役立ちます (例: API 呼び出しがエラーを返した場合、行に問題があったことを示す更新を送信できます)。API がエラーを返した場合にワークフローを停止させたい場合は、モジュールの [Additional Settings (その他の設定)] セクションの下にあるチェックボックスをオンにします。