メインコンテンツまでスキップ

連携のステップ

連携ステップは、ワークフローの外にあるシステムを呼び出します。外部 API、GitHub、Forge 関数、Oliver エージェントが対象です。API ステップ、GitHub のステップ、Oliver の実行ステップは、パレットの ツール＆タスク カテゴリーにあります。Forge 関数には専用の Forge関数 カテゴリーがあります。キャンバスの右クリックメニューから追加できるのは、このうち API ステップだけです。

ステップ用途
APIステップ認証、リトライ、失敗時のルーティングを備えた HTTP リクエストを送信します。
GitHub アクションGitHub Actions のワークフローの実行を開始し、必要に応じて完了を待ちます。
GitHub コミット文書を GitHub リポジトリにコミットします。
Forge 関数アップロードされた Forge 関数を実行します。
Oliver を実行Oliver エージェントをワークフローのステップとして実行します。

API ステップ​

失敗ルートの出力がある API ステップ

APIステップ

カードのタイトルは APIリクエスト です。右側にあるラベルのない出力が成功時の経路です。失敗ルートを追加するたびに、ラベル付きの出力が 1 つずつ増えます。自動リトライが有効なときは更新アイコンが表示されます。URL を設定するまで、ステップには 設定エラー と表示されます。鉛筆アイコンを選択すると APIステップを編集 が開きます。

APIステップを編集ダイアログ

APIステップを編集

ダイアログは 3 列に分かれています。左にリクエストの設定、中央に ヘッダー と ボディ、右に テストリクエスト と 同等のコード があります。変更はその場で反映され、テンプレートを保存すると保持されます。

基本設定​

設定説明
URL呼び出し先のエンドポイント。文書の値やキーストアのシークレットを含めることができます。例: {{ document.reference_number }}、{{ keystore('my_key') }}
リクエストメソッドGET（既定）、POST、PUT、DELETE のいずれか。
生データを保存送信したリクエスト本文と未加工のレスポンスも保存します。ワークフローのビジュアライゼーション画面からダウンロードできます。
ヘッダーJSON 形式のヘッダー。値には、URL や本文と同じように、ワークフローの文書の値が差し込まれます。
ボディリクエスト本文。プレースホルダーには、ワークフローの文書の値が差し込まれます。

ステータスが 2xx であれば成功とみなされます。

認証設定​

API ステップの OAuth2 認証設定

認証設定: OAuth2 クライアント認証情報

認証方法項目
なしなし。
ベーシックユーザー名 と キー。
APIトークンAPIトークン。Bearer トークンとして送信されます。
トークン取得認証リクエストURL（GET、POST、PUT）からトークンを取得し、ベアラートークン または 名前付きヘッダー として付与します。トークンの位置は トークンパス で、data.token のようなドット区切りのパスで指定します。有効期限パス に同じレスポンス内のトークンの有効期限を指すドット区切りのパスを指定すると、実行のたびにトークンを取得せず、有効期限の少し前まで取得済みのトークンを使い回します。
OAuth2 クライアント認証情報トークンURL、クライアントID、クライアントシークレット、任意で スコープ と オーディエンス。
カスタムヘッダーヘッダー名 と 値テンプレート。シークレット（任意） を選択すると、展開後の値の末尾に付加されます。

キー はキーストアのエントリーです。新しいエントリーを追加 を使うと、ダイアログを閉じずにエントリーを作成できます。レスポンス検証 では、レスポンスの HMAC 署名も検証できます。設定項目は アルゴリズム（SHA512）、署名キー、タイムスタンプヘッダー（既定は X-Timestamp）、署名ヘッダー（既定は X-Signature）、有効期間（秒）（既定は 300）です。

失敗ルート​

タイムアウトのルートを設定した API ステップの失敗ルート

失敗ルート

失敗ルートがない場合、リクエストが失敗するとワークフローはこのステップで止まります。失敗ルートを使うと、特定の種類の失敗をそれぞれ専用の出力に送れます。失敗の種類 を選んで ルートを追加 を選択します。ルートは上から順に確認され、最初に一致したものが使われます。

失敗の種類一致する条件既定のパス名
タイムアウトリクエストがタイムアウトした。timeout
HTTPエラーステータスステータスコード に指定したコード（429,503 や 5xx など）が返された。空欄の場合は、失敗を示すステータスすべてに一致します。http_error
空 / null レスポンス変換後のレスポンスが空だった。empty
レスポンスの正規表現一致失敗したレスポンスの本文が 正規表現パターン に一致した。matched
キュー上限に到達同時実行の制限により、リクエストの実行枠を確保できなかった。queue_full
すべての失敗を捕捉あらゆる失敗。failed

パス名 は、そのルートの出力に付くラベルです。パス名は重複できず、end と start は予約されています。どのルートにも一致しない失敗が起きると、ワークフローは止まります。

失敗メッセージの解析 は、失敗したレスポンスから読みやすい理由を取り出し、インボックスと失敗通知メールに表示します。抽出の手順（正規表現、XML や HTML の要素、JSON のキー）は上から順に実行されます。最終的な失敗時に起票者へメール通知 を有効にすると、リクエストが最終的に失敗し、どの失敗ルートでも処理されなかったときに、ワークフローを開始した人にメールが届きます。

自動リトライ​

API ステップの自動リトライの設定

自動リトライ

自動リトライを有効化 を選ぶと、失敗ルートを適用する前に、失敗したリクエストを再試行します。

設定説明
リトライ条件タイムアウト（既定でオン）、HTTPエラーステータス（リトライ対象ステータスコード を指定）、null / 空のレスポンス、その他のエラー。
最大リトライ回数1〜500。既定は 5。
初回リトライ遅延既定は 5 分。リトライの要否は 5 分ごとに確認されます。
遅延減衰係数リトライのたびに遅延をどれだけ延ばすか。既定は 2。1 にすると遅延は一定になります。
最大遅延遅延の上限。既定は 60 分。
ジッター（0〜1）遅延をランダムにずらし、同時に失敗した項目が同時にリトライしないようにします。既定値の 1 では、選択した遅延より早くリトライすることがあります。

同時実行数とバースト制御​

API ステップの同時実行数とバースト制御の設定

同時実行数とバースト制御

同時リクエスト数を制限する を有効にすると、応答の遅いエンドポイントやレート制限のあるエンドポイントに、このステップが送るリクエストの量を抑えられます。上限を超えたリクエストはキューに入って自動的に再試行され、インボックスには キュー待ち と表示されます。キューで待っている間は、自動リトライの回数を消費しません。

設定説明
リクエストのグループ化基準同じエンドポイントとみなす範囲。URL（ホストとパス）（既定）、サーバー（ホストのみ）、URLとリクエスト本文、このステップのみ、カスタムテンプレート のいずれか。
同時実行リクエスト数1〜64。既定は 2。
時間ウィンドウあたりのリクエスト数0 にすると時間あたりの制限はかかりません。1 以上にすると ウィンドウ長（秒） が表示されます。
Wait for a free slot (seconds)キューに入ったリクエストを再試行するまでの間隔を設定します。リクエストは空きを待たず、すぐにキューに入ります。

制限の上には、設定内容を文章で説明した概要が表示されます。

ページネーションとペイロード変換​

ページネーション変数 と ページネーション乗数 を使うと、結果をページ単位で取得できます。ページごとに、ページ番号（0 から始まる）に乗数を掛けた値が変数に設定され、URL と本文に改めて差し込まれます。空のレスポンスが返るとページの取得は終わります。各ページの結果が上書きされずに積み上がるよう、変換の最後には JSONをDataframeに変換 を置いてください。

API ステップのペイロード変換の手順

ペイロード変換設定

ペイロード変換設定 では、保存する前にレスポンスの形を整えます。手順は上から順に実行され、それぞれ前の手順の出力を受け取ります。変換タイプ を選んで ステップを追加 を選択します。

変換タイプ処理内容
XMLを辞書に変換XML を解析します。
キー抽出ネストされたキー の位置にある値を取り出します。
文字列からJSONテキストを JSON として解析します。
JSONをDataframeに変換表を作ります。オブジェクトは 1 行に、リストは項目ごとに 1 行になります。
仮想キー生成指定した列を連結した列を追加します。この手順で起きたエラーは無視されます。
辞書をマージネストされたオブジェクトを 1 階層に平坦化し、ネストされたキーをアンダースコアでつなぎます（address.city は address_city になります）。設定項目はありません。
Reggex ExtractionReggex Pattern に最初に一致した部分を残します。
列生成値を 結果列名 の列に入れた 1 行の表を作ります。

API ステップの直後に接続した CF挿入ステップ または JSONからデータフレーム が、保存された結果を読み取ります。データのステップを参照してください。

テストリクエストと同等のコード​

テストリクエストを送信 を選択すると、リクエストを 1 回送信し、ステータス、レスポンス、レスポンスヘッダー、実際に送信したリクエスト、各変換の結果を表示します。サンプル文書番号 には、文書のプレースホルダーに値を差し込む元の文書番号を入力します。Ctrl または ⌘ + Enter でも送信できます。

警告

テストリクエストを送信では、実際にリクエストが送信されます。 POST、PUT、DELETE の呼び出しは、エンドポイント側のデータを変更します。影響のないエンドポイントでテストしてください。

同等のコード には、リクエストを cURL、TypeScript、Python で表したコードが表示されます。APIトークン の値は $API_TOKEN に置き換えて表示され、ステップの設定から取得される旨の注記が付きます。

GitHub アクション​

GitHub アクションステップ

GitHub アクションステップ

接続済みのリポジトリで GitHub Actions のワークフローを開始します。コネクターの GitHub Actions 機能をオンにしておく必要があります。リポジトリとワークフローファイルを設定するまで、ステップには 設定エラー と表示されます。

リポジトリが接続されていない状態の GitHub アクションステップを編集ダイアログ

GitHub アクションステップを編集

設定説明
リポジトリ接続済みのリポジトリ。接続されたリポジトリがない場合、ダイアログには GitHubリポジトリが設定されていません。 と表示されます。
ワークフローファイルワークフローファイル。例: ci.yml。workflow_dispatch トリガーが必要です。
Ref（ブランチまたはタグ）必須です。ただし、空欄でもカードに警告は表示されません。文書の値を含めることができます。
ワークフロー入力実行に渡す追加の入力。入力を追加 で追加します。値には文書の値を含めることができます。
実行追跡モード送信して続行 は、実行が始まった時点で先に進みます。完了をポーリング は完了を待ち、最長で約 6 時間確認を続けます。Webhook を待機 は GitHub からの通知を待ち、約 57 分で待機をやめます。
実行結果を文書に添付完了をポーリング または Webhook を待機 が必要です。実行が終わると、ワークフローが先に進む前に、ジョブの結果（JSON ファイル）とすべての成果物をワークフローの文書に添付します。出力を取得できなかった場合は インフラエラー時 に進みます。
出力使われる場合
成功時実行が成功した。送信して続行 では、実行が開始された。
失敗時実行が失敗またはキャンセルされた。または、ファイルや ref の誤りなどにより、GitHub が実行の開始を拒否した。
インフラエラー時実行が終わる前に、Docwize が待機をやめた。

リポジトリがない、接続が切れている、またはコネクターの機能がオフになっている場合、ワークフローはどの出力も使わずに止まります。インフラエラー時 だけでなく 失敗時 も接続してください。1 時間を超える実行には 完了をポーリング を使います。

実行を追跡するには、ワークフローファイルで docwize_run_id 入力を宣言し、run-name に含めます。ファイルを追跡できない場合、ダイアログに このワークフローでは実行トラッキングが機能しない可能性があります という警告が表示されます。

GitHub コミット​

GitHub コミットステップ

GitHub コミットステップ

接続済みのリポジトリに、文書を 1 つのコミットとしてコミットします。コネクターには コンテンツ書き込み が、.github/workflows 配下のパスには ワークフローファイル も必要です。このステップの出力は 成功時 の 1 つだけで、問題が起きるとワークフローはこのステップで止まります。リポジトリとブランチを設定するまで、ステップには 設定エラー と表示されます。

GitHub コミットステップを編集ダイアログ

GitHub コミットステップを編集

設定説明
リポジトリ接続済みのリポジトリ。
ブランチコミット先のブランチ。例: docwize/test-{{wf_id}}
ベースブランチ（任意）新しいブランチの作成元。既定はリポジトリの既定ブランチです。
ブランチが無ければ作成既定でオン。オフの場合、ブランチが存在しないとステップは失敗します。
完了時にブランチを削除後続の GitHub アクション ステップが GitHub から結果を受け取った時点で、ブランチを削除します。送信して続行 モードでは機能しません。
コミット対象ワークフロー文書、ステップ入力（ワークフローの文書に直接添付されたもの）、または 文書 ID に指定した 特定の文書 ID。
リポジトリパス（任意）リポジトリ内のフォルダー。各ファイルは元の名前のままコミットされ、同じパスに既存のファイルがあれば上書きされます。
コミットメッセージ（任意）既定は「Add N file(s) from Docwize workflow …」です。

ブランチ、ベースブランチ、パス、メッセージには、文書の値を含めることができます。

Forge 関数​

Forge 関数ステップ

Forge 関数ステップ

パレットの Forge関数 には、有効なバージョンがあるアップロード済みの関数が 1 つずつ表示されます。カードには、関数の名前、ランタイム、モードが表示されます。出力は、ラベルのない成功時の出力、関数のマニフェストに定義されたルートごとの出力、自動的に追加される エラー です。Docwize Forge を参照してください。

Forge 関数の設定ダイアログ

Forge 関数の設定

設定説明
関数実行する関数。変更すると、バージョンと設定はクリアされます。
バージョン有効なバージョン（推奨） は、その時点で有効なバージョンに従います。番号付きのバージョンを選ぶと固定されるのはコードだけで、出力と設定項目は引き続き有効なバージョンに従います。
コールバックの待機日数非同期の関数で、関数からの結果報告を何日待つか。期限を過ぎると エラー に進みます。
設定関数の設定キー。シークレットのキーにはキーストアのエントリーを使います。
  • エラー は、関数が失敗した、何も返さなかった、マニフェストで宣言されていないルートを返した、クォータを使い切った、またはコールバックの期限に間に合わなかった場合に使われます。

Oliver を実行​

設定前の Oliver の実行ステップ

Oliver の実行ステップ

Oliver エージェントをワークフローのステップとして実行し、その回答をカスタムフィールドに書き込みます。エージェントと出力先のフィールドを設定するまで、ステップには 設定エラー と表示されます。鉛筆アイコンを選択すると設定が開きます。

Oliver 実行ステップを編集ダイアログ

Oliver 実行ステップを編集

設定説明
エージェント実行するエージェント。エージェントを作成 を選択すると、設定アプリが新しいタブで開きます。
システムプロンプト注入任意。今回の実行に限り、エージェントのシステムプロンプトに追加する指示。
プロンプト依頼内容。文書の値を含めることができます。例: {{document.description}}
コンテキスト文書文書 ID またはプレースホルダーをカンマ区切りで指定します。既定はワークフローの文書です。その文書に直接添付されたものは自動的に追加されます。
実行ユーザーワークフロー起票者（既定）、文書所有者、特定のユーザー のいずれか。このユーザーが、コンテキストの文書を少なくとも 1 つ開ける必要があります。
タイムアウト（秒）30〜3600。既定は 600。
出力カスタムフィールドエージェントの最終的な回答を書き込む先。
分岐カスタムフィールド（任意）エージェントが回答の最後に {"branch":"<label>"} を付けたとき、その分岐ラベルを受け取ります。条件 ステップでの振り分けに使えます。

ワークフローで使えなくなる前に チャネル ID で保存されたステップには警告が表示されます。実行ユーザー で別の選択肢を選び直してください。

保存 を選択すると、変更がステップに書き込まれ、ダイアログが閉じます。キャンセル を選択すると変更は破棄されます。ステップの変更を残すには、いつもどおりテンプレートを保存してください。

設定済みの Oliver の実行ステップ

設定済みの Oliver の実行ステップ

エージェントが回答を返して終了すると、ワークフローは 成功時 に進みます。失敗時 に進むのは、実行が失敗またはキャンセルされた場合、入力を求めて止まった場合、回答が空だった場合、タイムアウトした場合です。設定や権限に問題がある場合、ワークフローはどちらの出力も使わずに止まります。

エージェントは、ほかのエージェントへの委任を含め、自分のツールを使って実行されます。使えないのは、人の操作を待つツールだけです。ユーザーへの追加情報の問い合わせ、承認の依頼、誰かが保存を選択する必要がある編集画面の表示がこれに当たります。検索結果、グラフ、PDF プレビューなどの読み取り専用の表示は使えます。無人で実行しても安全なツールを持つエージェントを選んでください。後続のプレースホルダーでは、出力先のフィールドを {{ <template_name>.<field_name> }} の形式（小文字、アンダースコア区切り）で参照します。