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

入力パラメーターの設定、ワークフローの設計、API 呼び出しの統合など、API ワークフロー ソリューションを Studio Web で作成および管理します。

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

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

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

入力スキーマを定義する

API ワークフローでは通常、呼び出し元からの入力が必要です。それには、入力と出力の両方に JSON オブジェクトを定義し、それぞれが JSON スキーマに従います。これらのスキーマにより、オブジェクトのデータ型と構造が確立されます。定義済みのオブジェクトには、入れ子になったオブジェクト、複数のプロパティ、および配列を含めることができるため、必要に応じて複雑なデータ構造をモデル化できます。

入力スキーマは、ワークフローをトリガーするときに外部サービスが提供する必要があるデータ構造を指定します。

入力スキーマを設定するには、JSON ペイロードをアップロードするか、入力パラメーターを手動で定義します。

1. API ワークフロー プロジェクトで、[ データ マネージャー ] パネルを開きます。
2. [ 入力 ] タブを選択します。JSON スキーマをアップロードするには、手順 3 を実行します。入力パラメーターを手動で定義するには、手順 4 に従います。
3. 入力パラメーターが定義済みの JSON スキーマをアップロードするには、[ ペイロードから生成] を選択します。
   1. 必要な入力を JSON で指定します。
   2. [ スキーマを生成] を選択します。
   3. 生成されたスキーマを確認し、必要に応じてプロパティに説明を追加します。
4. 入力パラメーターを手動で定義するには、[ プロパティを追加] を選択します。
   1. プロパティの詳細を設定します。
      • 名前 - プロパティ キーを定義します
      • 型 - [文字列]、[数値]、[整数]、[ブール値]、[オブジェクト]、[配列]、[日時]、[日付]、[時刻] から選択します。
        重要:

        オブジェクトまたは配列を使用する場合は、入れ子にする項目のプロパティを定義します。

      • 必須 - プロパティを必須としてマークするには、このボックスを選択します。
   2. すべての入力パラメーターを定義するまで、この手順を繰り返します。

出力スキーマを定義する

出力スキーマは、API ワークフローによって返されるデータの構造を定義し、ワークフローを呼び出すすべてのサービスが出力形式を事前に理解できるようにします。また、ワークフローに 応答 アクティビティが含まれている場合、呼び出し元に送り返される正確なデータを決定するためにも必要です。

注:

現在のところ、スキーマの検証は適用されないため、[応答] アクティビティで返されるデータに含まれるプロパティが、出力スキーマで定義されたプロパティよりも多かったり少なかったりしても、ワークフローが失敗することはありません。

出力スキーマには、スキーマ自体の中で明示的に定義されたフィールド (ID やユーザーが指定した値など) と、ワークフロー ステップから動的に生成された出力 (API 応答や計算値など) が含まれます。

出力スキーマは、JSON ペイロードをアップロードするか、出力パラメーターを手動で定義して設定できます。

1. API ワークフロー プロジェクトで、[ データ マネージャー ] パネルを開きます。
2. [ 出力 ] タブを選択します。JSON スキーマをアップロードするには、手順 3 を実行します。出力パラメーターを手動で定義するには、手順 4 に従います。
3. 出力パラメーターが定義済みの JSON スキーマをアップロードするには、[ ペイロードから生成] を選択します。
   1. 期待される出力を JSON に指定します。
   2. [ スキーマを生成] を選択します。
   3. 生成されたスキーマを確認し、必要に応じてプロパティに説明を追加します。
4. 出力パラメーターを手動で定義するには、[ プロパティを追加] を選択します。
   1. プロパティの詳細を設定します。
      • 名前 - プロパティ キーを定義します
      • 型 - [文字列]、[数値]、[整数]、[ブール値]、[オブジェクト]、[配列]、[日時]、[日付]、[時刻] から選択します。
        重要:

        オブジェクトまたは配列を使用する場合は、入れ子にする項目のプロパティを定義します。

      • 必須 - プロパティを必須としてマークするには、このボックスを選択します。
   2. すべての出力パラメーターを定義するまで、この手順を繰り返します。

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

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

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

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

パネル	説明
入力	メイン パネルは入力パネルで、ここで JavaScript 式または JQ 式を記述します。このパネルには、式の構文のエラーを特定して強調表示する構文チェッカーが組み込まれています。
Autopilot 式ジェネレーター	Located at the bottom of the input panel, the Autopilot expression generator helps you create workflow expressions using natural language, instead of writing JavaScript. Autopilot understands the context of your workflow, and enables you to reference objects and workflow steps by describing your desired outcome.
アクティビティのテスト入力	To the right-hand side of the code panel, the Activity test input panel lets you review test data generated from previous workflow runs. It provides sample data you can use to build and validate expressions, and it interacts directly with the Expression output panel to ensure your expressions produce the desired results.
式の出力	The Expression output panel displays the result of your expression based on the data from the Activity test input data. This lets you validate that your expression generates the expected outcome. If your expression has errors, the Expression output section highlights the problematic expression and provides a corresponding error message. The result updates automatically whenever you modify the expression in the input panel.

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

ワークフロー データにはいくつかのアクセス ポイントがあります。

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

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

アクセスポイント	説明	列の合計
$workflow.input	要求スキーマと、テスト コンフィギュレーションで定義されたすべての値を格納します。	式エディター内でテストの設定データにアクセスするには、次の構文を入力し、{property_name} を参照する特定のプロパティに置き換えます。 $workflow.input.{property_name}
$context	各アクティビティの入力データと出力データを格納します。式でこれらのプロパティを参照するには、まずワークフローを実行してデバッグします。これにより、ステップレベルの入力と出力が生成され、[ テスト入力 ] 画面に表示されます。	特定のステップの出力応答データにアクセスするには、[ 式エディター] で次の構文パターンを使用し、 {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 ヘッダーが適切に設定されていることを確認します。
• クエリ パラメーター - フィルターとパラメーターが正しい形式であることを確認します。
• [Body Content]:JSON 構造が API 要件に一致していることを検証します。

成功した API 要求

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

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

デバッグ

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

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

デバッグ構成の追加

You can build and test your API workflow iteratively, validating each step as you add new activities. To run these tests effectively, you can define specific input data using the Debug configuration feature. This lets you set a JSON input once and reuse it across all subsequent test runs. You can access the emulated data through the $workflow.input object during workflow execution.

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

1. API ワークフロー デザイナー キャンバスの上部で [デバッグ] ドロップダウンを開き、[ デバッグ構成] を選択します。
2. 開いたウィンドウで、利用可能なフィールドにテスト入力データを指定するか、JSON ペイロードをアップロードします。
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 要求 ] アクティビティのいずれかを選択します。

• UiPath Orchestrator コネクタを使用してアセットと資格情報にアクセスできるようになり、それらを要求ヘッダーで安全に使用できるようになりました。

• [HTTP アクティビティのヘッダー] プロパティに認証トークンを指定します。

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

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

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