Google Cloud プロジェクトの信頼性をモニタリングし、Google Cloud Monitoringで問題をデバッグするためのツールが用意されていますGoogle Cloud Logging エラーログ。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインがその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングする。
- エラーログでエラーの詳しい説明を確認して問題を調査する。
必要に応じて、アクションを他のユーザーと 共有してテストできます。エラーと例外の処理を適切に行えるようにします。
エラーをモニタリングする
Google Cloud Monitoring dashboards を使用して、プロジェクトの指標にアクセスできます。品質のモニタリングとデバッグにおいて、特に役に立つグラフをいくつか紹介します。
- 成功率 のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。このグラフを慎重にチェックし、プロジェクトに変更や更新を加えた後に異常が発生していないかを確認します。
- 95 パーセンタイル レイテンシ のグラフは、 ユーザーに対してCloud-to-cloud 統合がどのように機能しているかを示す重要な指標です。 このグラフが突然変動した場合、システムによるリクエストの処理が追いついていない可能性があります。予期しない動作が発生しないように、このグラフを定期的に確認することをおすすめします。
- エラーの内訳 のグラフは、統合の問題のトラブルシューティングにおいて特に役立ちます。成功率グラフでハイライト表示されたすべてのエラーについて、その内訳とエラーコードを確認できます。Google Home platform によってフラグが設定されたエラーとそのトラブルシューティング方法については、以下の表をご覧ください。
一般的なプラットフォーム エラーコード
プロジェクト ログに表示される可能性のある一般的なエラーコードを以下に示します。これらのエラーコードは、Google Home platformによって検出された問題を特定するために使用できます。トラブルシューティング情報については、次の表をご覧ください。エラーコードの完全なリストについては、 次を ご覧ください。エラーと例外
| エラーコード | 説明 | パートナーが対応可能 |
|---|---|---|
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 テストスイートを使用して 修正を徹底的にテストすることをおすすめしますGoogle Home Test Suite。修正のテストを効果的に行う方法については、 Test Suiteのユーザーガイドで詳しく説明しています。
学習用リソース
このドキュメントでは、スマートホーム アクションのエラーをトラブルシューティングする手順について説明しています。デバッグの詳細については、以下の Codelab も参考にしてください。
- Codelab: スマートホームのデバッグ: スマートホームのクラウド統合をデバッグするためのクイック スタートガイドです。
- Codelab: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。