Call API ツールを設定する

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

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

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

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

   

Bridge ビルダーのヒント

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

API 呼び出しフィールド

開始する前に、API の使用に関する用語を確認しましょう。

Base URL (ベース URL)

このフィールドはプロファイルに含まれており、API URL のうち常に同一である部分です。Smartsheet の場合は、https://api.smartsheet.com/2.0/ というベース URL を使用します。

Endpoint (エンドポイント)

このフィールドは Make API Call モジュールに含まれており、実行するアクション (例: シートの並べ替え) を指定します。この値に、Bridge トリガーから必要なデータ参照を追加できます。

静的データまたは動的データの設定方法の例を以下に示します。

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

Method (メソッド)

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

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

Headers (ヘッダー)

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

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

Form Parameters (フォーム パラメーター)

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

サンプル シナリオでは、Smartsheet 呼び出しでページングを適用し、特定の数のアイテムのみが応答に含まれるようにします。たとえば、2 万行のレポートの最初のページのみを取得したい場合です。
 

Body (本文)

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

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

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

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

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

返されるデータ

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

これで、Call API プロファイルと Make API Call モジュールの設定時に表示されるフィールドが分かりました。このユーティリティの設定と使用方法について、詳しくは以下をお読みください。

始めるために必要なもの

• シート
  • シート ID
  • 行で変更されたときに、Bridge ワークフローをトリガーする列
• Bridge
  • Smartsheet の統合機能
  • Bridge ワークフロー トリガー: Smartsheet - [When Column Values are Changed (列の値が変更された場合)]
  • Bridge ワークフロー モジュール: Make API Call
• Smartsheet API キー。Smartsheet 用の API キーを生成する方法をご確認ください。 

今すぐスタート

Bridge でこのワークフローを構築するには、Bridge ワークスペースに対して Smartsheet 統合を認証します。「Bridge 向け Smartsheet 統合機能の設定方法」についての手順をご覧ください。 

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

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

まず、ワークフローに必要なすべてのモジュールを用意します。 

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

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

Brandfolder Image

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

基本的なワークフローのモデルを作成したら、ワークフローのトリガーの設定を開始します。

1. [Trigger (トリガー)] モジュールを選択します。
2. 新しいタブで「Integration (統合)」パネルを開くには、「Integrations (統合)」セクションで、[Integrations (統合)] ページを選択します。

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

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

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

10. ワークフローに戻ります。
     

    元のタブに戻る場合は、ページを最新の情報に更新してトリガーを表示させます。

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

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

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

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

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

1. Bridge アカウントにログインします。
2. [Integrations (統合)] タブに移動します。
3. 「Call API (API 呼び出し)」ユーティリティを選択します。

4. [Add to Profiles (プロファイルに追加)] を選択します。

   Brandfolder Image

   
5. プロファイルに名前を付けます。それぞれのプロファイル名は一意でなければなりません。
6. 接続するシステム API のベース URL を追加します。
   • この例では、https://api.smartsheet.com/2.0/ が Smartsheet 用のベース URL となります。
7. [Secret Headers (シークレット ヘッダー)] で、トークンや秘密情報 (API トークンなど) を含むヘッダーを追加します。
   • たとえば、Smartsheet 呼び出しには通常 「Authorization」 という名前のキー ヘッダーがあり、値が Bearer [各自の API トークンを入力] に設定されています。
8. [Headers (ヘッダー)] で、このプロファイルを使用して行うすべての 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 をモジュールの [Endpoint (エンドポイント)] フィールドに追加することになります。

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

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

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

   Brandfolder Image

   

   
    

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

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

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

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

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

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

ここで、このワークフローをカスタマイズする方法についてアイデアをいくつか紹介します。

• 並べ替えるシートまたは列について、それと異なるシートや列からトリガーする。この場合は、並べ替えを実行したいシートや列に合わせて、API 呼び出しの詳細を変更する必要があります。 
• 並べ替えに条件を追加する。ワークフローがトリガーされた後、ジャンクションのモジュールを使用して列の値を評価し、優先度列の変更に基づいてさまざまなアクションを実行します (例: 優先度が 0 の場合、シートから行を移動し、優先度が 1 の場合はシートを並べ替える)。
• 「Schedule (スケジュール)」トリガーを使用する。このトリガーを使用すると、シートが 1 日、1 週間、または 1 か月に 1 回並べ替えられるため、変更に対応する必要がなくなります。

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

• プロファイルはワークスペースに適用されるので、どの Make API Call モジュールを使用していても、ワークスペース内のすべてのワークフローで同じプロファイルを使用できます。ユーザーの権限が変更されたり、システム API が変更を加えたりしたために、プロファイルの詳細を変更する必要がある場合、単一の場所でそうした変更を行い、そのプロファイルを使用しているワークスペースのワークフローに適用することができます。
• 接続する必要があるシステム API ごとに、このガイドの最初の部分に従って新しい一意のプロファイルを設定できます。