Google Cloud には、Google Cloud Monitoring を使用してプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログを使用して問題をデバッグするツールが用意されています。ユーザー インテントのフルフィルメントでエラーが発生するたびに、Google Home Analytics パイプラインはその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングできます。
- エラーログでエラーの詳細な説明を確認して、問題を調査します。
エラーをモニタリングする
プロジェクト指標にアクセスするには、Google Cloud Monitoring dashboard を使用します。品質のモニタリングとデバッグに特に役立つ重要なグラフがいくつかあります。
- [成功率] グラフは、プロジェクトの信頼性をモニタリングするときに最初に使用するグラフです。このグラフの急激な減少は、ユーザーベースの一部またはすべてが停止している可能性を示します。プロジェクトを変更または更新するたびに、このグラフに異常がないか注意深くモニタリングすることをおすすめします。
- 95 パーセンタイル レイテンシ グラフは、ユーザーに対するスマートホーム アクションのパフォーマンスを示す重要な指標です。このグラフが急激に変動した場合、システムがリクエストに追い付いていない可能性があります。予期しない動作が発生しないように、このグラフを定期的に確認することをおすすめします。
- [Error Breakdown] グラフは、統合の問題のトラブルシューティングを行う際に役立ちます。成功率グラフでハイライト表示されているエラーごとに、エラーの内訳にエラーコードが表示されます。Google Home platform でフラグが付けられたエラーとそのトラブルシューティング方法を次の表に示します。
プラットフォームのエラーコード
ここでは、Google Home platform でキャッチされた問題を特定するためにプロジェクト ログに表示される一般的なエラーコードについて説明します。トラブルシューティング情報については、次の表をご覧ください。
| エラーコード | 説明 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google が、401 以外の HTTP 4xx エラーコードをサービスから受け取りました。 GCP Logging の requestId を使用して、スマートホーム サービスのログを確認します。
|
BACKEND_FAILURE_URL_TIMEOUT |
サービスに接続しようとしたときに、Google からのリクエストがタイムアウトしました。 サービスがオンラインで、接続を受け入れていて、容量を超えていないことを確認します。また、対象デバイスの電源が入っていて、オンラインになっていて、同期されていることも確認します。 |
BACKEND_FAILURE_URL_UNREACHABLE |
Google がサービスから HTTP 5xx エラーコードを受信しました。 GCP Logging の requestId を使用して、スマートホーム サービスのログを確認します。
|
DEVICE_NOT_FOUND |
デバイスがパートナー サービス側に存在しない。
これは通常、データ同期の失敗または競合状態を示します。 |
GAL_BAD_3P_RESPONSE |
ペイロードの形式または値が無効であるため、アカウント リンク サービスからのレスポンスを解析できません。 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 |
ユーザーのアクセス トークンの有効期限が切れており、トークンの更新がもう 1 回同時試行されています。 これは問題ではなく、対応は必要ありません。 |
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 オブジェクトとして正しく構造化されていることを確認してください。 |
PROTOCOL_ERROR |
リクエストの処理中にエラーが発生しました。 Google Cloud Logging の requestId を使用して、スマートホーム サービスのログを確認します。
|
RESPONSE_TIMEOUT |
レスポンスの待機中にリクエストがタイムアウトしました。 レスポンス送信のタイムアウト期間は、リクエスト送信から 9 秒です。この時間内にレスポンスを送信してください。 |
RESPONSE_UNAVAILABLE |
レスポンスが届かないか、レスポンスにステータスが示されていません。 インテント フルフィルメント リクエストに対するレスポンスは、 スマートホームのドキュメントに従って構造化し、ステータスを示す必要があります。 |
TRANSIENT_ERROR |
一時的なエラーとは、自動的に解決されるエラーです。 これらのエラーはほとんどの場合、ドロップされるデバイスやサービスへの接続として現れます。また、サーバーへの新しい接続を開くことができない場合にも発生します。 |
検索ログ
指標を使用して統合をモニタリングする方法がわかったら、次に 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: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。