このページの内容は Apigee と Apigee ハイブリッドに該当します。
Apigee Edge のドキュメントを表示する。
Apigee は、API 間で送受信される幅広い運用データとビジネスデータを記録します。このデータから導出される指標は、運用のモニタリングやビジネスのモニタリングに役立ちます。Apigee Analytics を使用すると、パフォーマンスが高いまたは低い API、最も値の大きいトラフィックを送信しているデベロッパー、バックエンド サービスで最も多くの問題を起こしているアプリなどを判別できます。
この指標データに簡単にアクセスするために、自動化クライアントまたはスクリプトを使用して定期的に指標を取得するなど、特定の分析機能を自動化する必要がある場合は、この指標 API を使用します。また、この API を使用して、カスタム ウィジェットという形で独自の可視化機能を作成し、そのウィジェットをポータルやカスタムアプリに組み込むこともできます。
Apigee UI で Analytics を使用する方法については、Apigee Analytics の概要をご覧ください。
指標 API について
指標 API を使用するには、次の 2 つの方法があります。
- 1 時間、1 日、1 週間など、一定期間にわたる組織と環境の指標を取得します。このメソッドでは、組織全体と環境全体の生の指標が返されます。
たとえば、前の週について次の指標を取得できます。
- ポリシーエラー数
- 平均応答時間
- 総トラフィック
組織と環境の一定期間にわたる指標をディメンションを基準に整理した指標を取得します。
たとえば、前週分について、API プロダクト、API プロキシ、デベロッパーのメールアドレス（AppGroup ID でも可）ごとに指標をグループ化するためにディメンションを使用すると、以下を取得できます。
- API プロダクトあたりのポリシーエラー数
- API プロキシあたりの平均応答時間
- デベロッパーのメールあたりの総トラフィック
返された結果を管理するために、指標 API は次の機能をサポートします。
詳細については、Metrics API リファレンスをご覧ください。
指標 API を使ってみる
指標 API のリクエスト URL は次のとおりです。
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]
たとえば、API プロキシごとにグループ分けされた指標を取得するには、次の URL を使用して Apigee API を呼び出します。
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00
特定の期間を対象に、組織と環境全体の生の指標を返すディメンションを除外します。
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00
返される指標の指定
selectクエリ パラメータを使用して、取得する指標とオプションの集計関数を次の形式で指定します。?select=metric
または
?select=aggFunction(metric)
ここで
- metric は、返されるデータを指定します。たとえば、API リクエストの数、キャッシュ ヒット数、ポリシーエラー数を指定します。
selectクエリ パラメータで使用する指標名を指定するテーブルについては、指標をご覧ください。 aggFunction は、指標に対して実行するオプションの集計関数を指定します。たとえば、処理レイテンシ指標では次の集計関数を使用できます。
avg: 平均処理レイテンシを返します。min: 最小処理レイテンシを返します。max: 最大処理レイテンシを返します。sum: すべての処理レイテンシの合計を返します。-
p50: 処理レイテンシの 50 パーセンタイルを返します。 -
p95: 処理レイテンシの 95 パーセンタイルを返します。 -
p99: 処理レイテンシの 99 パーセンタイルを返します。
すべての指標ですべての集計関数がサポートされているわけではありません。指標の名前とその指標がサポートしている関数（
sum、avg、min、max）を記載した表については、指標のドキュメントをご覧ください。
たとえば、1 秒あたりの平均トランザクション数（つまり API プロキシ リクエスト数）を返すには、次のようにします。
?select=tps
上記の例に集計関数は必要ありません。次の例では、集計関数を使用してキャッシュ ヒット数の合計を返します。
?select=sum(cache_hit)
1 回の API 呼び出しで複数の指標を返すこともできます。ポリシーエラーの合計数とリクエストの平均サイズの指標を取得するには、次のように指標のカンマ区切りリストを使用して
selectクエリ パラメータを設定します。?select=sum(policy_error),avg(request_size)
期間の指定
指標 API は指定された期間のデータを返します。
timeRange（最大 6 か月）クエリ パラメータを使用して、期間を次の形式で指定します。?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
HH:MMの前にある%20に注意してください。MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MMと同様に、timeRangeパラメータにはHH:MMの前に URL エンコードの空白文字、または+文字が必要です。例:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
時刻として 24:00 を使用しないでください。24:00 は 00:00 に戻されるためです。代わりに 23:59 を使用してください。
指標 API の呼び出し例
このセクションでは、指標 API の使用例を示します。その他の例については、指標 API の例をご覧ください。
1 か月間に行われた API 呼び出しの合計数を返す
組織と環境で 1 か月間に行われたすべての API に対する呼び出しの合計数を返すには、次のような呼び出しを使用します。
curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、
$TOKENは OAuth 2.0 アクセス トークンに設定されます。この例で使用されているcurlオプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。レスポンスの例を次に示します。
{ "environments": [ { "metrics": [ { "name": "sum(message_count)", "values": [ "7.44944088E8" ] } ], "name": "prod" } ], ... }2 日間の API プロキシあたりのメッセージの合計数を返す
この例では、すべての API プロキシが 2 日間にわたって受信したリクエストの合計数の指標を返します。
selectクエリ パラメータでは、apiproxyディメンションのmessage_count指標に対する集計関数sumを定義しています。レポートは、UTC 時間の 2018 年 6 月 20 日から 2018 年 6 月 21 日までに受信したトラフィックを対象とした、すべての API のリクエスト メッセージのスループットを返します。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、
$TOKENは OAuth 2.0 アクセス トークンに設定されます。この例で使用されているcurlオプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。レスポンスの例を次に示します。
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(message_count)", "values" : [ { "timestamp" : 1498003200000, "value" : "1100.0" } ] } ], "name" : "target-reroute" } ], "name" : "test" } ]... }このレスポンスは、2018 年 6 月 20 日から 2018 年 6 月 21 日までの間、テスト環境で実行中の「target-reroute」という API プロキシが 1,100 件のメッセージを受信したことを表しています。
他のディメンションの指標を取得するには、目的のディメンションを URI パラメータとして指定します。たとえば、
developer_appディメンションを指定すると、デベロッパー アプリに関する指標を取得できます。次の API 呼び出しにより、指定された期間のすべてのアプリからの合計スループット（受信メッセージ数）が返されます。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \ -H "Authorization: Bearer $TOKEN"
レスポンスの例を次に示します。
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "886.0" } ] } ], "name": "Test-App" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "6645.0" } ] } ], "name": "johndoe_app" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "1109.0" } ] } ], "name": "marys_app" } ]... }相対的なランキングによる結果の並べ替え
指標を取得するときに、データのすべてのセットではなく、その一部の結果を取得したい場合があります。通常は、「最も処理速度が遅い 10 個の API」、「最もアクティブな 10 個のアプリ」のように「上位 10」の結果を取得する必要があります。これを行うには、リクエストの一部として
topkクエリ パラメータを使用します。たとえば、最上位のデベロッパー、スループットで測定された最上位のデベロッパー、あるいは、レイテンシに基づく最低位のパフォーマー（例: 「最も遅いパフォーマー」）のターゲット API、などに関心があるかもしれません。
topk（上位 k のエンティティ）を使用すると、特定の指標の最大値に関連付けられているエンティティについてレポートできます。これにより、特定の条件を示すエンティティのリストで指標をフィルタリングできます。たとえば、過去 1 週間にわたり、最もエラーが起こりやすかったターゲット URL を調べるには、値を
1に設定してtopkパラメータをリクエストに追加します。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、
$TOKENは OAuth 2.0 アクセス トークンに設定されます。この例で使用されているcurlオプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。レスポンスの例を次に示します。
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(is_error)", "values": [ { "timestamp": 1494201600000, "value": "12077.0" } ] } ], "name": "http://api.company.com" } ]... }このリクエストの結果は、最もバグが多いターゲット URL が
http://api.company.comであることを示す指標のセットです。topkパラメータを使用して API を並べ替えて、最もスループットが高い API を確認することもできます。次の例では、過去 1 週間のスループットに基づいて上位にランキングされる API の指標を取得します。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \ -H "Authorization: Bearer $TOKEN"
レスポンスの例を次に示します。
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1494720000000, "value": "5750.0" }, { "timestamp": 1494633600000, "value": "5752.0" }, { "timestamp": 1494547200000, "value": "5747.0" }, { "timestamp": 1494460800000, "value": "5751.0" }, { "timestamp": 1494374400000, "value": "5753.0" }, { "timestamp": 1494288000000, "value": "5751.0" }, { "timestamp": 1494201600000, "value": "5752.0" } ] } ], "name": "testCache" } ], "name": "test" } ]... }結果のフィルタリング
粒度を細かくするため、結果をフィルタリングして、返されるデータを制限するという方法があります。フィルタを使用する場合は、フィルタのプロパティとしてディメンションを使用する必要があります。
たとえば、リクエストの HTTP 動詞でフィルタリングされたバックエンド サービスからエラー数を取得する必要があるとします。目標は、バックエンド サービス別にエラーの原因となった POST リクエストと PUT リクエストの数を調べることです。それには、フィルタ
request_verbとディメンションtarget_urlを組み合わせて使用します。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、
$TOKENは OAuth 2.0 アクセス トークンに設定されます。この例で使用されているcurlオプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。レスポンスの例を次に示します。
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(is_error)", "values" : [ { "timestamp" : 1519516800000, "value" : "1.0" } ] } ], "name" : "testCache" } ], "name" : "test" } ]... }結果のページ分け
本番環境では、Apigee Analytics API に対するリクエストによっては大量のデータセットが返されることがあります。UI ベースのアプリケーションのコンテキストで大量のデータセットを表示しやすくするために、この API はページ分けをネイティブにサポートしています。
結果をページ分けするには、クエリ パラメータ
offsetとlimitをsortby並べ替えパラメータとあわせて使用し、アイテムの整合性を維持します。たとえば、次のリクエストは、前週の本番環境に含まれるすべての API の全エラーに関わる指標をすべて取得するので、大きなデータセットが返される可能性があります。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、
$TOKENは OAuth 2.0 アクセス トークンに設定されます。この例で使用されているcurlオプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。UI ベースのアプリケーションでページあたり 50 件の結果を無理なく表示できる場合、この制限を 50 に設定します。0 は最初の項目として数えられるため、次の呼び出しでは項目 0～49 が降順で返されます（
sort=DESCがデフォルトです）。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \ -H "Authorization: Bearer $TOKEN"
結果の 2 ページ目については、offset クエリ パラメータを次の例に示すように使用します。limit と offset が同一であることに注意してください。これは、0 が最初の項目として数えられるためです。limit の値が 50、offset の値が 0 に設定されているため、項目 0～49 が返されます。offset の値を 50 に設定すると、項目 50～99 が返されます。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \ -H "Authorization: Bearer $TOKEN"