更新日: 2023 年 1 月 6 日
Google Cloud は、Google Cloud Monitoring でプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログで問題をデバッグするためのツールを提供します。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインがその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングする。
- エラーログでエラーの詳しい説明を確認して問題を調査する。
エラーをモニタリングする
Google Cloud Monitoring dashboard を使用して、プロジェクトの指標にアクセスできます。品質のモニタリングとデバッグにおいて、特に役に立つグラフをいくつか紹介します。
- 成功率のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。このグラフを慎重にチェックし、プロジェクトに変更や更新を加えた後に異常が発生していないかを確認します。
- エラーの内訳のグラフは、統合のトラブルシューティングにおいて特に役立ちます。成功率グラフでハイライト表示されたすべてのエラーについて、その内訳とエラーコードを確認できます。Google Home platform から報告されたエラーとそのトラブルシューティングの方法については、次の表をご覧ください。
一般的なプラットフォーム エラーコード
Google Home platform によって検出された問題を特定するために、プロジェクト ログに表示される一般的なエラーコードを以下に示します。トラブルシューティング情報については、次の表をご覧ください。エラーコードの全リストについては、エラーと例外をご覧ください。
| エラーコード | 説明 | Partner Actionable（パートナーが対応可能） |
|---|---|---|
AGENT_ISSUE |
パートナーのクラウド エージェントで一般的な問題が発生しました。 フルフィルメント ログで未処理の例外やクラッシュがないか確認します。 |
はい |
AGENT_UNAVAILABLE_ERROR |
Google がパートナーのフルフィルメント URL にアクセスできませんでした。 サーバーがオンラインであること、ファイアウォールで Google がブロックされていないこと、URL が正しいことを確認します。 |
はい |
BACKEND_FAILURE_URL_TIMEOUT |
Google のリクエストがサービスにアクセスしようとしたときにタイムアウトしました。 サービスがオンラインで、接続を受け入れており、容量を超えていないことを確認します。また、ターゲット デバイスの電源がオンになっていて、オンラインで同期されていることを確認します。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google は、お客様のサービスから HTTP 5xx エラーコードを受け取りました。 Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。サーバーのクラッシュ、タイムアウト、502/503 ゲートウェイ エラーを調査します。 |
|
COMMAND_FAILED |
コマンドの実行中に一般的なエラーが発生しました。 フルフィルメント ログで特定の requestId を確認し、根本原因を特定します。 |
はい |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google は、フルフィルメントから HTTP 4xx エラー（401 以外）を受け取りました。 ウェブサーバーのログで 403、404、400 のレスポンスを確認します。 |
はい |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
フルフィルメント URL が robots.txt またはセキュリティ フィルタによってブロックされています。 フルフィルメント エンドポイントが Google のクローラー/サービスからアクセス可能であることを確認します。 |
はい |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google は、フルフィルメント サービスから HTTP 5xx エラーを受け取りました。 エンドポイント URL サービスが安定していて、正しく、一般公開されており、サービスが実行中であることを確認します。ヘルスチェックと再試行処理を追加します。サーバーのクラッシュ、タイムアウト、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 |
Google は、リクエストの内部トラッキング 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: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。