概要
この記事は、UiPath Integration Service でお問い合わせの多い事象を、質問ごとに「原因」と「解決策」に分けてそれぞれまとめたものです。
テクニカルサポートへお問い合わせいただく際にご提供いただきたい情報は、最後にまとめています。事象の切り分けやお問い合わせ前の確認にご活用ください。
注：この投稿は個人の見解であり、所属組織・団体を代表するものではございません。
質問1: Integration Service のコネクションを作成できない、またはコネクションが切断される
原因
コネクションの作成や更新で失敗する場合、主な原因は認証情報、権限、スコープ、またはコネクション先サービス側の設定にあります。
Integration Service のコネクションは、対象サービスの API へアクセスするための認証情報を保持します。そのため、次のような状態ではコネクションが失敗したり、作成済みのコネクションが切断状態になったりします。
- 入力したユーザー名、パスワード、API キー、Personal Access Token、OAuth クライアント情報が正しくない
- 対象サービス側で必要な権限やロールが不足している
- OAuth コネクションで必要なスコープが許可されていない
- 対象サービス側でアカウント、アプリ登録、API 利用設定が無効化されている
- 対象サービス側で多要素認証、IP 制限、条件付きアクセスなどのセキュリティ設定が追加されている
解決策
まず、Integration Service のコネクション画面で対象のコネクション状態を確認します。
- Automation Cloud にサインインします。
- 画面左上のテナント切り替えで、事象が発生しているテナントを選択します。
- Integration Service を開きます。
- コネクションを開きます。
- 検索欄でコネクター名またはコネクション名を検索します。
- 該当するコネクションの状態を確認します。正常な場合は、有効なコネクションとして表示されます。切断、期限切れ、エラーなどの状態が表示されている場合は、コネクション情報またはコネクション先サービス側の認証に問題がある可能性があります。
- コネクションを開き、表示されているエラーメッセージを確認します。エラー本文、コネクション名、コネクター名、確認日時を控えてください。
- コネクション画面に再認証に相当する操作が表示されている場合は、同じ認証情報で再認証します。
- 再認証後、コネクション状態が有効に戻るか確認します。有効に戻らない場合は、認証情報、スコープ、権限、コネクション先サービス側の設定を確認します。
- コネクションを再作成する場合は、既存のコネクションを利用しているトリガーやワークフローがないか事前に確認します。
次に、対象サービス側の設定を確認します。
- 対象サービスの画面に、コネクションで使用しているユーザーまたはアプリ資格情報でログインできるか確認します。
- 対象サービス側で、アカウントが無効化、ロック、パスワード期限切れになっていないか確認します。
- 対象サービス側で、API 利用に必要な権限またはロールが付与されているか確認します。参照、作成、更新、削除など、実行したい操作に必要な権限を個別に確認してください。
- OAuth を使用している場合は、対象コネクターの公式ドキュメントに記載されたスコープが許可されているか確認します。
- 対象サービス側で、API 利用設定、アプリ登録、クライアント ID、クライアントシークレット、リダイレクト URL が変更されていないか確認します。
- 対象サービス側で、IP 制限、条件付きアクセス、多要素認証、レート制限などのセキュリティ設定が追加されていないか確認します。
- 対象サービス側の管理画面や監査ログで、UiPath からの認証試行が拒否されていないか確認します。
コネクションを作り直す場合は、既存のコネクションを利用しているワークフロー、トリガー、アクティビティがあるかも確認してください。コネクションを削除または変更すると、それを参照している自動化に影響する場合があります。
質問2: Integration Service のトリガーが発火しない
原因
トリガーが発火しない場合、主にコネクション状態、トリガーの有効化状態、対象サービス側の権限、フィルター条件、または外部サービス側のイベント発生状況を確認します。
Integration Service のトリガーは、コネクション先サービスのイベントやデータ変更をもとに自動化を開始します。コネクションが切断されている場合、関連するトリガーは一時的に停止します。コネクションを再確立すると、トリガーは再開されますが、トリガー自体が無効化されていないかも確認が必要です。
また、ポーリング型のトリガーでは、イベント発生から検出までに時間差が出ます。トリガー単位ではなくコネクションレベルで定義されたポーリング間隔が、そのコネクションに紐づくトリガーへ適用されます。さらに、サードパーティーアプリケーション側の問題によりポーリングで 100 回連続エラーが発生した場合、システム安定性のためトリガーが自動的に無効化されることがあります。
解決策
次の順番で確認します。
- Automation Cloud で、事象が発生しているテナントを開きます。
- Integration Service を開きます。
- コネクションを開き、トリガーが使用しているコネクションを検索します。
- コネクション状態を確認します。切断、期限切れ、エラーの状態であれば、先にコネクションを再認証します。
- コネクションが有効な場合は、同じコネクションを使っている他のワークフローやアクティビティが動作するか確認します。他の処理も失敗する場合は、トリガーではなくコネクションまたは対象サービス側の問題である可能性が高くなります。
- トリガーを開き、該当トリガーを検索します。
- トリガーが有効化されているか確認します。無効の場合は有効化します。
- トリガーに紐づくプロセス名、コネクション名、コネクター名が想定どおりか確認します。似た名前のコネクションや別テナントのコネクションを参照していないか注意してください。
- トリガーの設定画面を開き、フィルター条件、監視対象のオブジェクト、イベント種別を確認します。
- 対象サービス側で、フィルター条件に一致するイベントを実際に発生させます。たとえば「新規レコード作成」で発火するトリガーであれば、対象サービス側で新規レコードを作成します。
- 対象サービス側で、コネクションで使用しているユーザーまたはアプリがそのイベント対象データを参照できるか確認します。管理者では見えるがコネクションで使用しているユーザーでは見えない、という権限差に注意してください。
- Orchestrator のジョブを開き、該当時間帯にジョブが作成されていないか確認します。ジョブが作成されている場合は、トリガーは発火しており、以降はジョブ失敗として切り分けます。
- Webhook 型のトリガーを利用している場合は、対象サービス側で Webhook 登録が有効か、削除または無効化されていないか確認します。
- ポーリング型のトリガーでは、イベント発生からジョブ作成までに時間差が出る場合があります。発生直後だけで判断せず、トリガーの仕様に応じて一定時間待ってから確認します。
- イベントトリガーの場合は、Orchestrator のトリガー詳細から Traces を確認します。ポーリング実行または Webhook 受信が記録されているか、イベントデータを受信しているか、フィルター条件に一致したイベントがあるかを確認します。
- Traces でイベントは一致しているがジョブが作成されていない場合は、トリガーではなくジョブ作成側の問題として、トリガー詳細の History、Orchestrator のジョブ、ロボット、ライセンス、フォルダー権限を確認します。
フィルター条件を設定している場合は、一時的に条件を緩めて、トリガーが発火するか確認すると切り分けしやすくなります。ただし、本番環境で条件を変更する場合は、意図しないジョブ起動が起きないよう、影響範囲を確認してから実施してください。
Traces タブに表示される情報は、トリガーの最新バージョンに対する情報です。トリガーを編集すると、編集前のバージョンに対する Traces は同じタブでは確認できなくなるため、調査中は編集前に必要な情報を控えてください。
デバッグ実行と実際にデプロイされたトリガーでは、確認している時間範囲や実行経路が異なる場合があります。「デバッグでは一致するが、実運用では発火しない」場合は、デバッグ結果だけで判断せず、デプロイ済みトリガーの設定、コネクション、フォルダー、実行ユーザー、Traces、ジョブ履歴を合わせて確認してください。
質問3: トリガーを追加、無効化、削除しようとするとエラーになる
原因
トリガー操作時に 400 エラーが発生する場合、公式ドキュメントでは、対象のコネクションが正常でない状態または非アクティブな状態である可能性が案内されています。
参考：
トリガーはコネクションと紐づいて動作するため、コネクションが切断されている場合や認証情報が失効している場合、トリガーの追加、無効化、削除に失敗することがあります。
解決策
まずコネクション状態を修復します。
- Automation Cloud で、事象が発生しているテナントを開きます。
- Integration Service を開きます。
- コネクションを開きます。
- トリガーが使用しているコネクションを検索し、コネクション名、コネクター名、コネクション状態を確認します。
- コネクションが切断、期限切れ、エラー状態の場合は、コネクション詳細を開き、表示されているエラーを控えます。
- コネクション画面から再認証します。再認証後、コネクション状態が有効に戻ったことを確認します。
- 再認証できない場合は、対象サービス側の認証情報、権限、スコープ、アプリ登録、IP 制限を確認します。
- コネクションが有効になった後、トリガーに戻ります。
- 該当トリガーを開き、コネクション欄で有効なコネクションを参照しているか確認します。
- トリガーの追加、無効化、削除を再実行します。
- 同じエラーが続く場合は、エラーコード、エラーメッセージ、操作日時、対象トリガー名を控えます。
コネクションを再作成した場合は、トリガーが古いコネクションを参照していないか確認してください。必要に応じて、新しいコネクションを使用してトリガーを作成し直します。
質問4: Integration Service アクティビティがタイムアウトする、または大量データ取得で失敗する
原因
Integration Service には、アクティビティやトリガーの実行時間、レスポンスサイズなどに関する制限があります。公式ドキュメントでは、JSON 形式のデータ処理上限は 8 MB、JSON 外で扱われるファイルの上限は 1 GB、Integration Service コネクターを利用するアクティビティとトリガーのタイムアウトは 120 秒と案内されています。
大量のレコードを一度に取得する処理や、コネクション先 API の応答に時間がかかる処理では、次のような事象が発生することがあります。
- タイムアウトエラーになる
-
Response content too largeのようなエラーになる - 一部のレコード取得で失敗する
- 実行時間が安定しない
解決策
取得対象を小さくし、API 呼び出しを分割します。
- Studio または Studio Web で、失敗しているアクティビティを開きます。
- アクティビティ名、コネクター名、使用しているコネクション名を確認します。
- アクティビティの設定で、取得件数、最大レコード数、検索条件、フィルター、日付範囲を確認します。
- まず取得件数を小さくします。たとえば全件取得ではなく、10 件や 100 件など小さい件数で成功するか確認します。
- WHERE 句、検索条件、日付範囲、ステータスなどのフィルターを追加し、取得対象を絞ります。
- 一度に全件を取得せず、期間、ステータス、ID 範囲などで分割して複数回に分けます。
- ファイルや大きなデータを JSON 内の Base64 として扱っている場合は、レスポンスサイズ制限に該当しないか確認します。
- コネクション先サービス側の API ドキュメントで、ページング仕様、レート制限、タイムアウト、1 回のレスポンスサイズ制限を確認します。
- 同じ条件で対象サービス側の画面または API テストツールから取得できるか確認します。対象サービス側でも遅い、または失敗する場合は、対象サービス側の API 制限やデータ量が原因の可能性があります。
- 小さい件数では成功し、大きい件数でのみ失敗する場合は、取得条件を分割する設計へ変更します。
- トリガーで大きなイベントペイロードを扱っている場合も、同じデータ処理上限に該当する可能性があります。イベント本文、添付ファイル、HTML メール本文、Base64 化されたファイルなど、ペイロードを大きくする要素がないか確認します。
特定のコネクターで標準アクティビティが目的の API 操作に対応していない場合は、公式ドキュメントでそのコネクターが 『HTTP要求』アクティビティに対応しているか確認します。ただし、『HTTP要求』アクティビティにも対応コネクターやコンテンツタイプなどの制限があります。
質問5: Studio で Integration Service アクティビティの入力項目やドロップダウンが期待どおり表示されない
原因
Integration Service アクティビティでは、コネクション先サービスのメタデータ、コネクション情報、選択したオブジェクト、権限に応じて入力項目が表示されます。そのため、コネクション先サービス側で権限が不足している場合や、コネクションが無効な場合、期待する項目が表示されないことがあります。
また、Integration Service のアクティビティには複数の種類があります。コネクタ別のIntegration Service系パッケージ、Dynamic Activity Packageなどで、コネクション方法や表示のされ方が異なる場合があります。
参考：Integration Serviceアクティビティの種類
https://qiita.com/ts_saito/items/17dfb80bf145210519d9#integration-service%E3%82%A2%E3%82%AF%E3%83%86%E3%82%A3%E3%83%93%E3%83%86%E3%82%A3%E3%81%AE%E7%A8%AE%E9%A1%9E
Studio Desktop、Studio Web、Maestro、API Workflow など、どの画面で使用しているかによって、同じコネクターでも設定画面や入力項目の表示が異なる場合があります。まず「どの製品画面で、どのアクティビティパッケージを、どのコネクションで使っているか」を切り分けください。
解決策
次の手順で確認ください。
- Studio または Studio Web で、対象プロジェクトを開きます。
- 失敗している、または項目が表示されないアクティビティを選択します。
- アクティビティ名、コネクター名、コネクション名を確認します。
- Studio Desktop の場合は、プロジェクトの依存関係からアクティビティパッケージ名とバージョンを確認します。
- Automation Cloud の Integration Service を開き、コネクション で同じコネクション名を検索します。
- コネクション状態が有効か確認します。切断またはエラー状態の場合は、先にコネクションを再認証します。
- Studio 側に戻り、対象アクティビティでコネクションを選び直します。
- オブジェクト、レコード種別、項目一覧、ドロップダウンを再読み込みできる場合は再読み込みします。
- 対象サービス側にコネクションで使用しているユーザーでログインし、表示されないオブジェクトや項目を同じユーザーで参照できるか確認します。
- 対象サービス側で、コネクションで使用しているユーザーに対象オブジェクト、項目、レコードへの参照権限があるか確認します。管理者では見えるがコネクションで使用しているユーザーでは見えない場合、権限不足の可能性があります。
- 対象コネクターの公式ドキュメントで、前提条件、必要な権限、サポートされるオブジェクトや操作を確認します。
- カスタムコネクターの場合は、Connector Builder の定義で入力、出力、表示名、パラメーター、データ型が正しく設定されているか確認します。
- コネクターやアクティビティパッケージを更新した直後の場合は、Studio またはブラウザーを再起動し、パッケージやメタデータを再読み込みしてから再確認します。
※一時的な表示不整合の切り分けとして、コネクションの再選択/再作成、Studio の再起動、アクティビティパッケージの更新、別の小さなテストプロジェクトでの再現確認も有効です。
質問6: Connector Builder で作成したカスタムコネクターが期待どおり動作しない
原因
Connector Builder では、外部 API の認証、ベース URL、リソース、メソッド、パラメーター、入力と出力の定義を構成します。カスタムコネクターが期待どおり動作しない場合、設定値と実際の API 仕様が一致していない可能性があります。
よくある原因は次のとおりです。
- ベース URL が対象 API の仕様と一致していない
- パスパラメーター、クエリパラメーター、ヘッダーの指定が API 仕様と異なる
- 認証方式の選択が API 仕様と一致していない
- トークンや API キーの渡し方が異なる
- API 側で必要なスコープや権限が不足している
- Connector Builder または HTTP 要求アクティビティの制限に該当している
解決策
まず、対象 API の公式仕様と Connector Builder の設定を突き合わせます。
- 対象 API の公式ドキュメントを開きます。
- API のベース URL、対象エンドポイント、HTTP メソッドを確認します。
- 認証方式を確認します。API キー、Personal Access Token、OAuth など、対象 API が要求する方式と Connector Builder の設定が一致しているか確認します。
- トークンや API キーを渡す場所を確認します。ヘッダー、クエリパラメーター、ボディのどこに渡す仕様かを確認してください。
- 必須ヘッダー、クエリパラメーター、パスパラメーター、リクエストボディの形式を確認します。
- Connector Builder を開き、対象コネクターを選択します。
- 設定でベース URL と認証方式を確認します。
- 対象リソースを開き、パス、HTTP メソッド、パラメーター、入力、出力の定義を確認します。
- Connector Builder のテストリクエストで、最小限の入力値を指定して送信します。
- レスポンスのステータスコード、エラー本文、レスポンスボディを確認します。
- 401 または 403 系のエラーであれば、認証情報、スコープ、権限を確認します。
- 404 系のエラーであれば、ベース URL、パス、パスパラメーターを確認します。
- 400 系のエラーであれば、必須パラメーター、データ型、ボディ形式を確認します。
- 429 系のエラーであれば、対象 API のレート制限を確認します。
- Connector Builder のテストで成功した後、コネクターを公開します。
- Studio または Studio Web で新しいテストプロジェクトを作成し、公開したコネクターを使って最小構成で実行します。
- 最小構成で成功した後、実際のワークフローに組み込みます。
API 定義ファイルがある場合は、Connector Builder の API 定義から開始する方法も検討してください。手動設定よりも、エンドポイントやパラメーターの転記ミスを減らせます。
参考：API定義からコネクターを構築する
質問7: テクニカルサポートへ問い合わせる前に、どの情報を集めればよいか
Integration Service の問題は、コネクション、トリガー、アクティビティ、対象サービス側 API、権限、データ量、制限のいずれかに起因することが多いです。事象の切り分けには、発生箇所と時間帯、使用しているコネクション、エラー全文、実行ログが重要です。
お問い合わせ前に、可能な範囲で次の情報を共有ください。
- 何を実行したときに失敗したか
- いつから発生しているか
- 毎回発生するか、断続的に発生するか
- 以前は成功していたか
- 直前に変更した設定、パッケージ、権限、コネクション情報があるか
- コネクション、トリガー、アクティビティ、対象サービス側 API のどこで失敗しているように見えるか
- 確認できる場合は、コネクション ID、トリガー ID、ジョブ ID
画面で確認する場合は、次の手順で確認ください。
- Automation Cloud で、事象が発生している組織とテナントを開きます。別テナントを見ていないか、最初に確認してください。
- Integration Service のコネクションを開き、対象コネクター名またはコネクション名で検索します。コネクション状態、コネクション名、認証方式、表示されているエラーを確認します。
- Integration Service のトリガーを開き、対象トリガーを検索します。トリガーが有効か、参照しているコネクションが正しいか、紐づくプロセスが正しいかを確認します。トリガー詳細画面の URL または画面上の ID 表示から、トリガー ID も控えます。
- トリガー設定を開き、監視対象のオブジェクト、イベント種別、フィルター条件を確認します。発火しないイベントがフィルター条件に一致しているか確認してください。
- Orchestrator のジョブを開き、対象フォルダー、プロセス名、実行時間帯で絞り込みます。ジョブが作成されていればトリガーは発火しており、ジョブ失敗またはワークフロー内のエラーとして確認します。
- 失敗したジョブを開き、ジョブ ID、ジョブ詳細、エラー概要、ログを確認します。エラーが発生したアクティビティ名、エラー全文、発生時刻を控えます。
- Automation Cloud の管理 > 組織 > 監査ログを開き、該当時間帯のコネクション作成、コネクション更新、コネクション削除、トリガー作成、トリガー更新、トリガー無効化の操作を確認します。
- 対象サービス側の管理画面で、コネクションで使用しているユーザーの権限、API 利用権限、OAuth スコープ、Webhook 登録、レート制限、障害情報を確認します。
- 可能であれば、最小構成で再現確認します。たとえば、取得件数を少なくする、フィルター条件を単純にする、テスト用レコードを 1 件だけ作成するなど、影響範囲を小さくして確認します。
お客様への依頼事項
テクニカルサポートへは、次の形式で可能な範囲でできるだけ多くの情報をご提供ください。
■ 発生している事象
■ 発生日時とタイムゾーン
■ Automation Cloud 組織名
■ テナント名
■ コネクター名
■ コネクション名
■ コネクション ID
■ トリガー名
■ トリガー ID
■ プロセス名
■ ジョブ ID
■ Studio の種類とバージョン
■ アクティビティ名
■ アクティビティパッケージ名とバージョン
■ エラーメッセージ全文
■ 再現手順
1.
2.
3.
■ 期待する結果
■ 実際の結果
■ 直前に変更した内容
■ 添付資料
- コネクション画面のスクリーンショット
- トリガー設定画面のスクリーンショット
- Orchestrator ジョブログ
- Automation Cloud 監査ログ
- 対象サービス側でイベントや API エラーが確認できる資料
注：認証情報、API キー、アクセストークン、個人情報、業務データは、テクニカルサポートへお問い合わせ前にマスクしてください。