Google Cloud は、Google Cloud Monitoring を使用してプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログを使用して問題をデバッグするツールを提供します。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインはその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングする。
- エラーログでエラーの詳しい説明を確認して、問題を調査します。
エラーをモニタリングする
Google Cloud Monitoring dashboard を使用して、プロジェクト指標にアクセスできます。品質のモニタリングとデバッグにおいて特に役立つキーチャートを以下に示します。
- 成功率のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。プロジェクトを変更または更新した後、このグラフで異常がないか監視することをおすすめします。
- 95 パーセンタイルのレイテンシのグラフは、スマートホーム アクションのパフォーマンスに関する重要な指標です。このグラフが突然変動した場合、システムがリクエストに対応できていない可能性があります。予期しない動作が発生しないように、このグラフを定期的に確認することをおすすめします。
- エラーの内訳のグラフは、統合に関する問題のトラブルシューティングに役立ちます。成功率グラフでハイライト表示されたすべてのエラーのエラーコードがエラーの内訳に表示されます。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 |
ペイロードの形式または値が無効であるため、アカウント リンク サービスからのレスポンスを 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 |
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 によく似た形式で記録されています。
Google Cloud 内に複数のシステムがあり、常にプロジェクトにログを送信します。ログをフィルタするクエリを作成し、必要なクエリを見つける必要があります。クエリは、期間、リソース、重大度、カスタム エントリに基づいて作成できます。
クエリボタンを使用して、カスタム フィルタを作成できます。
期間を指定するには、期間選択ボタン をクリックし、提供されたオプションの 1 つを選択します。これにより、ログがフィルタされ、選択した期間に発生したログが表示されます。
リソースを指定するには、[リソース] プルダウンをクリックし、[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 も参考にしてください。
- Codelab: スマートホームのデバッグ: スマートホームのクラウド統合をデバッグするためのクイック スタートガイドです。
- Codelab: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。