Matter 統合エラーのトラブルシューティング

refresh_date: 2023-01-06

Google Cloud には、Google Cloud Monitoring でプロジェクトの信頼性をモニタリングし、Google Cloud Logging エラーログで問題をデバッグするためのツールが用意されています。ユーザー インテントのフルフィルメントに失敗すると、Google Home アナリティクスのパイプラインがその失敗を指標に記録し、プロジェクト ログにエラーログを公開します。

エラーのトラブルシューティングは、次の 2 つの手順で行います。

  1. スマートホームの指標でプロジェクトの状態をモニタリングする。
  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 お客様のサービスから HTTP 5xx エラーコードが返されました。

GCP Logging の requestId を使用して、スマートホーム サービスのログを確認します。
DEVICE_NOT_FOUND デバイスがパートナー サービス側に存在しません。

これは通常、データ同期の失敗または競合状態を示します。
GAL_BAD_3P_RESPONSE ペイロードの形式または値が無効であるため、Google はアカウント リンク サービスからのレスポンスを解析できません。

GCP Logging の requestId を使用して、アカウント リンク サービスのエラーログを確認します。
GAL_INTERNAL アクセス トークンを取得しようとしたときに Google 内部エラーが発生しました。

GCP Logging でこのエラーの発生率が増加している場合は、詳細についてお問い合わせください。
GAL_INVALID_ARGUMENT アクセス トークンを取得しようとしたときに Google 内部エラーが発生しました。

GCP Logging でこのエラーの発生率が増加している場合は、詳細についてお問い合わせください。
GAL_NOT_FOUND Google に保存されているユーザーのアクセス トークンと更新トークンは無効になり、更新できなくなります。サービスを継続するには、ユーザーがアカウントを再度リンクする必要があります。

GCP Logging でこのエラーの発生率が増加している場合は、詳細についてお問い合わせください。
GAL_PERMISSION_DENIED トークンの共有が承認されていないときに、Google 内部エラーが発生しました。

GCP Logging でこのエラーの発生率が増加している場合は、詳細についてお問い合わせください。
GAL_REFRESH_IN_PROGRESS ユーザーのアクセス トークンが期限切れになり、別の同時実行の更新がすでに進行中です。

これは問題ではなく、対応は必要ありません。
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 つ以上のインテントが見つかりません。

EXECUTE レスポンスが正しく構造化されていること、リクエストからのすべてのインテントの結果がレスポンスに含まれていることを確認します。
PARTNER_RESPONSE_MISSING_DEVICE レスポンスに、リクエスト内の 1 つ以上のデバイスが見つかりません。

EXECUTE レスポンスが正しく構造化されていること、リクエストからのすべてのデバイス ID がレスポンスに含まれていることを確認します。
PARTNER_RESPONSE_MISSING_PAYLOAD レスポンスに payload フィールドが含まれていません。

リクエスト レスポンスにペイロード フィールドが含まれていることを確認します。 EXECUTE レスポンスを正しく構築する方法を参照してください。
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 には、プロジェクトに常にログを送信する複数のシステムがあります。目的のログを探すには、ログをフィルタするクエリを記述する必要があります。クエリを作成するには、「期間」または「リソース」を指定するか、ログの重大度またはカスタム エントリを記述します。

Cloud ログをクエリする

クエリボタンを使用すると、カスタム フィルタを作成できます。

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 も参考にしてください。

前へ
Cloud Logging が重要