API ワークフローを管理する

API ワークフローを作成する

API ワークフロー ソリューションを作成するには、以下の手順を実行します。

1. Automation Cloud™ の組織で Studio Web を開きます。
2. [API ワークフロー >新規作成] を選択します。新しいソリューションが開き、 API ワークフロー デザイナー キャンバスが表示されます。

入力スキーマを定義する

API Workflows typically require input from their calling parties. This is handled by defining JSON objects for both input and output, each following a JSON schema. These schemas establish the data types and structure for your objects. The defined objects can include nested objects, multiple properties, and arrays, allowing you to model complex data structures as needed.

The input schema specifies the data structure an external service must provide when triggering the workflow.

You can configure the input schema by uploading a JSON payload or by manually defining input parameters.

1. API ワークフロー プロジェクトで、[ データ マネージャー ] パネルを開きます。
2. [ 入力 ] タブを選択します。

   JSON スキーマをアップロードするには、手順 3 を実行します。

   入力パラメーターを手動で定義するには、手順 4 に従います。

3. 入力パラメーターが定義済みの JSON スキーマをアップロードするには、[ ペイロードから生成] を選択します。
   1. 必要な入力を JSON で指定します。
   2. [ スキーマを生成] を選択します。
   3. 生成されたスキーマを確認し、必要に応じてプロパティに説明を追加します。
4. 入力パラメーターを手動で定義するには、[ プロパティを追加] を選択します。
   1. プロパティの詳細を設定します。
      • 名前 - プロパティ キーを定義します
      • 型 - [文字列]、[数値]、[整数]、[ブール値]、[オブジェクト]、[配列]、[日時]、[日付]、[時刻] から選択します。
        大事な： オブジェクトまたは配列を使用する場合は、入れ子にする項目のプロパティを定義します。
      • 必須 - プロパティを必須としてマークするには、このボックスを選択します。
   2. すべての入力パラメーターを定義するまで、この手順を繰り返します。

出力スキーマを定義する

The output schema defines the structure of the data returned by the API workflow, ensuring that any service calling the workflow understands the output format in advance. It is also required when the workflow includes a Response activity, as it determines the exact data sent back to the calling party.

Note: Currently, schema validation is not enforced, so if the data returned in the Response activity includes more or fewer properties than those defined in the output schema, the workflow does not fail.

The output schema includes fields explicitly defined within the schema itself, such as IDs or user-provided values, as well as outputs generated dynamically from workflow steps, such as API responses or calculated values.

You can configure the output schema by uploading a JSON payload or by manually defining output parameters.

1. API ワークフロー プロジェクトで、[ データ マネージャー ] パネルを開きます。
2. [ 出力 ] タブを選択します。

   JSON スキーマをアップロードするには、手順 3 を実行します。

   出力パラメーターを手動で定義するには、手順 4 に従います。

3. 出力パラメーターが定義済みの JSON スキーマをアップロードするには、[ ペイロードから生成] を選択します。
   1. 期待される出力を JSON に指定します。
   2. [ スキーマを生成] を選択します。
   3. 生成されたスキーマを確認し、必要に応じてプロパティに説明を追加します。
4. 出力パラメーターを手動で定義するには、[ プロパティを追加] を選択します。
   1. プロパティの詳細を設定します。
      • 名前 - プロパティ キーを定義します
      • 型 - [文字列]、[数値]、[整数]、[ブール値]、[オブジェクト]、[配列]、[日時]、[日付]、[時刻] から選択します。
        大事な： オブジェクトまたは配列を使用する場合は、入れ子にする項目のプロパティを定義します。
      • 必須 - プロパティを必須としてマークするには、このボックスを選択します。
   2. すべての出力パラメーターを定義するまで、この手順を繰り返します。

[式エディター] を使用する

式エディターを使用すると、API ワークフロー内のデータにアクセスし、評価し、データを操作できます。条件ロジックの作成、アクティビティ フィールドの設定、または JavaScript アクティビティの記述に使用します。

式エディターのレイアウト

[式エディター] のレイアウトには、次のパネルが含まれます。

パネル	説明
入力	メイン パネルは入力パネルで、ここで JavaScript 式または JQ 式を記述します。 このパネルには、式の構文のエラーを特定して強調表示する構文チェッカーが組み込まれています。
Autopilot 式ジェネレーター	入力パネルの下部にある Autopilot 式ジェネレーターを使用すると、JavaScript を記述する代わりに自然言語を使用してワークフロー式を作成できます。 Autopilot はワークフローのコンテキストを理解し、目的の結果を記述するだけでオブジェクトやワークフローのステップを参照できるようにします。
アクティビティのテスト入力	コード パネルの右側にある [アクティビティ テストの入力 ] パネルでは、以前のワークフロー実行から生成されたテスト データを確認できます。 式の構築と検証に使用できるサンプル データを提供します。また、[ 式の出力 ] パネルと直接対話して、式で目的の結果が生成されるようにします。
式の出力	[ 式の出力 ] パネルには、 アクティビティのテストの入力 データからのデータに基づいた式の結果が表示されます。これにより、式が期待される結果を生成することを検証できます。 式にエラーがある場合、[ 式の出力] セクションでは問題のある式が強調表示され、対応するエラー メッセージが表示されます。 結果は、入力パネルで式を変更するたびに自動的に更新されます。

JavaScript を使用してデータにアクセスする

There are several access points for workflow data:

• $workflow—ワークフロー レベルの設定を指します。
• $context— アクティビティ レベルの設定を指します。
• $input- 以前に実行されたアクティビティの設定を参照します。
• $context.variables—Refers to variable-level configuration.

大事な： 式 エディター内の[テスト] 入力 画面を使用して、式を作成する際にステップのプロパティを参照します。

アクセスポイント	説明	列の合計
$workflow.input	要求スキーマと、テスト コンフィギュレーションで定義されたすべての値を格納します。	式エディター内でテストの設定データにアクセスするには、次の構文を入力し、{property_name} を参照する特定のプロパティに置き換えます。 $workflow.input.{property_name}
$context	Stores the input and output data for each activity. To reference these properties in your expressions, first run and Debug the workflow . This generates step-level inputs and outputs visible in the Test Input screen.	特定のステップの出力応答データにアクセスするには、[ 式エディター] で次の構文パターンを使用し、 {step_name} と {property_name} をそれぞれステップ名とプロパティ名に置き換えます。 $context.outputs.{step_name}.content.{property_name}
$input	前のステップから現在のステップに直接渡されたデータを格納します。$inputを使用すると、$context全体を移動せずに前の手順のプロパティを参照できます。	前の手順のプロパティにアクセスするには、次の構文を使用し、 {property_name}を参照するプロパティに置き換えます。 $input.{property_name}

テスト API ワークフロー

API ワークフローとの連携を成功させるには、ワークフローを早い段階から頻繁にテストします。定期的なテストを行うことで、エラーをすばやく特定して解決できます。IntelliSense、オートコンプリート、Autopilot、アクティビティ テストの入力画面などの機能は、テスト データによって異なります。[テスト] ボタンを使用してワークフローを定期的に実行し、このデータを生成します。

テストによって以下が保証されます。

• ワークフロー ステップ間のデータ マッピングが正しく、予期しない動作が防止されている。
• API 要求が適切に設定され、応答の信頼性が確保されます。
• ワークフローは意図したとおりに実行されるため、運用環境で予期しないエラーが発生するリスクが軽減されます。

実行結果に関する情報を理解する

[実行結果] パネルには、ワークフローの実行に関する詳細情報が表示されます。

アクティビティの入力データと出力データ

このデータは、選択したアクティビティごとに利用でき、以下を提供します。

• 入力データ—ステップが前のアクティビティから受け取る情報。
• 出力データ—現在のステップで生成され、次のアクティビティに渡される情報。

入力/出力データを確認して、正確なマッピングとデータ変換を確認します。

API 要求情報

ワークフローが API と対話する場合は、次の要求の詳細を確認します。

• 要求 URL—動的 URL パラメーターが正しく解決されることを確認します。
• ヘッダー—認証ヘッダーと content-type ヘッダーが適切に設定されていることを確認します。
• クエリパラメータ—フィルターとパラメーターの形式が正しいことを確認します。
• 本文の内容—JSON 構造が API 要件に一致していることを検証します。

成功した API 要求

API 要求が成功したら、各手順を展開して確認します。

• リクエストの詳細—URL、ヘッダー、クエリ パラメーター、本文の内容。
• 回答の詳細—ステータス コード、ヘッダー、応答コンテンツ。
• 出力データ—後続のワークフロー ステップで使用するための API 呼び出しによって生成された情報。

デバッグ

ワークフローのエラーを効率的に特定してデバッグするには、次のガイドラインに従ってください。

• エラー インジケーター
  • ステップでエラーが発生すると、エラー アイコンが表示されます。
  • ステップを選択すると、詳細なエラー メッセージと出力が表示されます。
• 一般的なデバッグ手順
  • API 要求の検証 — URL、ヘッダー、パラメーター、本文の内容などの要求の詳細が API ドキュメントと一致していることを確認します。
  • エラー メッセージを確認する - 認証エラー、誤ったペイロード、またはスクリプトの誤りに関する手がかりがないか、エラー メッセージを調べます。

デバッグ構成の追加

API ワークフローを反復的に構築およびテストし、新しいアクティビティを追加するたびに各ステップを検証できます。これらのテストを効果的に実行するために、 デバッグ構成 機能を使用して特定の入力データを定義できます。これにより、一度設定した JSON 入力を、その後のすべてのテスト実行で再利用できます。ワークフローの実行中に、 $workflow.input オブジェクトを介してエミュレートされたデータにアクセスできます。

デバッグ構成を追加するには、次の手順を実行します。

1. API ワークフロー デザイナー キャンバスの上部で [デバッグ] ドロップダウンを開き、[ デバッグ構成] を選択します。
2. In the window that opens, provide the test input data in the available fields, or upload a JSON payload.
3. テストの設定を保存します。
4. 保存すると、[式エディター] で参照 $workflow.input.{propertyname}を使用してテスト設定にアクセスできます。さらに、デバッグ設定は [式エディター] の [アクティビティ テスト] 入力 パネルにも表示されます。

API ワークフローをデバッグする

API ワークフローをデバッグするには、以下の手順を実行します。

1. API ワークフローを開きます。ワークフローが完全に設定され、実行できる状態になっていることを確認します。
2. ワークフローが入力データ (外部システムからのものなど) に依存する場合は、テスト前に デバッグ構成 を定義します。これにより、すべてのステップで必要なデータが確実に受信されます。
3. ワークフローをデバッグします。[ デバッグ] ボタンはページの上部にあります。このファイルを選択すると、ワークフローが実行され、リアルタイムの結果を確認できます。
4. デバッグが開始されると、画面の右側に [実行結果 ] パネルが表示されます。ここで、各ステップの実行ステータスに成功、失敗、保留中として明確にマークされています。

API ワークフローをパブリッシュする

大事な： パブリッシュする前に、成功シナリオと失敗シナリオの両方を使用して API ワークフローをテストし、各シナリオが正しく実行されることを確認します。

API ワークフロー ソリューションをパブリッシュするには、以下の手順を実行します。

1. API ワークフロー デザイナー キャンバスで、[ パブリッシュ] を選択します。
2. API ワークフローをパブリッシュする場所を選択します。
   • Orchestrator 個人用ワークスペース フィード
   • Orchestrator テナント フィード
3. 変更ログやバージョンなど、API ワークフローにとって重要なその他の詳細情報を入力します。
4. [ パブリッシュ] を選択します。API ワークフローのパブリッシュが成功したことを知らせる通知が表示されます。

個人用ワークスペース フィードにパブリッシュした場合、ワークフローは Orchestrator の [マイ ワークスペース] > [オートメーション] > [プロセス] の下に表示されます。API ワークフローは、 API の種類で識別できます。

テナント フィードにパブリッシュした場合は、Orchestrator の [ テナント] > [ソリューション] にワークフローが表示されます。API ワークフローは、 API の種類で識別できます。

API ワークフローをデプロイする

API ワークフローを任意のフィードにパブリッシュしたら、ソリューションをデプロイする必要があります。

個人用ワークスペース フィードから API ワークフローをデプロイする

個人用ワークスペースにパブリッシュすると、API ワークフローがプロセスとして Orchestrator > [マイ ワークスペース] > [API ワークフロー名] > [オートメーション] > [プロセス] のサブフォルダーに準備されます。

大事な： 個人用ワークスペース フォルダー内に専用のサブフォルダーが自動的に作成されます。

テナント フィードから API ワークフローをデプロイする

Orchestrator テナントにパブリッシュすると、API ワークフロー パッケージが Orchestrator >テナント > ソリューションにアップロードされます。

プロセスとしてデプロイするには、以下の手順を実行します。

1. Orchestrator の > テナント >ソリューション] に移動します。
2. テナント フィードにパブリッシュした API ワークフロー パッケージの 3 点リーダー メニューを選択し、[ パッケージをデプロイ] を選択します。
3. ソリューション バージョンのデプロイ ウィザードで、次の詳細を設定します。
   1. デプロイ名 - プロセスについて記載、表示、監視しているすべてのページに表示する名前を追加します。何も指定しない場合は、パッケージの名前が使用されます。
   2. コピー先フォルダー - ソリューションのルートの親フォルダーとして使用するフォルダーを指定します。ソリューションは選択したフォルダーにはデプロイされませんが、新しい子フォルダーが作成されます。
   3. テナント下の新しいルート フォルダーとしてインストール - このチェックボックスをオンにすると、ソリューションが現在のテナント下の新しいルート フォルダーとしてインストールされます。
   4. ソリューションのルート フォルダー名 — ルート フォルダー名を変更します。
4. [ レビュー] を選択します。これで、ソリューションを下書きとして保存したり、検証して操作を続行したりできます。
5. [ デプロイ] を選択します。これで、ワークフローは、手順 3 > [オートメーション] > [プロセス] で指定したフォルダーにプロセスとして格納されます。API ワークフローは API タイプで識別できます。
6. [ デプロイをアクティブ化 ] を選択して、API ワークフローのデプロイを完了します。

ベスト プラクティス

• 明確な 入力 スキーマと 出力 スキーマを定義し、他の UiPath 製品がワークフローを理解して操作できるようにします。
• API ワークフローの迅速な実行速度を利用して、設計時に入出力ペイロードをテストします。
• Autopilot を使用して、コンテキストに対応した式と JavaScript コードを生成します。
• [式エディター] の出力パネルで式を検証し、実行前に構文やロジックの問題をキャッチします。
• [実行結果] パネルで入力データと出力データを操作するには、値を展開、折りたたむ、またはクリップボードにコピーします。
• [成功] または [失敗] のいずれかの [応答] アクティビティを設定して、ワークフローを早期に終了します。
• ループ内の アクティビティ、 つまり [繰り返し (コレクション の各要素)] と [ 繰り返し (後判定)] で、 $context の代わりに $input を使用して前のオブジェクトの出力にアクセスします。
• コネクタが必要な機能が提供されない場合に API を直接呼び出すには、[ HTTP ] アクティビティを使用します。ネイティブの [HTTP ] アクティビティまたはコネクタ固有の [HTTP 要求 ] アクティビティのいずれかを選択します。
• Using the UiPath Orchestrator connector, you can now access assets and credentials, which can then be securely used in request headers.
• [HTTP アクティビティのヘッダー] プロパティに認証トークンを指定します。

  { 
      Authorization: "<my_token>",
      "Content-Type": "application/json"
  }

  基本認証の場合は、以下を使用します。

  { Authorization: "Basic " + btoa("<username>:<pass>")}