手動開始ワークフローAPIとBox Relay

Published in

Box Developer Blog

Sep 7, 2021

Box Relay用に2つの新しいAPIエンドポイントをリリースしました。1つ目のエンドポイントでは、指定したフォルダに対して構成されたワークフローを取得できます。もう1つのエンドポイントでは、トリガータイプがWORKFLOW_MANUAL_STARTに設定されているワークフロー内のフローを開始できます。このガイドでは、これらの新しいエンドポイントの使用方法を説明します。

前提条件

· 手動開始フローを作成しておく必要があります。こちらのガイドを参照してください。

ステップ1

Boxアプリケーションを設定します。上記の新しいエンドポイントを使用するには、開発者コンソールの構成セクションにあるアプリケーションスコープで [Box Relayを管理する]、[Boxに格納されているすべてのファイルとフォルダの読み取り]、[Boxに格納されているすべてのファイルとフォルダへの書き込み] を有効にする必要があります。アプリケーションの認証方法によっては、管理者によるアプリケーションの再承認が必要になる場合があります。

ステップ2

ワークフローを設定したら、GETエンドポイントを使用して、指定したフォルダに対するワークフローをすべて表示します。このエンドポイントを使用するcURLの例を次に示します。

curl -i -X GET “https://api.box.com/2.0/workflows?folder_id=324234"\
 -H “Authorization: Bearer <ACCESS_TOKEN>”

レスポンスの一部は、次のようになります。

ステップ3

WORKFLOW_MANUAL_STARTフローを開始するには、POSTエンドポイントを使用します。前述のGET呼び出しのレスポンスで受け取った情報の一部が必要になります。具体的には、フローを開始するためのフローID、フォルダID、結果IDとその設定可能な情報 (任意)、ファイルID (任意) をリクエスト本文に配置する必要があります。ワークフローIDはパスパラメータです。

1つのファイルに対してフローを開始するcURL呼び出しの例を次に示します。一度に最大20ファイルに対してフローを開始できます。

curl -i -X POST “https://api.box.com/2.0/workflows/<WORKFLOW_ID>/start" \
   -H “Authorization: Bearer <ACCESS_TOKEN>” \
   -d ‘{ 
      “type”: “workflow_parameters”, 
      “flow”: { 
       “id”: “<FLOW_ID>”,
       “type”: “flow” 
      }, 
      “files”: [{ 
         “type”: “file”, 
         “id”: “<FILE_ID>” 
      }],
      “folder”: { 
       “id”: “<FOLDER_ID>”, 
       “type”: “folder” 
      }, 
      “outcomes”: [ { 
          “id”: “<OUTCOME_ID>”, 
          “type”: “outcome”, 
          “task_collaborators”: { 
             “type”: “variable”, 
             “variable_type”: “user_list”, 
             “variable_value”: [{ 
                 “type”: “user”, 
                 “id”: “<USER_ID>” 
             }] 
           }, 
           “completion_rule”: { 
             “type”: “variable”, 
             “variable_type”: “task_completion_rule”,
             “variable_value”: “all_assignees” 
           }, 
           “file_collaborator_role”: { 
             “type”: “variable”, 
             “variable_type”: “collaborator_role”, 
              “variable_value”: “viewer” 
           } 
       }] 
   }’

フローに、フローの開始時に設定可能な結果がある場合は、各outcomeの設定可能なすべての情報のリストを取得するoutcomes配列オブジェクトを渡す必要があります。

上記の例は、タスクを割り当てる場合のoutcomeの例です。task_collaboratorsオブジェクトのvariable_value配列オブジェクトで、このタスクを割り当てる各ユーザーのリストを取得できます。

同様に、completion_ruleオブジェクトとfile_collaborator_roleオブジェクトのvariable_valueには、それぞれ値any_assignee/all_assigneesとeditor/viewer/previewer/uploader/previewer uploader/viewer uploader/co-ownerを指定することができます。

その他の設定可能なoutcomeの例は、近日中に公開する予定です。

フローの開始に成功すると、空の204レスポンスが返されます。フローからの結果はすべて、メインのBoxウェブアプリで確認できます。

SDKのサポート

SDKライブラリは、近日中に、ここで説明したエンドポイントをサポートする予定です。それまでの間、最新のPostmanコレクションまたはcURLをご利用ください。

フィードバック

バグが見つかった場合や問題を解決/修正する場合は、Boxの製品サポートチームに対して、英語でチケットを作成してください。
APIの使用方法に関する質問がある場合は、Boxの開発者向けフォーラムに英語で投稿してください。