Apigee への API トラフィック データのアップロード(ベータ版)

Edge for Private Cloud v4.18.05

すべての Edge for Private Cloud のお客様は、API プロキシのトラフィックに関する統計情報を Apigee に提供していただく必要があります。cron ジョブを作成することによって、1 日 1 回統計情報をアップロードすることを推奨しています。

本番環境にデプロイされた API のデータを提供していただく必要がありますが、開発環境やテスト環境にデプロイされた API のデータは提供していただく必要はありません。Edge 実装環境では、多くの場合、本番環境用 API に特定の組織または特定の環境を定義します。ご提供いただいたデータは、本番環境用の組織と環境にのみ使用されます。

それらのデータのアップロードを支援するため、Apigee はベータ版の apigee-analytics-collector コマンドライン ユーティリティを提供しています。このユーティリティは、API 呼び出しのボリューム レポートを Apigee に送り返します。すべての Edge for Private Cloud 実装環境では必ずこのユーティリティがトラフィック データを取得し Apigee にレポートします。

必須: データをアップロードする前の Apigee サポートへのお問い合わせ

データを Apigee にアップロードする前に、Apigee サポートにご連絡いただきオンボーディング プロセスを完了する必要があります。

apigee-analytics-collector のインストール

apigee-analytics-collector ユーティリティは、apigee-service ユーティリティを使用してインストールする RPM パッケージになります。

インストールする場所

Edge Management Server 上の Edge 管理 API にアクセスできる任意のノードに、apigee-analytics-collector ユーティリティをインストールできます。Management Server 上、Edge が実装された他のノード上、または分離したノードのうち Management Server に API リクエストを行えるノード上に、直接インストールすることもできます。

インターネット アクセスの要件

apigee-analytics-collector ユーティリティを、外部インターネット アクセスが可能なマシンにインストールしてください。そうすることで、apigee-analytics-collector ユーティリティは、Apigee にデータを直接アップロードできます。

Edge Management Server 上の Edge 管理 API へのアクセスが可能なノードと、外部インターネット アクセスが可能なノードの両方が存在しない場合は、Edge 管理 API を使用してトラフィック データをローカルに保存できます。その後、インターネット アクセスが可能なマシンにデータを転送し、Apigee にアップロードしてください。このシナリオでは、apigee-analytics-collector ユーティリティを使用する必要はありません。詳細については、後述の Apigee への手動データ アップロードをご覧ください。

インストール

次のコマンドを使用して、apigee-analytics-collector ユーティリティをインストールします。RPM ファイルをインストールするため、このコマンドは root ユーザーまたは sudo フルアクセス権限を持っているユーザーが実行する必要があります。sudo フルアクセス権限とは、root ユーザーと同じ操作を実施できる sudo アクセス権限をユーザーが持っていることを意味します。

    > /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector install
    

apigee-analytics-collector の実行

このセクションでは、apigee-analytics-collector ユーティリティを実行する方法について説明します。

apigee-analytics-collector を実行するようにユーザ-を構成

root ユーザー以外で apigee-analytics-collector を実行してください。このユーザーは、「apigee」ユーザーへの sudo フルアクセス権限を持っている必要があります。

「apigee」ユーザーへの sudo フルアクセス権限をユーザーに構成するには、「visudo」コマンドを使用することで sudoers ファイルを編集して、次に記載の内容を追加します。

    analyticsUser        ALL=(apigee)      NOPASSWD: ALL
    

analyticsUser は、apigee-analytics-collector ユーティリティを実行しているユーザーのユーザ―名です。

apigee-analytics-collector ユーティリティをインストールしてユーザーを構成した後、apigee-analytics-collector ユーティリティの help コマンドを実行してユーティリティをテストできます。

    > /opt/apigee/apigee-service/bin/ apigee-service apigee-analytics-collector export traffic --help
    

apigee-analytics-collector を実行するために必要な情報

apigee-analytics-collector コマンドを実行して Apigee にデータを転送するには、次の情報が必要です。

  • apigee_mgmt_api_uri: Management Server 上の Edge API のベース URL です。この URL の形式は通常、次のとおりです。
    http://ms_IP:8080/v1

    ms_IP は Management Server の IP アドレスで、8080 は Edge API によって使用されるポートです。Edge API の DNS エントリを作成した場合、URL の形式は次のとおりです。
    http://ms_DNS/v1

    Edge 管理 API で TLS を有効にした場合、URL の形式は次のとおりです。
    https://ms_IP:8080/v1
    https://ms_DNS/v1
  • apigee_mgmt_api_email: Edge /stats API へのアクセス権限を持つアカウントのメールアドレスです。多くの場合、Edge のシステム管理者のメールアドレス、または本番環境組織の組織管理者のメールアドレスが使用されます。
  • apigee_mgmt_api_password: apigee_mgmt_api_email で指定したアカウントの Edge パスワードです。
  • apigee_analytics_client_idapigee_analytics_secret: Apigee にデータをアップロードするための認証情報です。Apigee サポートにチケットを送信して、apigee_analytics_client_idapigee_analytics_secret を取得してください。

コマンド例

以下は、Edge 実装環境内のすべての組織と環境のトラフィック データを取得して、Apigee にそのデータをアップロードするコマンド例になります。次の apigee-analytics-collector コマンドを実行するには、apigee-service を使用することに留意してください。

    >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic \
    --apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
    --apigee_mgmt_api_email $ae_username \
    --apigee_mgmt_api_password $ae_password \
    --apigee_analytics_client_id $apigee_analytics_client_id \
    --apigee_analytics_secret $apigee_analytics_secret
    

このコマンドには、apigee_analytics_client_idapigee_analytics_secret などの必要な情報がすべて含まれていることに留意してください。

実行結果は次のようになります。

    [
      {
        "org": "myOrg",
        "env": "prod",
        "time_range_start": "08/27/2016 00:00",
        "time_range_end": "08/30/2016 00:00",
        "response": [
          {
            "store_org_env_metrics_hourly_v4": 1
          }
        ]
      },
      {
        "org": "VALIDATE",
        "env": "test",
        "time_range_start": "08/27/2016 00:00",
        "time_range_end": "08/30/2016 00:00",
        "response": [
          {
            "store_org_env_metrics_hourly_v4": 1
          }
        ]
      }
    ]
    

コマンドにコマンドライン オプションを使用することで、挙動をコントロールできます。生成されたデータに含める組織と環境を指定するには、次のオプションを使用します。

  • -i、--include_orgs <comma-separated list of items>
  • -x、--exclude_orgs <comma-separated list of items>
  • -n、--include_envs <comma-separated list of items>
  • -e、--exclude_envs <comma-separated list of items>

たとえば、本番環境の組織と環境のみを指定するには、-i(または --include_orgs)と -n(または --include_envs)オプションを使用します。

    >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod \
    --apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
    --apigee_mgmt_api_email $ae_username \
    --apigee_mgmt_api_password $ae_password \
    --apigee_analytics_client_id $apigee_analytics_client_id \
    --apigee_analytics_secret $apigee_analytics_secret
    

この例では、myOrg の本番環境からデータを収集するのみとなります。

Apigee にデータを送信する前に、データを画面に表示して検証するには、次のように -S オプションを使用します。

    >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S \
    --apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
    --apigee_mgmt_api_email $ae_username \
    --apigee_mgmt_api_password $ae_password \
    --apigee_analytics_client_id $apigee_analytics_client_id \
    --apigee_analytics_secret $apigee_analytics_secret
    

-S オプションは、Apigee へのデータ アップロードを省略します。-S オプションなしでコマンドを再実行することで、データを Apigee に送信できます。

-S オプションを使用する理由の 1 つは、異なるタイプのデータをローカルで表示できるようにするためです。Apigee では、API トラフィック データのアップロードのみを必要としますが、-D オプションは API プロダクト、デベロッパー、アプリ、API プロキシに関するデータを表示します。次の例では、-D-S オプションを使用してローカルでデベロッパー データを表示します。

    >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -D devs \
    --apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
    --apigee_mgmt_api_email $ae_username \
    --apigee_mgmt_api_password $ae_password \
    --apigee_analytics_client_id $apigee_analytics_client_id \
    --apigee_analytics_secret $apigee_analytics_secret
    

-v オプションを使用することで詳細な出力を取得します。-R オプションを使用することで apigee-analytics-collector によって生成される curl コマンドを表示します。

     >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -R -v \
    --apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
    --apigee_mgmt_api_email $ae_username \
    --apigee_mgmt_api_password $ae_password \
    --apigee_analytics_client_id $apigee_analytics_client_id \
    --apigee_analytics_secret $apigee_analytics_secret
    

次のセクションでは、すべてのコマンドライン オプションをリストに記載します。

コマンド パラメータ

次の表は、apigee-analytics-collector ユーティリティのすべてのオプションを示します。

コマンド

用途

-h、--help

使用状況情報を出力

-D、--dimension <dimension>

収集するトラフィックのディメンション。有効なディメンション: apiproductsdevsappsapiproxy(デフォルト)

-d、--days <days>

収集するデータの、現時点の日付から数えた遡る日数。デフォルトは 3 です。

-d を指定する場合、期間を設定する -s-z を指定しないでください。

-m、--apigee_mgmt_api_uri <apigee_mgmt_api_uri>

Edge 管理 API への URL

-u、--apigee_mgmt_api_email <apigee_mgmt_api_email>

Edge /stats API へのアクセス権限を持つアカウントのメールアドレス。多くの場合、Edge のシステム管理者のメールアドレス、または本番環境組織の組織管理者のメールアドレスが使用されます。

-p、--apigee_mgmt_api_password <apigee_mgmt_api_password>

-u で指定された Edge 管理 API メール アカウントに関連付けられたパスワード

-i、--include_orgs <items>

出力に含めるカンマ区切りの組織リスト

-x、--exclude_orgs <items>

出力から除外するカンマ区切りの組織リスト

-n、--include_envs <items>

出力に含めるカンマ区切りの環境リスト

-e、--exclude_envs <items>

出力から除外するカンマ区切りの環境リスト

-o、--output <path>

出力を保存するパスとファイル名

-s、--time_range_start <time_range_start>

トラフィック統計情報のクエリを開始する期間。形式: 「03/01/2016 00:00」

-d を指定する場合、期間を設定する -s と -z を指定しないでください。

-z、--time_range_end <time_range_end>

トラフィック統計情報のクエリを終了する期間。形式: 「04/01/2016 24:00」

-d を指定する場合、期間を設定する -s と -z を指定しないでください。

-t、--time_unit <time_unit>

トラフィック データの時間単位。デフォルトは週。デフォルトの単位は時間。有効な時間単位: 秒、分、時間、日、週

-S、--standard_output

出力を apigee にアップロードせずに、デバイスに標準出力(stdout)で書き出し

-c、--apigee_analytics_client_id <apigee_analytics_client_id>

Apigee にデータをアップロードするための ID。取得するには、Apigee サポートにチケットを送信してください。

-r、--apigee_analytics_secret <apigee_analytics_secret>

Apigee にデータをアップロードするためのシークレット情報。取得するには、Apigee サポートにチケットを送信してください。

-R、--include_curl_commands

デバッグのために、生成された cURL コマンドを出力に含めます。

-v、--verbose

詳細な出力を表示

Apigee へのデータ手動アップロード

外部インターネット アクセスが可能なマシンに、apigee-analytics-collector ユーティリティをインストールすることを推奨しています。そうすることで、apigee-analytics-collector ユーティリティは、Apigee にデータを直接アップロードできます。

ただし、インストール対象のマシンに外部インターネット アクセスがない場合は、Edge 管理 API を使用してトラフィック データを収集した後、cURL コマンドを使用してインターネットにアクセスできるマシンから Apigee にデータをアップロードします。Edge 実装環境内のすべての本番環境の組織と環境に対して、この手順を繰り返してください。

次の cURL コマンドを使用して、特定の組織と環境のトラフィック データを指定の時間間隔で収集します。

    curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
    "http://<ms_IP>:8080/v1/organizations/{org_name}/environments/{env_name}/stats/apiproxy?select=sum(message_count)&timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM&timeUnit=hour"
    

このコマンドは、Edge Get API のメッセージ カウント API を使用します。このコマンド内でのパラメータについては次で説明します。

  • apigee_mgmt_api_email:apigee_mgmt_api_password では、Edge /stats API へのアクセス権限を持つアカウントのメールアドレスを指定します。
  • <ms_IP> は、Edge Management Server の IP アドレスまたは DNS 名です。
  • {org_name}{env_name} では、組織と環境を指定します。
  • apiproxy は、API プロキシによって指標をグループ化するディメンションです。
  • MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM&timeUnit=hour では、収集する指標の時間単位に分割された期間を指定します。cURL コマンドは、期間のスペースに 16 進コード %20 を使用していることに注意してください。

たとえば、24 時間にわたって 1 時間ごとに API プロキシ メッセージ カウントを収集するには、次の管理 API 呼び出しを使用します。timeRange には、URL にエンコードされた文字が含まれます。

    curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
    "http://192.168.56.103:8080/v1/organizations/myOrg/environments/prod/stats/apiproxy?select=sum(message_count)&timeRange=01%2F01%2F2018%2000%3A00~01%2F02%2F2018%2000%3A00&timeUnit=hour"
    

レスポンスが次の形式で表示されます。

    {
      "environments" : [ {
        "dimensions" : [ {
          "metrics" : [ {
            "name" : "sum(message_count)",
            "values": [
                    {
                      "timestamp": 1514847600000,
                      "value": "35.0"
                    },
                    {
                      "timestamp": 1514844000000,
                      "value": "19.0"
                    },
                    {
                      "timestamp": 1514840400000,
                      "value": "58.0"
                    },
                    {
                      "timestamp": 1514836800000,
                      "value": "28.0"
                    },
                    {
                      "timestamp": 1514833200000,
                      "value": "29.0"
                    },
                    {
                      "timestamp": 1514829600000,
                      "value": "33.0"
                    },
                    {
                      "timestamp": 1514826000000,
                      "value": "26.0"
                    },
                    {
                      "timestamp": 1514822400000,
                      "value": "57.0"
                    },
                    {
                      "timestamp": 1514818800000,
                      "value": "41.0"
                    },
                    {
                      "timestamp": 1514815200000,
                      "value": "27.0"
                    },
                    {
                      "timestamp": 1514811600000,
                      "value": "47.0"
                    },
                    {
                      "timestamp": 1514808000000,
                      "value": "66.0"
                    },
                    {
                      "timestamp": 1514804400000,
                      "value": "50.0"
                    },
                    {
                      "timestamp": 1514800800000,
                      "value": "41.0"
                    },
                    {
                      "timestamp": 1514797200000,
                      "value": "49.0"
                    },
                    {
                      "timestamp": 1514793600000,
                      "value": "35.0"
                    },
                    {
                      "timestamp": 1514790000000,
                      "value": "89.0"
                    },
                    {
                      "timestamp": 1514786400000,
                      "value": "42.0"
                    },
                    {
                      "timestamp": 1514782800000,
                      "value": "47.0"
                    },
                    {
                      "timestamp": 1514779200000,
                      "value": "21.0"
                    },
                    {
                      "timestamp": 1514775600000,
                      "value": "27.0"
                    },
                    {
                      "timestamp": 1514772000000,
                      "value": "20.0"
                    },
                    {
                      "timestamp": 1514768400000,
                      "value": "12.0"
                    },
                    {
                      "timestamp": 1514764800000,
                      "value": "7.0"
                    }
                  ]
                }
              ],
              "name" : "proxy1"
          } ],
        "name" : "prod"
      } ],
      "metaData" : {
        "errors" : [ ],
        "notices" : [ "query served by:53dab80c-e811-4ba6-a3e7-b96f53433baa", "source pg:6b7bab33-e732-405c-a5dd-4782647ce096", "Table used: myorg.prod.agg_api" ]
      }
    }
    

取得したデータをインターネットにアクセスできるマシンから Apigee にアップロードするには、次の cURL コマンドを使用します。

    curl -X POST -H 'Content-Type:application/json' \
    -u apigee_analytics_client_id:apigee_analytics_secret \
    https://nucleus-api-prod.apigee.com/v1/apigee-analytics-cli-api/traffic/orgs/{org_name}/apis -d '{"environments"...}'
    

各パラメータの説明は次のとおりです。

  • apigee_analytics_client_id:apigee_analytics_secret では、Apigee サポートから取得したデータを Apigee にアップロードするための認証情報を指定します。
  • {org_name} では、組織を指定します。
  • {"environments" ...} には、上記の統計情報を収集するために使用した cURL コマンドの結果が含まれています。