Mule API Analytics イベント API の確認

API Manager は、管理されている Mule API ごとに分析データを収集します。Analytics イベント API を使用して、レポートとチャートでこのデータを生成できます。特定の環境または複数の API のレポートを作成したり、同じ API の別のレポートを作成したりできます。

要件と制限事項

Analytics イベント API では 1 か月の保持ポリシーが提供され、データは最大 10 分の遅延で利用できます。10 要求/分の使用制限も適用され、1 要求につき最大 20,000 イベントを使用できます。1 分あたり 10 要求を超える要求レートは抑制されます。

この API はアドホックレポートの作成を目的として設計されています。データエクスポートツールとして使用することは意図されていません。

API を使用してレポートを作成する前に、次の要件と制限事項に注意してください。

  • コールが複数の期間に重ならないようにします。

  • 各 API で同じ要求を繰り返さないでください。

  • Analytics イベント API には 1 分あたり 10 要求の制限が適用されます。ベストプラクティスは 1 分あたり 1 要求です。

  • Analytics イベント API はデータ同期には使用しないでください。

    外部システムとのイベントのデータの同期が必要な場合は、​「Mule API Analytics イベント転送」​を参照してください。

レポートの作成

レート制限や IP ブラックリストによるポリシー違反などの API イベントを見つけるためのレポートを作成できます。分析サービスや Anypoint Platform が一時的に使用できない場合、Anypoint Platform はテレメトリーデータの損失を防止するために複数のデータポイントを送信することがあります。これにより、生成するレポートに重複するエントリが含まれる場合があります。

レポートを作成する手順は、次のとおりです。

  1. [API Manager]​ > ​[Mule Analytics]​ > ​[Manage Reports (レポートを管理)]​ に移動し、​[New (新規)]​ をクリックします。

  2. [Create Report (レポートを作成)]​ でデータソース、範囲、形式を選択します。

  3. [Fields (項目)]​ で ​[Violated Policy Name (違反ポリシー名)]​ を選択します。

  4. レポートを保存します。

    レポートを表示する URL が表示されます。

  5. URL をクリックして生成されたレポートを表示します。

ブラウザーでのレポートの実行

Analytics イベント API には、要求されたデータを使用できる開始時刻が表示されます。使用できるデータがない場合、警告メッセージが表示されます。

ブラウザーでレポートを実行するには、​[Manage Reports (レポートを管理)]​ ページに移動し、目的のレポートの ​[Run (実行)]​ をクリックします。

anev_running_report2

レポートを実行すると、要求した分析データを含む CSV または JSON ファイルが生成されます。

curl を使用したレポート情報の表示

この手順では、curl コマンドを実行して ​$TOKEN​ の値を取得します。コマンドはこの応答の ​access_token​ JSON プロパティを取得します。

認証ヘッダーの形式は、​Authorization: Bearer {$TOKEN.access_token}​ です。

jq​ コマンドライン JSON プロセッサーの使用は、アクセストークン値を取得するための可能なソリューションの 1 つです。このアプリケーション、またはこの手順で同じ機能を果たすアプリケーションをダウンロードしてインストールします。

レポート情報をプログラムで表示する

  1. 新しいターミナルウィンドウを開き、次のコマンドを実行します。

    TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=<YOUR-USERNAME>&password=<YOUR-PASSWORD>" | jq -r .access_token)

    このコマンドは、Anypoint Platform の認証サーバーに要求を送信し、要求が成功すると、アクセストークンを返して ​$TOKEN​ 変数に保存します。この変数の値は次のように表示されます。

    {
     "access_token": "54545454-5454-5454-5454-545454545454",
     "token_type": "Bearer",
     "redirectUrl": "/accounts/#/cs/profile/home"
     }
  2. レポートの Analytics レポート API エンドポイントの要求内の ​Authorization​ ヘッダーにアクセストークンを付加します。

    1. Mule API Analytics ダッシュボードの ​[Manage Reports (レポートを管理)]​ ページからエンドポイントをコピーします。

    2. 環境のない組織の分析を取得する次の例に示すように、前のステップからの ​$TOKEN​ 変数を次回の要求に含めます。

      curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/<ORGANIZATION_ID>/events?format=csv&startDate=2016-01-01&endDate=2016-12-31&fields=Application%20Name.Client%20IP.Resource%20Path" > output.csv
  3. 要求が成功すると、​curl​ 要求を開始したディレクトリに ​output.csv​ ファイルが生成されます。

    次の例は、環境がある組織の Analytics イベント API を照会します。

curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com:443/analytics/1.0/<ORGANIZATION_ID>/environments/<ENVIRONMENT_ID>/events?format=csv&apiIds=<API_ID>&duration=30d" > output.csv

この例では、API ID <​API_ID​> の API から過去 30 日間の分析データが取得されます。結果は CSV 形式で生成されます。

次の例は、2 つの ​curl​ コマンドを組み合わせてコマンドプロンプトウィンドウに値を表示します。

TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=myusername&password=mypassword" | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/42424242-4242-4242-4242-424242424242/events?format=csv&startDate=2016-01-01&endDate=2016-11-10&fields=Application%20Name.Client%20IP.Resource%20Path"
echo;echo

このコマンドで次の出力が生成されます。

"Application Name","Client IP","Resource Path",Timestamp,"API ID","API Version ID","API Name","API Version Name"
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T04:27:02.072Z,61460,63811,"test api contracts",1
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T05:03:38.774Z,61460,63811,"test api contracts",1
  ...

特定の環境のレポートの作成

複数の環境を有効にしている組織では、このトピックで説明されている方法で照会した API イベントは「未分類」の環境のみに属します。

特定の環境で API のイベントを要求する方法は、次のとおりです。

  1. 環境セレクターで環境を選択し、実行するレポートを作成します。

    レポートは環境に基づいて保存されます。そのため、異なる環境に異なるレポートが存在します。

  2. レポートの作成から生成されたレポート URL を UI からコピーします。

    この URL には、組織 ID に加えて ​/environment/{Environment ID}​ も含まれます。組織と環境の作成時に Anypoint Platform は一意の ID を割り当てます。たとえば、QA 環境内の API ID は本番環境内のその ID とは異なります。

  3. 特定の環境のイベントにアクセスするには、レポート URL に環境 ID を付加します。

コマンドオプションリファレンス

次のオプションを curl コマンドに追加できます。

オプション 説明

apiIds

クエリに含める API ID のカンマ区切りリスト。省略するか、​all​ または ​*​ を指定すると、すべての API が含まれます。

型:​ string
必須:​ いいえ
例:​ ​appIds=42,54

apiVersionIds

クエリに含める API バージョン ID のカンマ区切りリスト。 省略するか、​all​ または ​*​ を指定すると、すべての API バージョンが含まれます。 API ID の値が指定されていない場合、無視されます。

型:​ string
必須:​ いいえ
例:​ ​apiVersionIds=42,54

duration

レポートで返されるデータの対象の期間。数量を表す整数値と、単位を表す 1 文字のサフィックスで構成されます。

サフィックスは次のいずれかです。

  • d​: 日

  • h​: 時

  • m​: 分

  • s​: 秒

1 週間を対象とするには、期間として ​7d​ を指定します。30 秒を対象とするには、​30s​ を指定します。

型:​ string
必須:​ いいえ
例:​ ​duration=45m

fields

レポートに含める項目。CSV 出力では必須、JSON 出力では省略可能です。 項目のリストはカンマまたはピリオドで区切ることができます。スペースには ​%20​ を使用します。​[report-data-fields-reference]​の任意の値を使用できます。 タイムスタンプ、API 名、API ID、API バージョン、API バージョン ID は常に含まれます。

型:​ string
必須:​ いいえ
例:​ ​fields=Hardware%20Platform.Client%20IP.Resource%20Path

format

返される値のシリアル化形式を決定します。 ​csv​ または ​json​ を入力します。

型:​ string
必須:​ はい
例:​ ​format=csv

maxResults

返すイベントの最大数。デフォルト値は ​20000​ です。

型:​ integer
必須:​ いいえ
例:​ ​maxResults=3

startDate

開始日時。​http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser() http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser()`[ISO 日時パーサー]

型:​ date
必須:​ いいえ
例:​ ​startDate=2016-01-01T08:15:30-05:00

endDate

終了日時。​http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser()​ を参照してください。

型:​ date
必須:​ いいえ
例:​ ​endDate=2016-11-10

レポートデータ項目リファレンス

レポートでは、使用可能な 1 つまたは複数のデータ項目のデータを照会できます。

データ項目名 説明

Application (アプリケーション)

受信 API 要求に関連付けられたクライアント ID。

Application Name (アプリケーション名)

API 要求を実行したアプリケーションの名前 (要求と共にクライアント ID が渡された場合のみ使用可能)。

Browser (ブラウザー)

受信 API 要求に関連付けられたブラウザー種別。

City (市区郡)

API 要求の実行元の市区郡 (クライアントの IP アドレスによる推定)。

Client IP (クライアント IP)

API 要求を実行したクライアントの IP アドレス。

Continent (大陸)

API 要求の実行元の大陸 (クライアントの IP アドレスによる推定)。

Country (国)

API 要求の実行元の国 (クライアントの IP アドレスによる推定)。

Hardware Platform (ハードウェアプラットフォーム)

要求を実行したクライアントのハードウェア種別 (モバイル、タブレット、デスクトップなど)。

メッセージ ID

メッセージ ID の値。

OS Family (OS ファミリー)

クライアントの OS 種別: Mac OS X、iOS、Windows、Linux。

OS Major Version (OS メジャーバージョン)

オペレーティングシステムのメジャーバージョン。

OS Minor Version (OS マイナーバージョン)

オペレーティングシステムのマイナーバージョン。

OS Version (OS バージョン)

オペレーティングシステムのバージョン。

Postal Code (郵便番号)

API 要求の実行元の郵便番号 (クライアントの IP アドレスによる推定)。

Request Outcome (要求結果)

要求が成功したか、結果としてポリシー違反になったかを示します。

Request Size (要求サイズ)

受信クライアント要求のサイズ (バイト単位)。

Resource Path (リソースパス)

クライアント要求のパス。

Response Size (応答サイズ)

API 応答のサイズ (バイト単位)。以下の注意事項を参照してください。

Response Time (応答時間)

API 要求の処理時間。

Status Code (状況コード)

応答の HTTP 状況コード。

Timezone (タイムゾーン)

API 要求の実行元のタイムゾーン (クライアントの IP アドレスによる推定)。

User Agent Name (ユーザーエージェント名)

受信クライアント要求の完全なユーザーエージェント文字列。

User Agent Version (ユーザーエージェントバージョン)

受信クライアント要求のユーザーエージェント文字列のバージョン。

Verb (動詞)

API クライアント要求に関連付けられた REST 動詞 (GET、POST、PATCH など)。

Violated Policy Name (違反ポリシー名)

API 要求により違反となったポリシー (ある場合) の名前。

クエリ内の ​Content-Length​ ヘッダーの状況に応じて、次のように動作します。

  • 存在する: Response Size​ はその値に設定されます。

  • 存在せず、ペイロードが文字列: Mule API Analytics は文字列の長さを計算し、その値を報告します。

  • 存在せず、ペイロードが文字列ではない: Mule API Analytics は応答サイズを -1 として報告します。

    たとえば、返された出力が DataWeave ストリームであり、​Content-Length​ ヘッダーが存在しない場合、値が文字列ではないため、Analytics イベント API は応答サイズを報告しません。ただし、アプリケーションで文字列変換が実行されている場合、応答サイズは表示されます。

クライアント IP データの制限

クライアント IP データを転送しない場合は、Mule Runtime の​wrapper.conf​ ファイルで ​anypoint.platform.analytics_include_client_ip=false​ を設定します。プロパティを設定するには、Configuring Propertiesを参照してください。

クライアント IP データを転送しないことを選択した場合、​[City (市区郡)]​、​[Continent (大陸)]​、​[Postal Code (郵便番号)]​、​[Country (国)]​、​[Timezone (タイムゾーン)]​ などのローカライズされた地理データも使用できなくなります。