このガイドでは、Webhook を実装するためのさまざまなサンプルと、Webhook のトラブルシューティングに関する推奨事項について説明します。
セッション パラメータを設定する
以下のサンプルは、セッション パラメータを設定する方法を示しています。
Go
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Webhook クイックスタートをご覧ください。Java
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
フルフィルメント レスポンスを返す
次のサンプルは、フルフィルメント レスポンスを返す方法を示しています。
Go
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Webhook クイックスタートをご覧ください。Java
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
必要に応じてフォーム パラメータを設定する
次のサンプルは、パラメータに必須のフラグを付ける方法を示しています。
Java
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
フォーム パラメータを検証する
次のサンプルは、フォーム パラメータを検証する方法を示しています。
Java
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
ログセッション ID
次のサンプルは、Webhook リクエストの session ID
をログに記録する方法を示しています。
Python
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
トラブルシューティング
Webhook 呼び出しのライフサイクル
Webhook 呼び出しは常に会話エージェント(Dialogflow CX)によって開始され、HTTPS 経由でウェブサーバーに送信されます。汎用ウェブサービス ウェブフック呼び出しは、Google に属するインターネット IP アドレスから発信され、公共のインターネットで利用可能なウェブサーバー(ウェブフック サーバー)に到達できます。一方、Service Directory ウェブフックは常に内部Google Cloud アドレスから開始され、 Google Cloud内のプライベート ネットワークにあるウェブフック サーバーにのみ到達できます。
Webhook のデバッグに役立つログ
通常、Webhook の問題のデバッグには、Cloud Logging の Dialogflow ログと Webhook サーバーログの収集が必要です。Webhook サーバーが Cloud Run functions を使用して実装されている場合、そのログは Cloud Logging にあります。それ以外の場合、通常、ログは Webhook サーバーが実行されている場所に保存されます。
標準の Webhook ログには、Webhook サーバーで特定の呼び出しをトレースするのに役立つ UUID を含む detectIntentResponseId
フィールドが含まれています。このログは、Cloud Logging が有効になっている場合、Dialogflow Cloud Logging ログに存在します。
Webhook に関する一般的な問題
Webhook 呼び出しの Dialogflow ログで検出されるエラーには、次のようなものがあります。
Webhook サーバーのホスト名解決エラー
Dialogflow が汎用ウェブフックのホスト名をルックアップしましたが、そのホスト名が DNS に存在しません。ホスト名がパブリック DNS に登録されていることを確認します。ホスト名が新しい場合は、レコードが反映されるまでに時間がかかることがあります。Cloud Logging メッセージ: State: URL_ERROR, Reason: ERROR_DNS
。
Webhook サーバーがクライアントサイド エラーを返す
ERROR_DNS
以外の場合、この状態は Webhook サーバーからの 4xx レスポンスを示します。これは、未承認のステータス(401 - ERROR_AUTHENTICATION
)であるか、URL が Webhook サーバーで見つからなかった(404 - ERROR_NOT_FOUND
)可能性があります。Cloud Logging メッセージ: State: URL_ERROR
。
Webhook サーバーがレスポンスを返す前に Dialogflow エージェントがタイムアウトする
ウェブサーバーが終了する前に、Dialogflow が Webhook タイムアウトの制限に達しました。この場合、Webhook サーバーの処理時間を短縮するか、Dialogflow が Webhook を待機する時間を延長するかの 2 つの方法があります。処理時間を短縮すると、通常は最良の結果が得られますが、多くの場合、簡単ではありません。ウェブフックには最大タイムアウトの上限があり、この設定を増やすと、エージェントからの回答を得るまでにエンドユーザーの待ち時間が長くなることを考慮してください。Cloud Logging メッセージ: State: URL_TIMEOUT, Reason: TIMEOUT_WEB
。
Webhook サーバーがレスポンスを返す前に gRPC がタイムアウトする
Webhook 呼び出しが完了する前に、Dialogflow API 呼び出しで gRPC によって設定されたタイムアウトに達しました。この上限は通常、統合レベルで設定され、Dialogflow パラメータと Webhook タイムアウトの上限とは関係ありません。gRPC の期限の詳細については、https://grpc.io/docs/guides/deadlines/ をご覧ください。Cloud Logging メッセージ: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED
。
Dialogflow が webhook サーバーに接続できなかった
ネットワーク エラーが原因で Webhook サーバーにアクセスできなかったか、接続が確立されたものの、Webhook サーバーがリクエストの処理中に問題が発生したことを示す HTTP ステータス 5xx を返しました。Dialogflow がネットワーク レベルで webhook サーバー アドレスに到達できることを確認します。リクエストが Webhook サーバーログに表示されている場合は、呼び出しが 5xx エラーを返した理由を確認します。Cloud Logging メッセージ: State: URL_UNREACHABLE
。
Webhook 呼び出しのトレース
標準の Webhook 呼び出しは、セッション ID、detectIntentResponse
ID、Cloud Run functions のトレース ID、呼び出しのタイムスタンプを使用して、Dialogflow と Webhook サーバー間で関連付けることができます。柔軟な Webhook トレースは、呼び出しのタイムスタンプと、設計時に Webhook 定義で指定されたセッション パラメータ値を使用して行うことができます。標準 Webhook リクエストとフレキシブル Webhook リクエストの詳細については、Webhook をご覧ください。
セッション ID は、WebhookRequest の sessionInfo.session
フィールドに表示されます。このセッション ID は会話ごとに一意にする必要があります。このセッション ID を使用するとリクエストのエージェント ログと Webhook ログを比較する際に役立ちます。前のログセッション ID セクションでは、Webhook からセッション ID をログに記録する方法を示しています。
また、Webhook をホストしている場合は、Cloud Run functionsまたは、同様の Google Cloud サーバーレス オプションを使用している場合は、ログエントリから trace
フィールドをログフィルタとして使用します。関数の 1 回の実行で、同じトレース値を持つ複数のログエントリが生成されます。
次の例では、セッション ID とトレース値の両方を使用して、特定の Dialogflow エージェント エラーログを対応する Cloud Run functions Webhook ログエントリに関連付けます。この例では、Cloud Logging が有効になっているエージェントの Cloud Logging フィルタを使用します。
1. 特定のエージェントのエラーログに対して Dialogflow ログをフィルタする
次の Cloud Logging フィルタを使用して、特定のエージェントのエラーログに対して Dialogflow ログをフィルタします。
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Webhook ログのエラー エントリは次のようになります。
{
"insertId": "-j4gkkre31e2o",
"jsonPayload": {
"code": 14,
"message": "Error calling webhook 'https://us-central1-PROJECT_ID.cloudfunctions.net/function-webhook': State: URL_UNREACHABLE, Reason: UNREACHABLE_5xx, HTTP status code: 500"
},
"labels": {
"agent_id": "e9e01392-1351-42dc-9b15-b583fb2d2881",
"environment_id": "",
"location_id": "global",
"session_id": "07c899-a86-78b-a77-569625b37"
},
"logName": "projects/PROJECT_ID/logs/dialogflow-runtime.googleapis.com%2Frequests",
"receiveTimestamp": "2024-10-28T21:49:04.288439054Z",
"resource": {
"labels": {
"project_id": "PROJECT_ID"
},
"type": "global",
},
"severity": "ERROR",
"timestamp": "2024-10-28T21:49:04.132548Z"
}
セッション ID を含む labels.session_id
フィールドをメモします。セッション ID は次のステップで使用します。
2. Cloud Run functions のログをセッション ID でフィルタする
次の Cloud Logging フィルタを使用して、セッション ID で Cloud Run 関数のログをフィルタリングします。
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
textPayload="Debug Node: session ID = SESSION_ID"
結果のログは、指定されたセッション中に作成された Webhook ログに対応します。次に例を示します。
{
"insertId": "671c42940007ebebdbb1d56e",
"labels": {
"execution_id": "pgy8jvvblovs",
"goog-managed-by": "cloudfunctions",
"instance_id": "004940b3b8e3d975a4b11a4ed7d1ded4ce3ed37467ffc5e2a8f13a1908db928f8200b01cc554a5eda66ffc9d23d76dd75cec1619a07cb5751fa2e8a93bc6cfc3df86dfa0650a"
},
"logName": "projects/PROJECT_ID/logs/run.googleapis.com%2Fstdout",
"receiveTimestamp": "2024-10-26T01:15:00.523313187Z",
"resource": {
"labels": {
"configuration_name": "function-webhook",
"location": "us-central1",
"project_id": "PROJECT_ID",
"revision_name": "function-webhook-00001-jiv",
"service_name": "function-webhook",
},
"type": "cloud_run_revision"
},
"spanId": "6938366936362981595",
"trace": "d1b54fbc8945dd59bdcaed37d7d5e185",
"textPayload": "Debug Node: session ID = 07c899-a86-78b-a77-569625b37",
"timestamp": "2024-10-26T01:15:00.519147Z"
}
trace
フィールドをメモします。これは次のステップで使用します。
3. Cloud Functions のログを特定のトレースでフィルタする
次の Cloud Logging フィルタを使用して、特定のトレースのために Cloud Functions 関数のログをフィルタします。
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
trace="projects/PROJECT_ID/traces/TRACE_ID"
ここで、TRACE_ID
はトレースの最後のセグメントです。たとえば、projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e
の TRACE_ID
は e41eefc1fac48665b442bfa400cc2f5e
です。
結果は、ステップ 1 のセッション ID とステップ 2 のトレースに関連付けられた Webhook リクエストの実行中に生成された Webhook サーバーログです。ログは次のようになります。
{
"insertId": "671c42940008465e29f5faf0",
"httpRequest": {
"requestMethod": "POST",
"requestUrl": "https://us-central1-TEST_PROJECT.cloudfunctions.net/function-webhook",
"requestSize": "2410",
"status": 200,
"responseSize": "263",
"userAgent": "Google-Dialogflow",
"remoteIp": "8.34.210.1",
"serverIp": "216.239.36.1",
"latency": "0.166482342s",
"protocol": "HTTP/1.1"
},
"resource": {
"type": "cloud_run_revision",
"labels": {
"project_id": "PROJECT_ID",
"service_name": "function-webhook",
"location": "us-central1",
"revision_name": "function-webhook-00001-jiv",
"configuration_name": "function-webhook"
}
},
"timestamp": "2024-10-26T01:15:00.352197Z",
"severity": "INFO",
"labels": {
"instanceId": "004940b3b813af8a656c92aac1bd07ffad5165f1353e1e346b6161c14bcde225f68f4a88ceedc08aa9020f387b1b59471f73de45f2882a710ced37dea921f05ad962347690be",
"goog-managed-by": "cloudfunctions"
},
"logName": "projects/test-project-12837/logs/run.googleapis.com%2Frequests",
"trace": "projects/test-project-12837/traces/d1b54fbc8945dd59bdcaed37d7d5e185",
"receiveTimestamp": "2024-10-26T01:15:00.548931586Z",
"spanId": "604a07f7b33b18db",
"traceSampled": true
}