Google Home デベロッパー センターにようこそ。スマートホーム アクションの開発方法を学ぶことができます。注: アクションの作成は、引き続き Actions Console で行います。

統合エラーのトラブルシューティング

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Google Cloud Platform (GCP) には、Google Cloud Monitoring でプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログで問題をデバッグするためのツールが用意されています。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインがその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。

エラーのトラブルシューティングは、次の 2 つの手順で行います。

  1. スマートホームの指標でプロジェクトの状態をモニタリングする。
  2. エラーログでエラーの詳しい説明を確認して調査する。

ローカル統合の場合も手順は同様です。トラブルシューティングのフローをマスターすれば、指標とログを交互に見ながらエラーを簡単に分析できます。

エラーをモニタリングする

Google Cloud Monitoring dashboard を使用すると、プロジェクト指標にアクセスできます。品質のモニタリングとデバッグで特に役立つ主要グラフを以下に示します。

  • 成功率のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。このグラフを入念にモニタリングして、プロジェクトに変更や更新を加えた後に異常がないか確認することをおすすめします。
  • エラーの内訳のグラフは、統合に関する問題のトラブルシューティングに役立ちます。成功率グラフでハイライト表示されたすべてのエラーについて、その内訳とエラーコードを確認できます。Google Home platform によって報告されたエラーとそのトラブルシューティングの方法については、次の表をご覧ください。

プラットフォームのエラーコード

以下に、Google Home platform によって検出された問題を特定するために、プロジェクト ログに表示される可能性のある一般的なエラーコードを示します。トラブルシューティング情報については、次の表をご覧ください。

エラーコード 説明
BACKEND_FAILURE_URL_ERROR Google がサービスから、401 以外の HTTP 4xx エラーコードを受信した。

GCP Logging の requestId を使用して、スマートホーム サービスのログを確認します。
BACKEND_FAILURE_URL_UNREACHABLE Google がサービスから HTTP 5xx エラーコードを受信しました。

GCP Logging の requestId を使用して、スマートホーム サービスのログを確認します。
GAL_BAD_3P_RESPONSE ペイロード内の形式または値が無効であるため、アカウント リンク サービスからのレスポンスを解析できません。

GCP Logging の requestId を使用して、アカウントのリンク サービスのエラーログを確認します。
GAL_INTERNAL Google がアクセス トークンを取得しようとしたときに、Google の内部エラーが発生しました。

GCP Logging でこのエラーのレートが増えた場合は、詳細について Google にお問い合わせください。
GAL_INVALID_ARGUMENT Google がアクセス トークンを取得しようとしたときに、Google の内部エラーが発生しました。

GCP Logging でこのエラーのレートが増えた場合は、詳細について Google にお問い合わせください。
GAL_NOT_FOUND Google に保存されているユーザーのアクセス トークンと更新トークンは無効になり、更新できなくなります。サービスを継続して使用するには、ユーザーがアカウントを再リンクする必要があります。

GCP Logging でこのエラーのレートが増えた場合は、詳細について Google にお問い合わせください。
GAL_PERMISSION_DENIED トークンの共有が承認されていないときに Google 内部エラーが発生しました。

GCP Logging でこのエラーのレートが増えた場合は、詳細について Google にお問い合わせください。
GAL_REFRESH_IN_PROGRESS ユーザーのアクセス トークンの有効期限が切れ、それを更新するための別の同時試行がすでに進行中です。

これは問題ではないため、ご対応の必要はありません。
INVALID_AUTH_TOKEN Google がサービスから HTTP 401 エラーコードを受け取りました。

アクセス トークンの有効期限が切れていませんが、サービスによりアクセス トークンが無効化されています。 GCP Logging の requestId を使用して、スマートホーム サービスログを確認します。
INVALID_JSON JSON レスポンスを解析または認識できません。

JSON レスポンスの構造をチェックし、かっこの不一致、カンマの欠落、無効な文字など、無効な構文がないか確認します。
OPEN_AUTH_FAILURE ユーザーのアクセス トークンが期限切れになっており、Google がアクセス トークンを更新できないか、Google がサービスから HTTP 401 エラーコードを受信しています。

このコードのレートが増加した場合は、スマートホーム インテントまたは更新トークン リクエストに関連するエラーのレートも増加しているかどうかを確認してください。
PARTNER_RESPONSE_INVALID_ERROR_CODE レスポンスに、認識できないエラーコードが示されています。

リクエスト レスポンスにエラーが示されている場合は、サポートされているエラーコードが使用されていることを確認します。
PARTNER_RESPONSE_INVALID_PAYLOAD レスポンスの payload フィールドを JSON オブジェクトとして解析できません。

リクエスト レスポンスのペイロード フィールドのかっこが一致していること、JSON フィールドとして正しく構造化されていることを確認します。
PARTNER_RESPONSE_INVALID_STATUS レスポンスにステータスが示されていないか、示されているステータスが正しくありません。

インテントのフルフィルメント リクエストに対するレスポンスでは、SUCCESS, OFFLINE, ERROR, EXCEPTIONS のいずれかのステータスを示す必要があります。詳しくは、エラーと例外を処理するをご覧ください。
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES レスポンスに、リクエスト内の 1 つ以上のインテントが見つかりません。

実行レスポンスが正しく構造化されていること、リクエストからのすべてのインテントの結果がレスポンスに含まれていることを確認します。
PARTNER_RESPONSE_MISSING_DEVICE レスポンスに、リクエスト内の 1 つ以上のデバイスが見つかりません。

実行レスポンスが正しく構造化されていること、リクエストからのすべてのデバイス ID がレスポンスに含まれていることを確認します。
PARTNER_RESPONSE_MISSING_PAYLOAD レスポンスに payload フィールドが含まれていません。

リクエスト レスポンスにペイロード フィールドが含まれていることを確認します。詳細については、実行レスポンスを正しく作成する方法をご確認ください。
PARTNER_RESPONSE_NOT_OBJECT レスポンスを JSON オブジェクトとして解析できません。

リクエスト レスポンス内のすべてのフィールドで、意図されていない文字が含まれていないか、角かっこの不一致やフォーマット エラーがないかを確認します。一部の Unicode 文字はサポートされていない可能性があります。また、レスポンスが JSON オブジェクトとして正しく構造化されていることを確認してください。
RESPONSE_TIMEOUT レスポンスを待機している間、リクエストがタイムアウトしました。

レスポンスの送信がタイムアウトするまでの時間は、リクエストが送信されてから 9 秒です。この時間内にレスポンスが送信されていることを確認してください。
RESPONSE_UNAVAILABLE レスポンスを受信していないか、レスポンスにステータスが示されていません。

インテントのフルフィルメント リクエストに対するレスポンスは、スマートホームのドキュメントに沿って構造化し、ステータスを示す必要があります。

検索ログ

指標を使用して統合のモニタリングに問題がなければ、次のステップとして、Cloud Logging を使用して特定のエラーのトラブルシューティングを行います。エラーログは、時間、エラーコード、スマートホーム インテントの詳細などの有用な情報を含む JSON に似たエントリです。

GCP 内には複数のシステムがあり、常にプロジェクトにログを送信します。ログをフィルタリングするクエリを記述して、必要なログを見つける必要があります。クエリは、期間リソース、ログの重大度、またはカスタム エントリに基づいて作成できます。

Cloud ログをクエリする

クエリボタンを使用して、カスタム フィルタを作成できます。

Cloud ログクエリの作成

「期間」を指定する場合は、期間選択ボタン をクリックし、規定のオプションを選択します。これにより、ログがフィルタされ、選択した期間内に発生したログが表示されます。

リソースを指定するには、[リソース] プルダウンをクリックして [Google アシスタント アクション プロジェクト] を選択します。これにより、クエリにフィルタが追加され、プロジェクトからのログが表示されます。

[重大度] ボタンを使用して、緊急情報デバッグ、その他の重大度でフィルタリングします。

Logs Explorer の [クエリ] フィールドを使用して、カスタム エントリを入力することもできます。このフィールドで使用されるクエリエンジンは、文字列マッチングなどの基本的なクエリと、コンパレータ(<, >=, !=)やブール演算子(AND, OR, NOT)などの高度なクエリの両方をサポートしています。

たとえば、以下のカスタム エントリは LIGHT デバイスタイプで発生したエラーを返します。

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

ログを効果的にクエリするその他の例については、クエリ ライブラリをご覧ください。

修正をテストする

エラーを特定し、修正するために修正を採用したら、Google Home Test Suite を使用して修正を徹底的にテストすることをおすすめします。Test Suite の使用方法に関するユーザーガイドが用意されています。このガイドでは、変更を効果的にテストする方法について説明します。

学習用リソース

このドキュメントでは、スマートホーム アクションのエラーをトラブルシューティングする手順について説明します。デバッグの詳細については、以下の Codelab も参考にしてください。