Google Cloud Platform (GCP) には、Google Cloud Monitoring and debug issues with Google Cloud Logging error logs. Whenever a failure happens when fulfilling user intents, Google Home Analytics pipeline records that failure on your metrics, and publishes an error log in your project logs. を使用してプロジェクトの信頼性をモニタリングするツールが用意されています。
エラーのトラブルシューティングは、次の 2 つの手順で行います。
- スマートホームの指標でプロジェクトの状態をモニタリングする。
- エラーログでエラーの詳しい説明を確認して調査する。
ローカル統合の場合も手順は同様です。トラブルシューティングのフローを習得すると、指標とログを簡単に行き来して、エラーに関する分析情報を得ることができます。
エラーをモニタリングする
プロジェクトの指標にアクセスするには、Google Cloud Monitoring dashboard s を使用します。品質のモニタリングとデバッグで特に役立つ主要なグラフがいくつかあります。
- 成功率のグラフは、プロジェクトの信頼性をモニタリングする際にまず確認すべきグラフです。このグラフが急激に低下している場合、ユーザーベースの一部または全体が停止している可能性があります。このグラフを注意深くモニタリングして、プロジェクトに変更や更新を加えた後に異常が発生していないかチェックすることをおすすめします。
- エラーの内訳のグラフは、統合に関する問題のトラブルシューティングで特に役立ちます。成功率グラフでハイライト表示されたすべてのエラーについて、エラーの内訳にエラーコードが表示されます。Google Home platform and how to troubleshoot them in the table below. によって報告されたエラーを確認できます。
プラットフォームのエラーコード
Google Home platform でキャッチされた問題を特定するためにプロジェクト ログに表示される一般的なエラーコードを次に示します。次の表に、トラブルシューティング情報を示します。
| エラーコード | 説明 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
サービスから 401 以外の HTTP 4xx エラーコードを受信しました。 スマートホーム ログを確認するには、GCP Logging の requestId を使用します。
|
BACKEND_FAILURE_URL_UNREACHABLE |
サービスから HTTP 5xx エラーコードを受信しました。 スマートホーム ログを確認するには、GCP Logging の requestId を使用します。
|
GAL_BAD_3P_RESPONSE |
ペイロードの形式または値が無効であるため、Google はアカウントのリンク サービスからのレスポンスを解析できません。 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 |
ユーザーのアクセス トークンが期限切れで更新できない、またはサービスから 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 オブジェクトとして正しく構造化されていることを確認してください。 |
RESPONSE_TIMEOUT |
レスポンスを待機している間にリクエストがタイムアウトしました。
レスポンスの送信がタイムアウトするまでの時間は、リクエストが送信されてから 9 秒です。この時間内にレスポンスが送信されていることを確認してください。 |
RESPONSE_UNAVAILABLE |
レスポンスを受信していないか、レスポンスにステータスが示されていません。 インテントのフルフィルメント リクエストに対するレスポンスは、スマートホームのドキュメントに沿って構造化し、ステータスを示す必要があります。 |
検索ログ
指標を使用して統合をモニタリングできるようになったら、次のステップとして Cloud Logging を使用して特定のエラーのトラブルシューティングを行います。エラーログは、時間、エラーコード、スマートホーム インテントの詳細などの有用な情報を含むフィールドを含む JSON に似たエントリです。
GCP 内に複数のシステムがあり、常にプロジェクトにログを送信します。ログをフィルタリングするクエリを作成して、必要なクエリを見つける必要があります。クエリは、期間、リソース、ログの重大度、またはカスタム エントリに基づいて作成できます。
クエリボタンを使用してカスタム フィルタを作成できます。
期間を指定するには、期間選択ボタン をクリックし、表示されるオプションのいずれかを選択します。これにより、ログがフィルタされ、選択した期間に発生したログのみが表示されます。
リソースを指定するには、[リソース] プルダウンをクリックして、[Google アシスタント アクション プロジェクト] を選択します。これにより、クエリにフィルタが追加され、プロジェクトで発生したログが表示されます。
[重大度] ボタンを使用して、緊急、情報、デバッグ、その他の重大度のログレベルでフィルタします。
Logs Explorer
to enter custom entries. The query engine used by this field supports both
basic queries like string matching, and more advanced types of queries including
comparators (<, >=, !=) and boolean operators (AND, OR, NOT). の [クエリ] フィールドを使用することもできます。
たとえば、以下のカスタム エントリは LIGHT デバイスタイプで発生したエラーを返します。
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
ログを効果的にクエリするその他の例については、クエリ ライブラリをご覧ください。
修正をテストする
エラーを特定して修正を適用したら、Google Home Test Suite を使用して修正を徹底的にテストすることをおすすめします。Google では、Test Suite の使用方法に関するユーザーガイドを提供しています。このガイドでは、変更を効果的にテストする方法について説明します。
学習リソース
このドキュメントでは、スマートホーム アクションのエラーをトラブルシューティングする手順について説明しています。デバッグの詳細については、以下の Codelab も参考にしてください。
- Codelab: スマートホームのデバッグ: スマートホームのクラウド統合をデバッグするためのクイック スタートガイドです。
- Codelab: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイック スタートガイドです。