拡張機能のデバッグ

拡張機能のデバッグには、Trace ツールと拡張機能ログの 2 か所に表示されるメッセージを使用します。拡張機能が機能しない場合、問題を特定するためにこの両方からの情報が必要になることがあります。

Apigee Edge の Trace ツールを使って、API の開発中に API プロキシコードのテストや編集を繰り返し行うことができます。トレースメッセージには、API プロキシコード（API プロキシやポリシー構成など）からのエラーが含まれます。

通常 Trace ツールに表示される拡張機能関連のエラーには、HTTP エラーコードに加えて拡張機能の呼び出しが失敗したということ以外、詳細な情報はあまり含まれていません。ここで何か役に立つ情報が見つからない場合、次に確認すべきものは、使用中の拡張機能のログです。
拡張機能は、実行時にログエントリを生成します（拡張機能ログを使用できるのは、組織管理者だけです）。

このログには、拡張機能がやりとりするように構成されている外部リソースから返されたエントリが含まれます。たとえば、拡張機能で外部リソースの認証情報が誤って構成されていると、ここにエラーが表示される可能性があります。

ログには、内部の拡張機能コードからのエントリも含まれます。ログを調べる際は、一部のエントリが修正中のエラーと無関係であることに注意してください。通常、拡張機能関連のログエントリは、次に示す Cloud Pub/Sub 拡張機能のログエントリのように details で始まります。
```
details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'
```

エラーの種類と原因

拡張機能のリクエスト処理は、API プロキシの Extension Callout ポリシーから、拡張機能を介して外部リソースに流れ、その後再び戻ります。そのため、このうちのどこかでエラーが発生するおそれがあります。

表示されるエラーは、次のカテゴリに分類されます。

拡張機能構成のエラー

これは、拡張機能を環境に追加するときに組織管理者が行う構成です。

たとえば、正しくない GCP プロジェクト ID で Stackdriver Logging 拡張機能を構成した場合、Google Stackdriver が拡張機能にエラーを返します。このエラーの詳細情報は通常、拡張機能ログにあります。

Trace ツールでのエビデンス

このエラーは通常、プロキシエディタで 4xx または 5xx レベルのエラーとして表示されます。ただしプロキシエディタでは、拡張機能がエラーを返したということ以外、エラーの原因についての詳細は表示されません。

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

拡張機能ログでのエビデンス

この種のエラーについての詳細情報がある場合、拡張機能のログエントリに表示されます。Cloud Pub/Sub サービスによって返される次のエラーメッセージは、不正な形式のプロジェクト ID が原因です。

details: 'Project does not exist: example-test-12345'

Extension Callout ポリシー構成のエラー

このエラーは Extension Callout ポリシーが正しく構成されていない場合に、ポリシー構成の構文エラー、不正な構成キーまたは値のエラーのいずれかを介して発生します。このエラーには、ポリシーの構成方法に応じて次の 2 種類があります。

外部リソースによって正しくないと評価された値

これは、拡張機能で構成にはエラーがないと評価されたものの、外部リソースではエラーだと評価された場合に発生します。たとえば、拡張機能が不正なデータベース ID を Cloud Spanner に渡した場合、Cloud Spanner によってエラーが返されて拡張機能ログに記録されます。
```
details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'
```
これは、ポリシーの <Input> 要素の構成 JSON が正しくない場合にも発生することがあります。拡張機能の中には、JSON の一部が拡張機能によって処理され、一部がリソースに渡されるものもあります。たとえば、Stackdriver Logging 拡張機能の構成 JSON には、コンテンツが Stackdriver Logging に渡される metadata オブジェクトが含まれています。キー名が正しくない（type ではなく typ など）場合に、外部リソースから返されるエラーがエントリとして拡張機能ログに表示されることがあります。
```
details: 'Resource type cannot be empty'
```
拡張機能によって正しくないと評価された値

このエラーには、<Input> 要素のポリシー評価部分の構文エラー、<Action> 要素のアクション名のスペルミスなどがあります。このエラーは通常 Trace ツールに表示され、拡張機能ログには表示されません。

Trace ツールでのエビデンス

このエラーは通常、プロキシエディタで 4xx または 5xx レベルのエラーとして表示されます。ただしプロキシエディタでは、拡張機能がエラーを返したということ以外、エラーの原因についての詳細は表示されません。Cloud Firestore 拡張機能のアクション名のスペルを間違えると、Trace ツールに次のエラーが表示されます。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

拡張機能ログでのエビデンス

ポリシー構成によって外部リソースに処理エラーが発生すると、通常エラーはログに記録されます。

リソースに対する拡張機能のリクエストに関連したエラー

これは、外部リソースへのリクエストが、拡張機能には無関係の理由で成功しなかったというエラーです。

たとえば、Cloud Spanner 拡張機能を使用して行をデータベースに追加し、その行の主キー値が既存の行ですでに使用されているとします。この場合 Cloud Spanner は拡張機能にエラーを返し、拡張機能ログにエラーが追加されます。

Trace ツールでのエビデンス

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

拡張機能ログでのエビデンス

通常ログには、外部リソース自体からのメッセージを含むエントリが記録されます。次に示す Cloud Spanner からのログメッセージには、既存の主キー値のエラーが記録されています。

details: 'Row [jonesy42] in table user already exists'