Google Cloud は、Google Cloud Monitoring を使用してプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログを使用して問題をデバッグするためのツールを提供します。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインがその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングする。
- エラーログでエラーの詳しい説明を確認して問題を調査する。
必要に応じて、他のユーザーと共有することでアクションをテストできます。エラーと例外の処理を適切に行えるようにします。
エラーをモニタリングする
Google Cloud Monitoring dashboard を使用して、プロジェクトの指標にアクセスできます。品質のモニタリングとデバッグにおいて、特に役に立つグラフをいくつか紹介します。
- 成功率のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。このグラフを慎重にチェックし、プロジェクトに変更や更新を加えた後に異常が発生していないかを確認します。
- 95 パーセンタイルのレイテンシのグラフは、Cloud-to-cloud インテグレーションのパフォーマンスに関する重要な指標です。このグラフが突然変動した場合、システムによるリクエストの処理が追いついていない可能性があります。予期しない動作が発生しないように、このグラフを定期的に確認することをおすすめします。
- エラーの内訳のグラフは、統合のトラブルシューティングにおいて特に役立ちます。成功率グラフでハイライト表示されたすべてのエラーについて、その内訳とエラーコードを確認できます。Google Home platform から報告されたエラーとそのトラブルシューティングの方法については、次の表をご覧ください。
一般的なプラットフォーム エラーコード
Google Home platform によって検出された問題を特定するために、プロジェクト ログに表示される一般的なエラーコードを以下に示します。トラブルシューティング情報については、次の表をご覧ください。エラーコードの全リストについては、エラーと例外をご覧ください。
| エラーコード | 説明 | Partner Actionable（パートナーが対応可能） |
|---|---|---|
ACTION_NOT_AVAILABLE |
コマンドがデバイスの現在の状態に対して無効です（デバイスがオフのときに「温度を設定」するなど）。 フルフィルメントでデバイスの特性と現在の状態のロジックを確認します。 |
はい |
AGENT_ISSUE |
パートナーのクラウド エージェントで一般的な問題が発生しました。 フルフィルメント ログで未処理の例外やクラッシュがないか確認します。 |
はい |
AGENT_UNAVAILABLE_ERROR |
Google がパートナーのフルフィルメント URL にアクセスできませんでした。 サーバーがオンラインであること、ファイアウォールで Google がブロックされていないこと、URL が正しいことを確認します。 |
はい |
APP_LAUNCH_FAILED |
ターゲット デバイスでサードパーティ製アプリを起動できませんでした。 appId と、アプリが対象のハードウェアでサポートされていることを確認します。 |
はい |
AUTH_EXPIRED |
OAuth アクセス トークンの有効期限が切れており、更新できません。 更新トークンのローテーションを確認し、ユーザーがアクセスを取り消していないことを確認します。 |
はい |
BACKEND_FAILURE_URL_TIMEOUT |
Google のリクエストがサービスにアクセスしようとしたときにタイムアウトしました。 サービスがオンラインで、接続を受け入れており、容量を超えていないことを確認します。また、ターゲット デバイスの電源がオンになっていて、オンラインで同期されていることを確認します。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google は、お客様のサービスから HTTP 5xx エラーコードを受け取りました。 Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。
|
|
CHANNEL_SWITCH_FAILED |
デバイスがリクエストされたメディア チャンネルに切り替えられませんでした。 お客様のチャンネル名/番号と定期購入のステータスを確認します。 |
はい |
CHARGER_ISSUE |
デバイスが充電システムのハードウェアの問題を報告します。 パートナーは、ハードウェア レベルのテレメトリーとバッテリーの健全性を調査する必要があります。 |
はい |
CHECK_PARTNER_APP |
このエラーを解決するには、パートナーのアプリを開く必要があります。 複雑な UI 操作（ファームウェアの更新など）が必要なエラーには、このコードを使用します。 |
はい |
COMMAND_FAILED |
コマンドの実行中に一般的なエラーが発生しました。 フルフィルメント ログで特定の requestId を確認し、根本原因を特定します。 |
はい |
COMMAND_INSERT_FAILED |
Google は、デバイスのコマンドをキューに登録または処理できませんでした。 データベースの書き込みパフォーマンスまたは内部コマンド キューイング ロジックを調査します。 |
はい |
DEVICE_NOT_FOUND |
リクエストのデバイス ID がパートナー側に存在しません。 ユーザーがデバイスを追加または削除したときに、クラウドが requestSync をトリガーするようにします。 |
はい |
ERROR_STATUS |
レスポンスに、コードのない「ERROR」という特定できないステータスが示されました。 ユーザーの TTS とダッシュボードのデータを改善するため、常に特定の errorCode 文字列を含めます。
|
はい |
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 エラーを受け取りました。 サーバーのクラッシュ、タイムアウト、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_READ_ONLY_MODE_FOR_3P |
統合がパートナー側で読み取り専用状態になっています。 お客様のアカウントが停止されているか、メンテナンス モード（読み取り専用）になっているかを確認します。 |
はい |
EXECUTION_GAL_UNLINKED_BY_3P |
サードパーティ サービスによってアカウントのリンクが解除された。
お客様の接続が切断された理由（セキュリティ リセットなど）を調査します。 |
はい |
EXECUTION_INVALID_JSON |
JSON レスポンス ペイロードを Google が解析できませんでした。 レスポンスに構文エラー、角かっこの欠落、無効な文字がないか確認します。 |
はい |
FAULTY_BATTERY |
デバイスのハードウェアが、バッテリーの故障または消耗を報告している。
TTS またはアプリを使用して、物理バッテリーを交換するようお客様に指示します。 |
はい |
FUNCTION_NOT_SUPPORTED |
リクエストされたモードまたは機能はデバイスでサポートされていません。SYNC レスポンスがデバイスの機能を正確に反映していることを確認します。 |
はい |
HARD_ERROR |
手動で介入しないと解決しない非一時的な障害。 ハードウェアの永続的な障害や、復元できないアカウントの状態の場合に使用します。 |
はい |
INVALID_AUTH_TOKEN |
Google は、お客様のサービスから HTTP 401 エラーコードを受け取りました。 アクセス トークンの有効期限は切れていませんが、サービスによって無効になっています。Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。 |
|
INVALID_JSON |
レスポンスの構造が無効です（必須フィールドがないなど）。 インテント JSON スキーマに対してレスポンスを検証します。 |
はい |
LOCK_FAILURE |
スマートロックがリクエストされた状態に移行できませんでした。 ロック ハードウェアの物理的な詰まり、電力不足、モーターの故障を調査します。 |
はい |
MALFORMED_JSON |
JSON 構造が壊れている（文字列やオブジェクトが閉じられていないなど）。 フルフィルメントで標準の JSON ライブラリを使用してレスポンスをシリアル化するようにします。 |
はい |
MISSING_STATE |
QUERY レスポンスにリクエストされたデバイスの状態が含まれていませんでした。SYNC で定義されているすべての特性が、すべての QUERY レスポンスで考慮されていることを確認します。 |
はい |
NETWORK_PROFILE_NOT_RECOGNIZED |
リクエストされたネットワーク プロファイルがデバイスに認識されていません。 プロファイル名の文字列が SYNC レスポンスでサポートされているプロファイルと一致していることを確認します。
|
はい |
NOT_IMPLEMENTED |
リクエストされたインテントまたはトレイトがパートナーによって実装されていません。 完全に実装したトレイトのみを SYNC レスポンスに含めます。 |
はい |
OAUTH_RECONNECT_CALL_TO_ACTION |
ユーザーにアカウントの再リンクを求める通知をトリガーします。 ユーザーのセッションが無効になり、OAuth の手動再認証が必要な場合に使用します。 |
はい |
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 |
レスポンスに、リクエストされたすべてのコマンド/デバイスの結果が含まれていませんでした。 リクエストの commands 配列内のすべてのアイテムには、対応するレスポンス エントリが必要です。 |
はい |
PARTNER_RESPONSE_MISSING_DEVICE |
Google がリクエストした特定のデバイスがレスポンスから除外されました。 レスポンスに、リクエスト ペイロードで提供されたすべての ID が含まれていることを確認します。 |
はい |
PARTNER_RESPONSE_MISSING_PAYLOAD |
レスポンスに必須の payload フィールドがありません。トップレベルの JSON オブジェクトに payload キーが含まれていることを確認します。 |
はい |
PARTNER_RESPONSE_NOT_OBJECT |
レスポンス全体を JSON オブジェクトとして解析できませんでした。 HTTP レスポンスの本文に末尾の文字や JSON 以外のコンテンツがないか確認します。 |
はい |
PROTOCOL_ERROR |
基盤となる通信プロトコルでエラーが発生しました。 HTTP ヘッダーの問題または SSL/TLS handshake の失敗を調査します。 |
はい |
RELINK_REQUIRED |
統合を継続して使用するには、アカウントを再度リンクする必要があります。 更新トークンが完全に無効になったときに、サーバーがこのコードを返すようにします。 |
はい |
REQUEST_ID_NOT_FOUND |
Google は、リクエストの内部トラッキング ID を検出できませんでした。 通常は内部プラットフォーム エラーです。スパイクをモニタリングし、サポートにお問い合わせください。 |
はい |
RESOURCE_UNAVAILABLE |
リクエストされたリソース（デバイスまたはトレイト）は利用できません。 デバイスが「ビジー」状態であるか、一時的に無効になっているかを確認します。 |
はい |
RESPONSE_TIMEOUT |
フルフィルメント サービスが 9 秒以内に応答しませんでした。 バックエンド レイテンシを最適化します。低速の DB クエリまたはリージョン ネットワークの遅延を確認します。 |
はい |
RESPONSE_UNAVAILABLE |
パートナーのフルフィルメント URL から応答がありませんでした。 サービスが実行中で、エンドポイントがクラッシュしていないことを確認します。 |
はい |
SCENE_CANNOT_BE_APPLIED |
リクエストされたシーンを有効にできませんでした（デバイスが見つからないなど）。 パートナー クラウドでユーザーのシーンの内部健全性を確認します。 |
はい |
STREAM_UNPLAYABLE |
カメラ ストリームを開始できなかったか、失敗しました。 WebRTC/HLS シグナリングを確認し、ストリーム URL が有効であることを確認します。 |
はい |
TIMEOUT |
インテントの処理中に一般的なタイムアウトが発生しました。 クラウドとデバイスハブ間の内部サービス タイムアウトのログを確認します。 |
はい |
TRANSIENT_ERROR |
一時的なエラーは、自動的に解決されるエラーです。 通常、これらのエラーはデバイスまたはサービスへの接続が切断されたときに発生します。サーバーへの新しい接続を開けない場合も同様です。 |
|
UNABLE_TO_LOCATE_DEVICE |
Locator トレイトを使用してデバイスが見つかりませんでした（ping が失敗したなど）。 デバイスのローカル接続（Wi-Fi/Bluetooth）を確認します。 |
はい |
UNABLE_TO_RING_DEVICE |
デバイスにアクセスできましたが、着信音/アラート機能をトリガーできませんでした。 ハードウェアのアラート/スピーカーの状態と音量レベルを確認します。 |
はい |
UNABLE_TO_SILENCE_DEVICE |
デバイスでアクティブなアラート/着信音を停止できませんでした。 クラウドと物理デバイス間の通信エラーを調査します。 |
はい |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
予期しないエラーが発生しました。パートナー アプリを確認してください。
Google がサポートする同等のエラーがない場合に、エラーの包括的なキャッチオールとして使用します。 |
はい |
UNKNOWN_ERROR |
追加の詳細情報が提供されていない一般的なエラー。 トラブルシューティングを改善するため、より具体的なエラーコードに置き換えることを目指します。 |
はい |
UNLOCK_FAILURE |
スマートロックが「ロック解除」状態に到達できませんでした。 ハードウェアの詰まり、バッテリー残量の低下、無効な PIN の入力について調査します。 |
はい |
検索ログ
指標を使用して統合をモニタリングできるようになったら、次は 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: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。