Hybrid Trace API を使用する

このセクションでは、Apigee API を使用して Apigee ハイブリッドでデバッグセッションを操作する方法について説明します。

このセクションで使用する変数値

このセクションでは次の点に注意してください。

org_name は、ハイブリッド対応組織の名前です。
env_name は、デバッグする API プロキシがデプロイされる環境です。
api_proxy_name は、トレースセッションでデバッグする API プロキシの名前です。
revision_number は、デバッグ中の API プロキシバンドルで現在デプロイされているリビジョンの番号です。
debug_session_ID は、1 つの API プロキシの 1 つのセッションでトレースされるリクエストの一意の識別子です。
transaction_ID は、デバッグセッションで API プロキシへの 1 つのリクエストに関連付けられたトランザクションの一意の識別子です。

デバッグセッションを作成する

デバッグセッションを作成するには:

次の例のように、コマンドラインで gcloud の認証情報を取得します。
```
TOKEN=$(gcloud auth print-access-token)
```
トークンが入力されたことを確認するには、次の例のように echo を使用します。
```
echo $TOKEN
```
エンコードされた文字列が stdout に出力されます。

詳しくは、gcloud コマンドラインツールの概要をご覧ください。
認証済みの POST リクエストを Debug Sessions API に送信します。

次の例は、新しいデバッグセッションを作成するリクエストの構造を示しています。
```
curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions
```
リクエストが成功すると、次の例のように、ハイブリッドは新しく作成されたデバッグセッションを表す JSON オブジェクトを返します。
```
{
  "name":"56382416-c4ed-4242-6381-591bbf2788cf",
  "validity":300,
  "count":10,
  "tracesize":5120,
  "timeout":"600"
}
```
セッションの長さまたは最大リクエスト数に達するまで、API プロキシに対する以降のリクエストが評価され、デバッグセッションデータに格納されます。

デバッグセッションの長さを設定する

特定の期間を持つセッションを作成するには、デバッグセッションの作成リクエストで次のものをペイロードとして使用します。

{
  "timeout":"debug_session_length_in_seconds"
}

次の例は、42 秒の新しいデバッグセッションを作成します。

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions
  -d ' {
    "timeout":"42"
  } '

セッションの timeout は、デバッグセッションの作成リクエストでのみ設定できます。セッションの作成後にセッションの期間を変更することはできません。

timeout のデフォルト値は 300（5 分）です。最大値は 600 秒（10 分）です。

フィルタを使用してデバッグセッションを作成する

デバッグセッションでフィルタを使用すると、ハイブリッドが収集されるデータに必要なリクエストのみを含めることができます。たとえば、HTTP レスポンスコードが 599 未満のリクエストを除外できます。また、リクエストの値とカスタム変数を比較することもできます。

フィルタで除外され、デバッグセッションに含まれないリクエストは、デバッグセッションの最大トランザクション数に含まれません。

フィルタを使用してセッションを作成するには、デバッグセッション作成リクエストで次のものをペイロードとして使用します。

{
  "filter":"filter_body"
}

次の例は、ヘッダー「A」が 42、ヘッダー「B」が 43、エラーコードが「ExpectedEOF」のトランザクションのみを含む新しいデバッグセッションを作成します。

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

フィルタは、デバッグセッション作成リクエストでのみ定義できます。既存のデバッグセッションにはフィルタを追加できません。また、アクティブなデバッグセッションからフィルタを削除することもできません。

フィルタの作成の詳細については、フィルタをご覧ください。

デバッグセッションのリストを取得する

デバッグセッションのリストを取得するには:

次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。
```
TOKEN=$(gcloud auth print-access-token)
```

認証済みの GET リクエストを Debug Sessions API に送信します。

次の例は、デバッグセッションのリストを取得するリクエストの構造を示しています。

curl -H "Authorization: Bearer $TOKEN"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions

次の例のように、Apigee API は現在アクティブなデバッグセッションのリストを含む sessions オブジェクトを返します。

{
  "sessions": [
    {
      "id": "a423ac73-0902-4cfa-4242-87a353a84d87",
      "timestamp_ms": 1566330186000
    },
    {
      "id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
      "timestamp_ms": 1566330286000
    }
  ]
}

Debug Sessions API は、デバッグセッションがアクティブかどうかを示しません。

セッションを作成してもトランザクションがまだ存在しない場合、このリストにそのセッションは含まれません。セッションに 1 つ以上のトランザクションが存在する場合にのみ、セッションがレスポンスに含まれます。

デバッグセッションでトランザクションのリストを取得する

デバッグセッションでトランザクションのリストを取得するには:

次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。
```
TOKEN=$(gcloud auth print-access-token)
```

認証済みの GET リクエストを List Session Data API に送信します。

次の例は、指定されたデバッグセッションのトランザクションリストを取得するリクエストの構造を示しています。

curl -H "Authorization: Bearer $TOKEN"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data

debug_session_ID の値は、デバッグセッションのリストを取得するリクエストから取得できます。

次の例のように、Apigee API はトランザクション ID の配列を返します。

[
  "myorg-myenv-ver-5qxdb-64",
  "myorg-myenv-ver-5qxdb-65",
  "myorg-myenv-ver-5qxdb-66",
  "myorg-myenv-ver-5qxdb-67",
  "myorg-myenv-ver-5qxdb-68",
  "myorg-myenv-ver-5qxdb-69",
  "myorg-myenv-ver-5qxdb-70",
  "myorg-myenv-ver-5qxdb-71",
  "myorg-myenv-ver-5qxdb-72"
]

トランザクションデータを取得する

Get Debug Session Data API を使用すると、トランザクション ID を指定してトランザクションデータをダウンロードできます。この API では、セッションのすべてのデータを一度に取得することはできません。その場合は、UI を使用する必要があります。詳しくは、トレースデータをダウンロードするをご覧ください。

デバッグセッションで保存されるトランザクションデータは JSON 形式になります。このデータはオフライントレースツールで読み込むことができます。

デバッグセッションで特定のトランザクションのデータを取得するには:

次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。
```
TOKEN=$(gcloud auth print-access-token)
```
認証済みの GET リクエストを Get Debug Session Data API に送信します。

次の例は、デバッグセッションからトランザクションデータを取得するリクエストの構造を示しています。
```
curl -H "Authorization: Bearer $TOKEN"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data/transaction_ID
```
transaction_ID の値は、セッションのトランザクションリストを取得するリクエストから取得できます。

Apigee API は、指定されたトランザクションのデータを含む JSON ペイロードを返します。詳しくは、データ構造をダウンロードするをご覧ください。

トレースデータには、各フローのリクエストとレスポンスに関するすべての情報が独自の JSON 形式で含まれています。このデータを保存して、後でオフライントレースツールで使用できます。

セッションが終了する前にリクエストが 1 つも追加されなかった場合、レスポンスは次のようになります。
```
[]
```

デバッグセッションを停止する

開始したデバッグセッションを明示的に停止することはできません。デバッグセッションは、タイムアウトまたは最大トランザクション数に達するまで継続します。

デバッグセッションデータを削除する

すべてのトレースデータを削除するには:

次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。
```
TOKEN=$(gcloud auth print-access-token)
```
認証済みの DELETE リクエストを Debug Sessions API に送信します。

次の例は、すべてのトレースデータを削除するリクエストの構造を示しています。
```
curl -H "Authorization: Bearer $TOKEN" -X DELETE
  "https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data"
```
正常に削除されると、Apigee API のレスポンスにデータが含まれません。

デバッグセッションデータは 24 時間保持されます。その時間までに削除しない場合、ハイブリッドがデータを削除します。

Hybrid Trace API を使用する

このセクションで使用する変数値

デバッグ セッションを作成する

デバッグ セッションの長さを設定する

フィルタを使用してデバッグ セッションを作成する

デバッグ セッションのリストを取得する

デバッグ セッションでトランザクションのリストを取得する

トランザクション データを取得する

デバッグ セッションを停止する

デバッグ セッション データを削除する