API トリガーを管理する

API トリガーを作成する

1. フォルダーで [オートメーション] > [トリガー] > [API トリガー] に移動します。

2. [ 新しいトリガーを追加] をクリックします。[ API トリガーの追加 ] ウィンドウが表示されます。

3. [プロセス名] ドロップダウン メニューから、トリガーの基になるプロセスを選択します。

4. 簡単に識別できるように、[名前] フィールドにトリガーの名前を追加します。

5. [ジョブの優先度] ドロップダウン メニューから、ジョブの優先度を選択します。既定値は [継承] で、ジョブの優先度は選択されたプロセスに定義された優先度と同じになります。

6. [ランタイムの種類] ドロップダウン メニューから、トリガーによって起動されるジョブの実行に使用するランタイムを選択します。

7. プロセスに入力引数がある場合、[引数] タブで、その引数の値を設定します。入力および出力引数の詳細については、こちらをご覧ください。

8. [動詞] ドロップダウン メニューから、ジョブで実行するアクションを表すオプション ([DELETE]、[GET]、[POST]、[PUT]) を選択します。

9. [ スラグ ] フィールドに、ベース URL に追加するスラグを入力し、作成するエンドポイントの最終的な URL を生成します。アプリケーションではこの URL を使用します。フィールドの下に完全な URL のプレビューが表示されます。

   既定のスラグは ${Process_Name} ですが、カスタマイズしてテナント レベルでの一意性を確保できます。

   スラッシュはサポートされないことに注意してください。

10. [既定の呼び出しモード] ドロップダウン メニューから、目的の呼び出しモードを選択します。利用可能なオプションは次のとおりです。

    • 非同期ポーリング (既定値ですが、変更できます)

    • 非同期で完了を待たずに実行 (fire & forget)

    • 同期 (ロングポーリング)

      これらのオプションについて詳しくは、「API トリガーを使用してジョブを開始する」をご覧ください。

11. [ジョブの実行を終了するスケジュールを設定] トグルをオンにして、ジョブの終了方法を選択します。

    注:

    • ジョブがキューに入っている時間も、ここで設定された経過時間に含まれることになります。たとえば、ジョブを午後 1 時に実行されるようにスケジュールし、20 分後に停止するように設定した場合、そのジョブは、たとえ午後 1 時 15 分までキューにあり、その後開始されたとしても、午後 1 時 20 分には停止されます。
    • トリガーの [ジョブの実行を終了するスケジュールを設定] オプションは、手動で開始されたジョブのために保持されます。 たとえば、トリガー T1 を作成し、以下のジョブ終了スケジュールをアクティブ化したとします。
    • ジョブの実行を終了するスケジュールを設定: 10 分後にジョブを停止
    • ジョブが停止しない場合に自動的に強制終了するスケジュールを設定: 2 分後にジョブを強制終了。[オートメーション] > [トリガー] ページで、トリガー T1 に対して [ジョブを今すぐ開始] をクリックすると、[ジョブの開始] ページが開き、すでに適用されているジョブ終了スケジュールが表示されます (トリガーの作成時に設定したものと同じ)。

    さらに、保留中または実行中のジョブを 2 時間後に停止するようスケジュールし、さらに 3 時間後に同じジョブを強制終了するよう設定した場合、ジョブは 5 時間後に強制終了されます。これは、最初に、ジョブが実際に 2 時間後に停止されたことを示すシグナルが Orchestrator に送信されるために発生します。シグナルを受信すると、ジョブの強制終了アクションが 3 時間後にトリガーされ、合計で 5 時間かかります。

• ドロップダウンから [停止] を選択 - ジョブが「保留中」または「実行中」ステートになってから指定した期間が経過した後に、実行の終了を試行します (期間を最短 1 分、最長 10 日、1 日は 23 時間 59 分として設定)。

  例: 10 分以上「保留中」または「実行中」ステートが続いているジョブに対して停止が試行されます。

  

• ドロップダウンから [強制終了] を選択 - ジョブが「保留中」または「実行中」ステートになってから指定した期間が経過した後に、実行の強制終了を試行します (期間を最短 1 分、最長 10 日、1 日は 23 時間 59 分として設定)。

  例: 10 分以上「保留中」または「実行中」ステートが続いているジョブに対して強制終了が試行されます。

  • ドロップダウンから [停止] を選択し、[ジョブが停止しない場合に強制終了] オプションを有効化 - ジョブが「保留中」ステートになってから、指定した期間が経過した後、実行の終了を試行します。その後、ジョブが「停止中」または「実行中」ステートになってから指定した期間が経過した後に、実行の強制終了を試行します (期間を最短 1 分、最長 10 日、1 日は 23 時間 59 分として設定)。

    例: 10 分以上「保留中」または「実行中」ステートが続いているジョブに対して停止が試行されます。それでもジョブが終了しない場合、20 分以上「停止中」ステートが続いているジョブに対して強制終了が試行されます。

12. [トリガーを自動的に無効化するスケジュールを設定] トグルをオンにして、トリガーを無効化する日時を入力します。タイム トリガーは、選択したタイム ゾーンで指定された日時に無効化されます。

13. [ジョブが保留中または再開ステータスのままになっている場合にアラートを生成] トグルをオンにして、ジョブが保留中または再開のステータスに留まることを許容できる期間を設定します。設定可能な最小期間は 1 分です。設定可能な最大期間は 11 日です。ジョブが設定された期間を超えた場合、重要度が「Error」のアラートがポップアップで表示され、以下のテキストによって通知されます。「#プロセス {process_number} の N 個のジョブが、X 時間 Y 分を超えて保留中または再開ステータスのままです。」各記号の意味は次のとおりです。

    • N - アラートをトリガーしたジョブの数です。
    • {process_number} - プロセス識別子です。
    • X - ジョブが保留中または再開ステータスの間に設定値を超えた時間数です。日は時間に変換されます。
    • Y - ジョブが保留中または再開ステータスの間に設定値を超えた分数です。

14. [開始済みのジョブが完了していない場合にアラートを生成] トグルをオンにして、ジョブが完了するまでの許容できる期間を設定します。設定可能な期間は、最小で 1 分、最大で 11 日です。ジョブが設定された期間を超えた場合、重要度が「Error」のアラートがポップアップで表示され、以下のテキストによって通知されます。 「#プロセス {process_number} のジョブが、X 時間 Y 分を超えて実行されています。」各記号の意味は次のとおりです。

    • {process_number} - プロセス識別子です。
    • X - ジョブが完了試行中に設定値を超えた時間数です。日は時間に変換されます。
    • Y - ジョブが完了試行中に設定値を超えた分数です。

15. ジョブが失敗した後にトリガーを無効化するタイミングを制御するには、[ジョブの実行に基づいてトリガーを無効化] トグルをオンにします。このトグルをオンにすると、次の 2 つのオプションが表示されます。

    オプション	説明
    ジョブが指定した回数連続して失敗した場合に無効化	この設定で選択した回数だけ実行が失敗すると、トリガーが無効化されます。 0 から 100 の値を選択できます。既定値は 0 です。つまり、トリガーは無効化されません。 ジョブの停止はこの値にカウントされません。
    トリガーの無効化の猶予期間 (日)	ジョブが最初に失敗してからトリガーが無効化されるまでの待機期間 (日数) です。 0 から 30 の値を選択できます。既定値は 0 です。つまり、上記フィールドで設定したジョブの実行数に達すると、当日すぐトリガーが無効化されます。

16. ジョブの開始用に設定されたアカウントとマシンのコンテキストを維持するには、[ジョブの再開時にアカウントとマシンの割り当てを維持する] チェックボックスをオンにします。これにより、ライセンスとリソースの使用状況が最適化されます。

重要:

• API トリガーにはテナント レベルの実行設定が適用されます。
• 作成できる API トリガーは、テナントあたり最大 1,000 個です。

API トリガーに対するアクション

[API トリガー] ページでは、各トリガーのコンテキスト メニューからさまざまな操作を実行できます。

注:

このセクションの例では、 6ea73196-ca89-446c-81e1-5279bdd36dc2 英数字の識別子は、API トリガーがあるフォルダーのフォルダー キーです。Orchestrator API は、識別子を /Folders エンドポイントの Key パラメーターの値として使用します。

完全なスラグ URL をコピー

サードパーティ アプリケーションで使用する URL をコピーします。

hw-process スラグを使用した API トリガーの場合、次のようになります。https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process

編集

選択した API トリガーのプロパティを変更します。

スラグをコピーする

コマンド ラインや既存のコードでの使用に適した形式でスラグをコピーします。利用可能なオプションは次のとおりです。

cURL (bash) としてコピー - hw-process スラグを使用した API トリガーの場合、次のようになります。

curl '{baseURL_orchestrator}/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process'  -X 'POST'  -H 'Content-Type: application/json'  -H 'Authorization: Bearer ***INSERT_YOUR_TOKEN***'

cURL (cmd) としてコピー - hw-process スラグを使用した API トリガーの場合、次のようになります。

curl "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process" ^ -X "POST" ^ -H "Content-Type: application/json" ^ -H "Authorization: Bearer ***INSERT_YOUR_TOKEN***"

フェッチとしてコピー - hw-process スラグを使用した API トリガーの場合、次のようになります。

fetch("https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process", { headers: { Authorization: "Bearer ***INSERT_YOUR_TOKEN***", "Content-Type": "application/json" }, "method": "POST" })

PowerShell としてコピー - hw-process スラグを使用した API トリガーの場合、次のようになります。

$headers = @{ "method"="POST" "Authorization" = "Bearer ***INSERT_YOUR_TOKEN***" } Invoke-WebRequest -UseBasicParsing -Uri "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process" ` -Headers $headers ` -ContentType "application/json"

有効化

以前無効化した API トリガーを有効化します。

無効化

既に有効化されている API トリガーを無効化します。

Remove

選択した API トリガーを削除します。API トリガーを削除することは、生成されるエンドポイントを削除することと同じです。特定のシナリオに応じて、以下のような動作を期待できます。

開始済みのジョブ

削除した API トリガーに関連付けられたプロセスに基づくジョブが、トリガーの削除時に開始済みである場合、そのジョブは完了するまで実行されます。

新しいジョブを開始する

URL は利用できなくなっているため、削除した API トリガーに関連付けられたプロセスに基づくジョブを開始しようとすると、404 エラーが発生します。

プロセスを編集する

1 つ以上の API トリガーで使用されているプロセスを編集すると、トリガーが更新され、新しい一連のプロセス プロパティが適用されます。

クロスオリジン リソース共有

テナント設定の [全般] タブで [API トリガーの CORS 許可リスト] オプションを選択することで、ドメインを受信トラフィックの許可リストに追加できます。

この設定は、ブラウザーから (サーバーからではありません) Orchestrator に HTTP 要求を実行するブラウザー アプリケーションに必要です。ドメインを許可リストに登録しないと、CORS ポリシー エラーが発生する可能性があります。CORS ポリシー エラーは開発者コンソールで確認できます。

他のドメインを許可リストに登録する場合は、カンマを使用するか Enter キーを押して各ドメインを区切ります。

API 定義

このページには、作成した API トリガーの Swagger 定義が、その出力と共にフォルダーごとにグループ化されて表示されます。さらに、トリガーに関連するジョブを実行することもできます。

このページにアクセスするには、[API トリガー] ページの [API 定義] ボタンをクリックするか、https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/t/swagger/index.html を使用します。

図 1. [API トリガー] ページ

API トリガーが個人用ワークスペースおよび Shared フォルダー内にあるテナントの API 定義は、次のようになります。

図 2. テナントの API 定義