Google Cloud には、Google Cloud Monitoring を使用してプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログを使用して問題をデバッグするためのツールが用意されています。ユーザー インテントの処理中にエラーが発生すると、Google Home Analytics パイプラインは、そのエラーを指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標を使用してプロジェクトの状態をモニタリングします。
- エラーログでエラーの詳細な説明を確認して、問題を調査します。
必要に応じて、他のユーザーと共有してアクションをテストできます。エラーと例外の処理を適切に行えるようにします。
エラーをモニタリングする
Google Cloud Monitoring dashboards を使用して、プロジェクトの指標にアクセスできます。品質のモニタリングとデバッグに特に役立つ主要なグラフがいくつかあります。
- [成功率] グラフは、プロジェクトの信頼性をモニタリングするときに最初に表示されるグラフです。このグラフの低下は、ユーザーベースの一部またはすべてでサービスが停止していることを示している可能性があります。プロジェクトの変更や更新のたびに、このグラフを注意深くモニタリングして、異常がないか確認することをおすすめします。
- 95 パーセンタイル レイテンシのグラフは、Cloud-to-cloud の統合がユーザーに対してどのように機能しているかを示す重要な指標です。このグラフの急激な変動は、システムがリクエストに追いついていないことを示している可能性があります。このグラフを定期的に確認して、予期しない動作がないか確認することをおすすめします。
- [Error Breakdown] グラフは、統合に関する問題のトラブルシューティングに最も役立ちます。成功率グラフでハイライト表示されたエラーごとに、エラーの内訳にエラーコードが表示されます。Google Home platform によってフラグが立てられたエラーとそのトラブルシューティング方法を次の表に示します。
一般的なプラットフォーム エラーコード
Google Home platform で検出された問題を特定するために、プロジェクト ログに表示される一般的なエラーコードをいくつか紹介します。トラブルシューティングの情報については、次の表をご覧ください。エラーコードの一覧については、エラーと例外をご覧ください。
| エラーコード | 説明 | パートナーが対応可能 |
|---|---|---|
AGENT_ISSUE |
パートナーのクラウド エージェントで一般的な問題が発生しました。
フルフィルメント ログで、未処理の例外やクラッシュがないか確認します。 |
○ |
AGENT_UNAVAILABLE_ERROR |
Google がパートナーのフルフィルメント URL にアクセスできませんでした。
サーバーがオンラインであること、ファイアウォールが Google をブロックしていないこと、URL が正しいことを確認してください。 |
○ |
COMMAND_FAILED |
コマンドの実行中に一般的なエラーが発生しました。 フルフィルメント ログで特定の requestId を確認して、根本原因を特定します。
|
○ |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google がフルフィルメントから HTTP 4xx エラー（401 以外）を受信しました。
ウェブサーバーのサーバーログで 403、404、400 のレスポンスを確認します。 |
○ |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
サービスにアクセスしようとしたときに、Google のリクエストがタイムアウトしました。
サービスがオンラインで、接続を受け入れており、容量を超えていないことを確認します。また、対象デバイスの電源がオンで、オンラインであり、同期されていることを確認します。 |
○ |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
フルフィルメント URL が robots.txt またはセキュリティ フィルタによってブロックされている。
フルフィルメント エンドポイントが Google のクローラー/サービスにアクセスできることを確認します。 |
○ |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google がフルフィルメント サービスから HTTP 5xx エラーを受信しました。
エンドポイント URL サービスが安定しており、正しく、一般公開でアクセス可能であり、サービスが実行されていることを確認します。Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。ヘルスチェックと再試行処理を追加します。サーバーのクラッシュ、タイムアウト、502/503 ゲートウェイ エラーを調査します。 |
○ |
EXECUTION_BAILOUT_INVALID_RESPONSE |
JSON レスポンスの形式が正しくないため、処理が中止されました。
JSON バリデータを使用して、レスポンスがインテント スキーマに厳密に準拠していることを確認します。 |
○ |
EXECUTION_GAL_BAD_3P_RESPONSE |
トークン レスポンスの形式が無効なため、アカウントをリンクできませんでした。
OAuth サーバーのレスポンス形式が Google の要件に一致していることを確認します。 |
○ |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
ユーザーのアカウントに、この操作に必要な権限がありません。
OAuth 時にリクエストされたスコープを確認し、必要なトレイトと一致していることを確認します。 |
○ |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
パートナー クラウドは、ユーザーがアカウントのリンクを解除したことを示します。
agentUserId マッピングが安定しており、パージされていないことを確認します。
|
○ |
EXECUTION_GAL_NOT_FOUND |
Google に保存されているユーザーのアクセス トークンと更新トークンが無効であるか、更新できないため、認証とパートナー サービスへのアクセスができません。 トークンが有効で同期されていることを確認し、アカウント ステータスの変更を適切に処理します。トークンが取り消されたことが確認された場合は、ユーザーにアカウントの再リンクを要求します。 |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
統合はパートナー側で読み取り専用の状態になっています。
ユーザーのアカウントが停止されているか、「表示専用」のメンテナンス モードになっているかを確認します。 |
○ |
EXECUTION_GAL_UNLINKED_BY_3P |
サードパーティ サービスによってアカウントのリンクが事前に解除された。
ユーザーの接続が切断された理由（セキュリティのリセットなど）を調査します。パートナーの OAuth サーバーが Google の refresh_token リクエストに正しく応答し、新しいアクセス トークンをシームレスに発行することを確認します。 |
○ |
EXECUTION_INVALID_JSON |
JSON レスポンス ペイロードを Google が解析できませんでした。
レスポンスに構文エラー、括弧の欠落、無効な文字がないか確認します。 |
○ |
INVALID_AUTH_TOKEN |
Google がサービスから HTTP 401 エラーコードを受信しました。
アクセス トークンの有効期限は切れていませんが、サービスによって無効にされています。 Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。 |
|
INVALID_JSON |
レスポンス構造が無効です（必須フィールドがないなど）。 インテント JSON スキーマに照らしてレスポンスを検証します。 |
○ |
MALFORMED_JSON |
JSON 構造が破損している（文字列やオブジェクトが閉じられていないなど）。
フルフィルメントで標準の JSON ライブラリを使用してレスポンスをシリアル化していることを確認します。 |
○ |
NOT_IMPLEMENTED |
リクエストされたインテントまたはトレイトがパートナーによって実装されていません。
SYNC レスポンスには、完全に実装したトレイトのみを含めます。
|
○ |
OPEN_AUTH_FAILURE |
ユーザーのアクセス トークンの有効期限が切れており、Google が更新できないか、Google がサービスから HTTP 401 エラーコードを受け取っています。
このコードの発生率が増加している場合は、スマートホーム インテントまたは更新トークン リクエストに関連するエラーの発生率も増加しているかどうかを確認します。 |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
返された errorCode 文字列が、Google のサポート対象リストにありません。
内部エラーを公式エラーリストにマッピングします。 |
○ |
PARTNER_RESPONSE_INVALID_PAYLOAD |
レスポンスの payload フィールドが有効な JSON オブジェクトではありません。フルフィルメント レスポンスのルート構造を確認します。 |
○ |
PARTNER_RESPONSE_INVALID_STATUS |
レスポンス status が SUCCESS、ERROR、OFFLINE のいずれでもありませんでした。
レスポンス内のすべてのデバイスの結果に、有効なステータス文字列が含まれていることを確認します。 |
○ |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
レスポンスに、リクエストされたすべてのコマンド/デバイスの結果が含まれていませんでした。
Google Home デベロッパー ドキュメントに照らして、レスポンス構造を検証します。内部サーバーエラーによりレスポンスが切り捨てられたり、空の本文が返されたりしていないことを確認します。リクエストの commands 配列内のすべてのアイテムには、対応するレスポンス エントリが必要です。 |
○ |
PARTNER_RESPONSE_MISSING_DEVICE |
Google がリクエストした特定のデバイスがレスポンスから除外されました。
レスポンスに、リクエスト ペイロードで指定されたすべての ID が含まれていることを確認します。
|
○ |
PARTNER_RESPONSE_MISSING_PAYLOAD |
レスポンスに必須の payload フィールドがありません。
最上位の JSON オブジェクトに payload キーが含まれていることを確認します。
|
○ |
PARTNER_RESPONSE_NOT_OBJECT |
レスポンス全体を JSON オブジェクトとして解析できませんでした。
HTTP レスポンスの本文に末尾の文字または JSON 以外のコンテンツがないか確認します。 payload.commands[] が、ID、ステータス、オプションの状態を含む適切な JSON オブジェクトであることを確認します。 |
○ |
REQUEST_ID_NOT_FOUND |
リクエストの内部トラッキング ID が見つかりませんでした。
通常は内部プラットフォーム エラーです。急増をモニタリングして、サポートにお問い合わせください。 |
○ |
RESOURCE_UNAVAILABLE |
リクエストされたリソース（デバイスまたはトレイト）は利用できません。
デバイスが「ビジー」状態であるか、一時的に無効になっているかを確認します。 |
○ |
RESPONSE_TIMEOUT |
フルフィルメント サービスが 9 秒以内に応答しませんでした。
バックエンドのレイテンシを最適化します。DB クエリの遅延やリージョン ネットワークの遅延を確認します。 |
○ |
RESPONSE_UNAVAILABLE |
パートナーのフルフィルメント URL から応答がありませんでした。
サービスが実行されており、エンドポイントがクラッシュしていないことを確認します。 |
○ |
TIMEOUT |
インテントの処理中に一般的なタイムアウトが発生しました。
クラウドとデバイスハブ間の内部サービス タイムアウトのログを確認します。 |
○ |
検索ログ
指標を使用して統合をモニタリングすることに慣れたら、次のステップとして、Cloud Logging を使用して特定のエラーをトラブルシューティングします。エラーログは、時間、エラーコード、元のスマートホーム インテントに関する詳細などの有用な情報を含むフィールドを持つ JSON のようなエントリです。
Google 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 も参考にしてください。
- Codelab: スマートホームのデバッグ: スマートホームのクラウド統合をデバッグするためのクイック スタートガイドです。
- Codelab: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。