アウトバウンド REST Web サービスのトラブルシューティング - Support and Troubleshooting

アウトバウンド REST Web サービスのトラブルシューティング Issue .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Table of Contents 1. 問題 — この記事の対象範囲 2. 症状の簡易トリアージ 3. アウトバウンドコールのライフサイクル 4. 汎用診断チェックリスト 5. よくある問題のカテゴリ 5.1 接続障害と TLS エラー 5.2 認証と承認の失敗 5.3 タイムアウトと応答遅延 5.4 エンドポイントエラー (4xx/5xx) 6. アウトバウンド HTTP ログの有効化と読み取り方法 詳細ログの有効化 ログレコードの読み取り ノードログへのトレース 7. HTTP ステータスコードクイックリファレンス 8. 関連記事 1. 問題 — この記事の対象範囲 アウトバウンド Web サービスコールは、ServiceNow インスタンスから発信され、サードパーティのエンドポイントに送信されます。この記事は、コールがエンドポイントに到達しない、予期しない応答が返される、タイムアウトする、MID Server ルーティングパスの途中で失敗するなど、アウトバウンド方向のあらゆる障害をトラブルシューティングするための出発点です。

対象となる症状:

応答なし、接続拒否、またはソケットタイムアウト (HTTP 0 または -1) TLS/証明書のハンドシェイクエラー エンドポイントから返される 401 Unauthorized または 403 Forbidden 完了前にタイムアウトする遅い応答またはコール リモートエンドポイントから返される 4xx または 5xx エラーコード MID Server の ECC キューがリクエストを処理しない この記事の使い方

この記事はハブ記事です。まずセクション 2 の症状の簡易トリアージを参照し、該当する詳細記事のリンクに従ってください。

2. 症状の簡易トリアージ 左列で症状を確認し、右列の記事を参照してください。以下の図は同じ判断ロジックを視覚的に示しています。

現象 最も考えられる原因 参照先 HTTP 0 または -1、ソケットタイムアウト、接続拒否 エンドポイント到達不能、ファイアウォールブロック、DNS 障害 以下のセクション 5.1、およびアウトバウンド Web サービス — 接続障害と TLS エラー TLS ハンドシェイクエラー、信頼されていない証明書、SSL 例外 sys_certificate または MID Server の CACert ファイルに証明書が存在しないか信頼されていない 以下のセクション 5.1、およびアウトバウンド Web サービス — 接続障害と TLS エラー エンドポイントから 401 Unauthorized が返される 無効または期限切れの認証情報、Authorization ヘッダーの欠落、OAuth トークンの問題 以下のセクション 5.2、およびアウトバウンド Web サービス — 認証と承認の失敗 エンドポイントから 403 Forbidden が返される エンドポイントの権限不足、OAuth スコープの不一致 以下のセクション 5.2、およびアウトバウンド Web サービス — 認証と承認の失敗 コールのタイムアウト、応答遅延、MID Server の 175 秒タイムアウト エンドポイントの遅延、タイムアウト設定、プロキシまたはロードバランサーの遅延 以下のセクション 5.3、およびアウトバウンド Web サービス — タイムアウトと応答遅延 エンドポイントから 400、500、502、または 503 が返される リクエストボディの不正形式、エンドポイント側のエラー、プロキシまたはゲートウェイ障害 以下のセクション 5.4、およびアウトバウンド Web サービス — エンドポイントエラー (4xx/5xx) ECC キューが停止している、「30/60 秒後に応答なし」エラー MID Server がダウンしているか、プローブを取得していない 以下のセクション 5.3、MID Server セクション — アウトバウンド Web サービス — タイムアウトと応答遅延 3. アウトバウンドコールのライフサイクル すべてのアウトバウンドコールは、MID Server が関与するかどうかに応じて 2 つのパスのいずれかをたどります。コールがどちらのパスをたどるかを特定することで、診断範囲をすぐに絞り込めます。

ダイレクトパス (MID Server なし)

スクリプトまたは Flow Designer ステップが、RESTMessageV2 または SOAPMessageV2 オブジェクトの execute() または executeAsync() を呼び出す。 インスタンスが HTTP リクエストをパブリックインターネット経由でサードパーティのエンドポイントに直接送信する。 エンドポイントがリクエストを処理し、HTTP レスポンスを返す。 レスポンスが呼び出し元のスクリプトまたはフローステップに返される。 MID Server 経由

スクリプトまたは Flow Designer ステップが execute() または executeAsync() を呼び出す。 Output RESTProbe または SOAPProbe レコードが ECC キューに挿入される。 MID Server が ECC キューをポーリングし、プローブレコードを取得する。 MID Server がサードパーティのエンドポイントに HTTP リクエストを送信する。 エンドポイントがリクエストを処理し、MID Server に HTTP レスポンスを返す。 MID Server がレスポンスをラップし、Input RESTProbe または SOAPProbe レコードを ECC キューに挿入する。 インスタンスが Input ECC キューレコードを読み取り、呼び出し元のスクリプトまたはフローステップにレスポンスを返す。 障害が集中する箇所

パス 障害が集中するステップ 障害タイプ ダイレクト ステップ 2〜3 ネットワーク、ファイアウォール、TLS、またはエンドポイント側の障害。コールは ServiceNow を出たが宛先で成功しなかった。 MID Server ステップ 2〜3 ECC キューの処理障害。コールが ServiceNow を出なかった。 MID Server ステップ 4〜5 ネットワーク、ファイアウォール、TLS、またはエンドポイント側の障害。コールは MID Server を出たが宛先で成功しなかった。 ダイレクトおよび MID Server ステップ 4 (ダイレクト) / ステップ 6 (MID) 認証の失敗。エンドポイントはコールを受信したが、認証情報を拒否した。 4. 汎用診断チェックリスト 詳細記事を参照する前に、以下の情報を収集してください。準備しておくことで、ほとんどのケースを初回対応で解決できます。

アウトバウンド HTTP ログレコード。 フィルターナビゲーターで [Outbound HTTP Requests] (sys_outbound_http_log) に移動します。URL にエンドポイントの URL が含まれるものでフィルタリングします。レコードを開き、[Request] タブと [Response] タブを確認します。[Response Status] および [Response Time] フィールドをメモします。 トランザクション ID。 同じログレコードから、Transaction ID をコピーします。最初の 12 文字がノードログ内のトランザクションを識別します。 ノードホスト名。 ログレコードの [Source] タブで System ID をメモします。これがコールを処理したノードです。 MID Server の関与。 コールが MID Server を経由するかどうかを確認します。不明な場合は、ECC キュー (ecc_queue) で一致する RESTProbe または SOAPProbe レコードを確認します。 認証タイプ。 REST または SOAP メッセージレコードに設定されている認証タイプ (Basic、OAuth、Mutual Auth、または API Key) をメモします。 外部テスト。 ServiceNow の外部から Postman または cURL を使用して、同じ認証情報とエンドポイントで同じリクエストを実行します。外部でも失敗する場合は、問題は ServiceNow ではなくエンドポイント側にあります。 ログレコードが表示されない場合のデバッグログの有効化

[Outbound HTTP Requests] に移動しても失敗したコールのレコードが見つからない場合、ログが有効になっていない可能性があります。有効化の方法はセクション 6 を参照してください。ログが有効になっているにもかかわらずレコードが表示されない場合、コールが実行されていません。HTTP コールが行われる前のスクリプトまたはフローステップの設定を確認してください。

5. よくある問題のカテゴリ 以下に簡単な概要を示します。実際の診断は詳細記事で行います。

5.1 接続障害と TLS エラー 発生条件: コールが HTTP 0 または -1、ソケットタイムアウト、接続拒否エラー、または TLS/SSL ハンドシェイク例外を返す。アウトバウンド HTTP ログにレスポンスボディが全く表示されない場合もあります。

よくある原因: インスタンスの IP 範囲からエンドポイントに到達できない、ファイアウォールがアウトバウンドトラフィックをブロックしている、DNS 解決の失敗、SSL 証明書が存在しないか信頼されていない。

MID Server に関する注意: コールが MID Server を経由する場合、接続確認は ServiceNow インスタンスではなく MID Server のホストマシンから行われます。インスタンス設定を調査する前に、MID Server ホストからエンドポイントに直接到達できることを確認してください。

次のステップ: アウトバウンド Web サービス — 接続障害と TLS エラー

5.2 認証と承認の失敗 発生条件: エンドポイントが 401 Unauthorized または 403 Forbidden を返す。コールはエンドポイントに正常に到達したが、認証レイヤーで拒否された。

よくある原因: 無効または期限切れの認証情報、アウトバウンドリクエストへの Authorization ヘッダーの欠落、OAuth トークンが更新されない、OAuth スコープが正しくない、Mutual Auth 証明書の不一致。

簡易確認: アウトバウンド HTTP ログの [Request] タブを確認します。Authorization ヘッダーが存在し、値が設定されていることを確認します。存在しない場合は、ServiceNow 側で認証プロファイルの設定が正しくありません。

MID Server に関する注意: MID Server を経由する場合は、アウトバウンド HTTP ログに表示されない可能性がある認証関連のエラーがないか、MID Server のエージェントログも確認してください。

次のステップ: アウトバウンド Web サービス — 認証と承認の失敗

5.3 タイムアウトと応答遅延 発生条件: コールに予想以上の時間がかかる、設定されたタイムアウト時間内に応答が返らない、またはアウトバウンド HTTP ログの [Response Time] の値が大きい。

よくある原因: エンドポイントの処理が遅い、ペイロードが大きい、プロキシまたはロードバランサーの遅延、同期コールのタイムアウト設定、アウトバウンドプローブに対する MID Server の 175 秒のハードタイムアウト。

簡易確認: sys_outbound_http_log の [Response Time] フィールドを確認します。成功ステータスで値が大きい場合はエンドポイントが遅いことを意味します。障害発生時に値がゼロまたは null の場合は、接続が完了しなかったことを意味します。

MID Server に関する注意: MID Server のアウトバウンドコールには、デフォルトで 175 秒のハードタイムアウトが設定されています。これはインスタンス側のタイムアウト設定とは独立しています。エンドポイントが 175 秒以内に応答しない場合、インスタンス側の設定に関わらず MID Server はコールをキャンセルします。

次のステップ: アウトバウンド Web サービス — タイムアウトと応答遅延

5.4 エンドポイントエラー (4xx/5xx) 発生条件: エンドポイントが 400、500、502、または 503 を返す。コールはエンドポイントに到達してレスポンスを受信したが、レスポンスがエンドポイント側の障害を示している。

よくある原因: リクエストボディの不正形式 (400)、エンドポイント側の例外 (500)、MID Server とエンドポイント間のプロキシまたはゲートウェイの障害 (502/503)。

簡易確認: 同じヘッダーとボディを使用して Postman または cURL から同じリクエストを実行します。ServiceNow の外部でも同じエラーが返される場合、問題はエンドポイント側にあります。Postman が成功する場合は、アウトバウンド HTTP ログのリクエストヘッダーとボディを Postman が送信する内容と比較してください。

MID Server に関する注意: 502 または 503 は、エンドポイント自体ではなく、MID Server とエンドポイントの間にあるプロキシから発生する場合があります。MID Server のエージェントログでエラーチェーン全体を確認してください。

次のステップ: アウトバウンド Web サービス — エンドポイントエラー (4xx/5xx)

6. アウトバウンド HTTP ログの有効化と読み取り方法 MID Server 自体が実行するコールを除き、インスタンスからのすべてのアウトバウンドコールはアウトバウンド HTTP ログ (sys_outbound_http_log) に記録されます。アウトバウンドの障害を確認する際には、まずここを確認します。

詳細ログの有効化 設定済みの REST または SOAP メッセージレコードを使用したコールの場合:

[System Web Services] > [Outbound] 配下の REST または SOAP メッセージレコードに移動します。 メソッドを選択します。 [Related Links] で [Set HTTP Log Level] > [All] を選択します。 失敗したコールを再実行します。 フィルターナビゲーターで [Outbound HTTP Requests] に移動し、リクエストとレスポンスの全内容を確認します。 Flow Designer スポークまたはインラインスクリプトを使用したコールの場合:

フィルターナビゲーターで [sys_properties.list] に移動し、以下のシステムプロパティを設定します。これらはすべてのアウトバウンド Web サービスのログに影響するグローバルプロパティです。ログを取得したら、すぐに無効化してください。

glide.outbound_http_log.override = true glide.outbound_http_log.override.level = all glide.outbound_http.content.max_limit = 1000 注意

グローバルログオーバーライドプロパティは、調査対象のコールだけでなく、インスタンス上のすべてのアウトバウンド Web サービスコールに影響します。設定して失敗したコールのログを取得したら、ログが過剰に増大しないよう、すぐに元に戻してください。

ログレコードの読み取り sys_outbound_http_log のレコードを開き、以下のタブを確認します:

[Request] タブ — ヘッダー、Authorization ヘッダー、リクエストボディを含むアウトバウンドリクエストの全内容。 [Response] タブ — HTTP ステータスコードとレスポンスボディを含む、エンドポイントからのレスポンスの全内容。 [Source] タブ — ノードログへのトレースに使用するノードホスト名 (System ID) と Session ID。

ノードログへのトレース ログレコードから Transaction ID をコピーします。 最初の 12 文字を取得します。これがノードログで使用される TXID です。 [Source] タブの System ID フィールドで識別されたノード上の Splunk (本番環境) または bssh (本番前環境) でこの TXID を検索します。 7. HTTP ステータスコードクイックリファレンス コードを確認し、該当するセクションに移動してください。

コード 意味 対応方法 0 または -1 応答なし — 接続が完了しなかった ネットワークパス、ファイアウォール、DNS を確認。セクション 5.1 参照。 400 Bad Request — エンドポイントがリクエストボディまたは URL を拒否した リクエストボディの形式とエンドポイント URL を確認。セクション 5.4 参照。 401 Unauthorized — 認証情報が存在しないか、エンドポイントに拒否された 認証プロファイルと [Request] タブの Authorization ヘッダーを確認。セクション 5.2 参照。 403 Forbidden — 認証情報は有効だがエンドポイントでの権限が不足している エンドポイントの権限と OAuth スコープを確認。セクション 5.2 参照。 500 Internal Server Error — エンドポイント側の障害 Postman でテストし、問題がエンドポイント側にあることを確認。セクション 5.4 参照。 502 Bad Gateway — 呼び出し元とエンドポイントの間のプロキシまたはゲートウェイがエラーを返した プロキシとロードバランサーの設定を確認。セクション 5.4 参照。 503 Service Unavailable — エンドポイントが一時的に利用不能 バックオフを設けて再試行。継続する場合はセクション 5.4 参照。 8. 関連記事 KB3067060 - Outbound Web Services — Connection Failures & TLS Errors KB3067106 - Outbound Web Services — Authentication & Authorization Failures KB3067152 - Outbound Web Services — Timeouts & Slow Responses KB3067183 - Outbound Web Services — Endpoint Errors (4xx/5xx) KB1695665 — Landing page for Web Services (Outbound) KB0694711 — RESTMessageV2 and SOAPMessageV2 execute() vs executeAsync() KB0960404 — MID Server Landing Page Release .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } すべて

Cause .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Resolution .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } }

Related Links .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } アウトバウンド Web サービスログ:

KB0998511 - Capturing localhost logs for Outbound Web Service issues