refresh_date: 2023 年 1 月 6 日
Google Cloud には、Google Cloud Monitoring でプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログで問題をデバッグするためのツールが用意されています。ユーザー インテントのフルフィルメントでエラーが発生すると、Google Home アナリティクスのパイプラインは、その失敗を指標に記録し、プロジェクト ログにエラーログをパブリッシュします。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホーム指標でプロジェクトの状態をモニタリングできます。
- エラーログで詳細なエラーの説明を確認して問題を調査します。
エラーをモニタリングする
Google Cloud Monitoring dashboard を使用してプロジェクトの指標にアクセスできます。品質とデバッグのモニタリングに特に役立つ重要なグラフがいくつかあります。
- [成功率] グラフは、プロジェクトの信頼性をモニタリングするときに最初に表示されるグラフです。このグラフの減少は、ユーザーベースの一部またはすべてが停止していることを示している可能性があります。プロジェクトを変更または更新するたびに、このグラフで異常を注意深くモニタリングすることをおすすめします。
- [エラーの内訳] グラフは、統合に関する問題のトラブルシューティングに役立ちます。成功率のグラフでハイライト表示されたエラーごとに、エラーの内訳にエラーコードが表示されます。次の表に、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 |
ユーザーのアクセス トークンが期限切れになり、別の同時更新の試行がすでに進行中です。 これは問題ではなく、特に対応は必要ありません。 |
INVALID_AUTH_TOKEN |
サービスから 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 アシスタント アクション プロジェクト] を選択します。これにより、クエリにフィルタが追加され、プロジェクトから取得したログが表示されます。
[重大度] ボタンを使用して、[Emergency]、[Info]、[Debug] などの重大度のログレベルでフィルタします。
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: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。