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 サービスから 401 以外の HTTP 4xx エラーコードを受信しました。

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

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

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 サービスから HTTP 401 エラーコードを受信しました。

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

JSON レスポンスの構造をチェックし、かっこの不一致、カンマの欠落、無効な文字など、無効な構文がないか確認します。
OPEN_AUTH_FAILURE ユーザーのアクセス トークンが期限切れで更新できない、またはサービスから 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 を使用して修正を徹底的にテストすることをおすすめします。Google では、Test Suite の使用方法に関するユーザーガイドを提供しています。このガイドでは、変更を効果的にテストする方法について説明します。

学習用リソース

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