Hybrid Trace API を使用する

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

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

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

  1. 次の例のように、コマンドラインで gcloud の認証情報を取得します。

    TOKEN=$(gcloud auth print-access-token)

    トークンが入力されたことを確認するには、次の例のように echo を使用します。

    echo $TOKEN

    エンコードされた文字列が stdout に出力されます。

    詳しくは、gcloud コマンドライン ツールの概要をご覧ください。

  2. 認証済みの 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'"
      } '

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

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

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

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

  1. 次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。

    TOKEN=$(gcloud auth print-access-token)

  2. 認証済みの 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 つ以上のトランザクションが存在する場合にのみ、セッションがレスポンスに含まれます。

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

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

  1. 次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。

    TOKEN=$(gcloud auth print-access-token)

  2. 認証済みの 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 形式になります。このデータはオフライン トレースツールで読み込むことができます。

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

  1. 次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。

    TOKEN=$(gcloud auth print-access-token)

  2. 認証済みの 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 つも追加されなかった場合、レスポンスは次のようになります。

    []

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

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

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

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

  1. 次の例のように、コマンドラインで gcloud の認証情報を取得または更新します。

    TOKEN=$(gcloud auth print-access-token)

  2. 認証済みの 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 時間保持されます。その時間までに削除しない場合、ハイブリッドがデータを削除します。