分析イベント API

分析では、イベントによって分析データの単位がカプセル化されます。たとえば、APM では、各イベントが、エントリポイントサービスまたはダウンストリームサービスのいずれであるかに関係なく、メソッドまたはサービス呼び出しに対応します。

分析 API を使用して、データストア内の独自のカスタムイベントの構造を定義します。また、カスタムソースで発生するイベントレコードをキャプチャし、それらをイベントサービス（分析用のデータストア）に送信します。データがイベントストアに格納されると、ユーザはコントローラ UI または分析イベント API を使用してデータをクエリできます。

分析イベント API は、共有キーを使用して、クライアントをイベントサービスに認証します。コントローラまたは分析管理者として、コントローラ UI から API キーを生成できます。「API キーの管理」を参照してください。

イベント サービス データ ストアへの対処

コントローラに表示されるほとんどの Splunk AppDynamics REST API とは異なり、分析イベント API へは Splunk AppDynamics プラットフォームでイベント サービス インスタンスに対処することでアクセスします。

次のいずれかの URL でイベントサービスに対処します。

[SaaS Domains and IP Ranges] ページから分析ドメインの URL を取得できます。

オンプレミス イベント サービスの場合は、イベント サービス インスタンス ホスト（または、イベントサービスクラスタのロードバランサで提示される仮想 IP の場合も多くあります）に対処します。イベントサービスには、プライマリ デフォルト リスニング ポート 9080 を使用します。

分析イベント API へのコールでは、対処するコントローラのアカウントに <global_account_name> と、このクライアントの管理者が生成した <eum_account_name> を指定する必要があります。<api_key> API は、ヘッダーにプロパティと値のペアをコロンで区切った値を想定します。たとえば、cURL 引数には次のように `-H` または `--header ` オプションを使用して curl とともに値が渡されます。

-H"X-Events-API-AccountName:<global_account_name> OR <eum_account_name>" -H"X-Events-API-Key:<api_key>"

コントローラ UI の [ライセンス（License）] ページ から、使用するグローバルアカウント名を取得できます。API キーについては、「API キーの管理」を参照してください。

また、コンテンツタイプも次のように cURL 引数として指定できます。

-H"Content-type: application/vnd.appd.events+json;v=2"

Splunk AppDynamics では、API へのアクセスに SSL/HTTPS を使用することを強くお勧めします。SSL/HTTPS 以外を使用する場合は、API キーがプレーンテキスト形式で送信されます。

データ形式

分析イベント API は、JSON 形式の名前と値のペアデータとしてイベントを取得します。

カスタムイベントスキーマに準拠したデータを送信する前に、カスタムスキーマのデータ構造を定義する必要があります。イベントサービスは、着信イベントデータを適切なスキーマと照合します。

サポートされるデータ型

• ブーリアン
• 日付：サポートされている時刻形式は次のとおりです。
  • ISO 8601 形式：yyyy-MM-dd'T'HH:mm:ss.SSSZZ。
  • UNIX エポックの日付形式：13 桁の数字で、UNIX エポック時刻（1970 年 1 月 1 日）以降の秒/ミリ秒時間を表します。たとえば、(GMT): Mon, 17 Apr 2017 23:46:22 GMT は 1492472782000 となります。
• 浮動小数点数（Float）
• 整数
• 文字列

命名制限

カスタムイベント名とフィールド名は、次の条件に従う必要があります。

• a ～ z、A ～ Z、_（下線）、0 ～ 9 のみを使用します。
• 名前を数値で始めることはできません。

タイムスタンプフィールド

カスタムスキーマには、次の 2 つの暗黙的なタイムスタンプフィールドが自動的に追加されます。

• eventTimestamp
• pickupTimestamp

eventTimestamp フィールドは、イベントが発生した時刻を表します。API クライアントは、イベントを作成するときにタイムスタンプフィールドの値を指定できます。指定できない場合、Analytics Events API は別の暗黙のフィールド pickupTimestamp に使用する値と同じ eventTimestamp の値を使用します。pickupTimestamp フィールドは必ずイベントサービスで入力され、イベントサービスによってイベントが受信された時間が表示されます。

ビジネスジャーニーでマイルストーンを設定する場合は、イベントを登録するために、eventTimestamp フィールドに日付を指定する必要があります。カスタムイベントを使用してビジネスジャーニーを定義するには、カスタムイベントで eventTimestamp フィールドを送信する必要があります。送信しない場合、ビジネスジャーニーは機能しません。

Splunk AppDynamics は

ISO 8601 または UNIX エポック時刻（64 ビットミリ秒）形式を使用して、すべてのタイムスタンプフィールドを表すことができます。

API コールフローの例

次の手順に従って、分析イベント API を使用するためのオンプレミス API コールワークフローを実行します。この手順では、スキーマの作成、そのスキーマへのイベントのパブリッシュ、およびイベントのクエリに関する cURL の例を示します。

1. フィールド名とデータ型を関連付けて、スキーマを定義します。たとえば、次のように購入イベントタイプを定義します。

   JSONCopy

   curl -X POST "<events_service_endpoint>:9080/events/schema/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '{"schema" : { "id": "string", "productBrand": "string", "userRating": "integer", "price": "float", "productName": "string", "description": "string" } }'

   curl -X POST "<events_service_endpoint>:9080/events/schema/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '{"schema" : { "id": "string", "productBrand": "string", "userRating": "integer", "price": "float", "productName": "string", "description": "string" } }'

2. 作成したスキーマに基づいてイベントをパブリッシュします。

   JSONCopy

   curl -X POST "<events_service_endpoint>:9080/events/publish/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '[{"id": "5653b879ab33a","productBrand": "ACME","userRating": 3,"price": 2006.41,"productName": "Watch","description": "new watch"},{"id": "5653b879700","productBrand": "Widget","userRating": 1,"price": 3800.13,"productName": "Watch","description": "2015 watch"}]'

   curl -X POST "<events_service_endpoint>:9080/events/publish/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '[{"id": "5653b879ab33a","productBrand": "ACME","userRating": 3,"price": 2006.41,"productName": "Watch","description": "new watch"},{"id": "5653b879700","productBrand": "Widget","userRating": 1,"price": 3800.13,"productName": "Watch","description": "2015 watch"}]'

3. イベントデータをクエリします。

   CODECopy

   curl -X POST "http://<events_service_endpoint>:9080/events/query" -H"X-Events-API-AccountName:customer1_7xxx-467a-bccc-xxx" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+text;v=2" -d 'SELECT * FROM myProducts'

   curl -X POST "http://<events_service_endpoint>:9080/events/query" -H"X-Events-API-AccountName:customer1_7xxx-467a-bccc-xxx" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+text;v=2" -d 'SELECT * FROM myProducts'

ADQL キーワードが含まれたフィールドを追加する場合は、キーワードを一重引用符で囲みます。これらのキーワードには、between、in、select などがあります。

クエリ要求が 1 つの場合は、次のコンテンツタイプを使用します。

-H"Content-type: application/vnd.appd.events+text;v=2"

クエリ要求が複数の場合は、クエリが JSON 本文テキストとして渡されます。この場合は、次のコンテンツタイプヘッダーを使用します。

-H"Content-type: application/vnd.appd.events+json;v=2"

コントローラによるカスタムイベントの取り込みには、次の制限があります。

• フィールド：イベントタイプごとに最大 255
• 文字列属性：最大長 4 KB
• バッチ総数：コールあたり 10,000 イベント
• バッチ合計サイズ：コールあたり最大 5 MB
• アカウントの最大カスタムイベントスキーマ数：20

イベントサービスでは、デフォルトで最大 1,500 個のカスタムフィールドを作成できます。カスタムフィールドの容量が 80％（1,200 フィールド）に達すると、次のインデックスロールオーバー時に最大フィールド制限が 500 フィールド増加します。

たとえば、1,400 カスタムフィールドに到達すると、最大フィールド制限が 1,500 フィールドから 2,000 フィールドに増加します。その後 1,800 カスタムフィールドに到達すると、最大制限数が 2,500 フィールドに増加します。

作成できるカスタムフィールドの上限は 3,000 個です。最大フィールド数に到達したり、最大フィールド数を超えたりすると、遅延や停止が発生する可能性があります。

Publish Events API コールは、イベントの配列を取得し、イベントサービスストレージに格納します。データは既存のスキーマに準拠している必要があります。1 つの要求を複数のイベントタイプにパブリッシュすることはできません。

イベントデータがイベントスキーマと一致しない場合、イベントサービスは両者が一致するためのベストエフォート型の試みを行い、それでも失敗した場合は「400 Bad Request」を返します。

形式

クエリパラメータ

N/A

パスパラメータ

ヘッダー

SaaS による Publish の例

リクエスト

JSONCopy

POST https://analytics.api.example.com/events/publish/{schemaName} X-Events-API-AccountName:<global_account_name> OR <eum_account_name> X-Events-API-Key:<api_key> Content-Type: application/vnd.appd.events+json;v=2 Accept: application/vnd.appd.events+json;v=2 [ { "id": "5653b879ab33a", "productBrand": "ACME", "userRating": 3, "price": 2006.41, "productName": "Watch", "description": "new watch" }, { "id": "5653b879700", "productBrand": "Widget", "userRating": 1, "price": 3800.13, "productName": "Watch", "description": "2015 watch" } ]

POST https://analytics.api.example.com/events/publish/{schemaName}
X-Events-API-AccountName:<global_account_name> OR <eum_account_name>
X-Events-API-Key:<api_key>
Content-Type: application/vnd.appd.events+json;v=2 Accept: application/vnd.appd.events+json;v=2
[
{
"id": "5653b879ab33a",
"productBrand": "ACME",
"userRating": 3,
"price": 2006.41,
"productName": "Watch",
"description": "new watch"
},
{
"id": "5653b879700",
"productBrand": "Widget",
"userRating": 1,
"price": 3800.13,
"productName": "Watch",
"description": "2015 watch"
}
]

レスポンス

CODECopy

HTTP/1.1 202 ACCEPTED

HTTP/1.1 202 ACCEPTED

エラー コード

独自のイベントスキーマを作成するには、この API を使用します。このスキーマで、フィールドとタイプごとにイベントタイプの全体的な構造を定義します。

この API は、アップロードするイベントが、最初のクラスイベントタイプ（ログやトランザクションなど）の既存のスキーマと一致しない場合にのみ使用する必要があります。既存のスキーマに準拠したイベントは、そのスキーマに自動的に一致します。このトピックより前に記載されている、サポートされるデータ型および命名制限を確認してください。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Create の例

既存のイベントスキーマを取得するには、この API を使用します。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Retrieve の例

フィールドごとに既存のイベントスキーマを更新するには、この API を使用します。要求本文で、イベントスキーマに適用される更新内容を定義します。

次の例に示すように、各フィールドの更新アクションを要求本文の名前付きセクションとして指定します。アクションは次のフィールドで表されます。

• 追加フィールド
• 名前変更フィールド

追加フィールドを定義する場合は、イベントスキーマを作成する場合と同じように、新しいフィールドのデータ形式を指定する必要があります。

このコールへの応答は、変更された完全なイベントスキーマである必要があります。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Update の例

既存のイベントスキーマを削除するには、この API を使用します。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Delete 要求の例

DELETE http://analytics.api.example.com/events/schema/{schemaName} HTTP/1.1
X-Events-API-AccountName:<global_account_name> OR <eum_account_name>
X-Events-API-Key:<api_key>
Accept: application/vnd.appd.events+json;v=2

When querying analytics events data, the following applies:

• Every Events Service API has a limit of 200 searches per minute by each account on each event type.

• The Multi-Query Events API is limited to twenty queries per HTTP request.

• The Analytics Query API can return a maximum of 10,000 results. If you would like to retrieve and paginate over the data, you can use the scroll mode. Scroll mode is limited to 1,000 results per batch.

  警告: Scroll mode cannot be used in Query Events (Multiple Queries).

• ADQL sets the rate limits on the following header fields to control large request volumes that may impact system stability:

  • X-Events-API-AccountName: 450 requests per minute.
  • X-Events-API-Key: 145 requests per minute.
• Limits work differently for aggregation and non-aggregation queries. Because we use the limits specified in the ADQL query as the bucket count limit, it is not possible to also use it as the overall result count limit. Therefore, the URL parametric limit is used for the overall limit. In the case of non-aggregation queries, there is no bucket limit, so the limit specified in the ADQL query is taken as the row count limit and the URL parametric limit becomes the second place to look for it if the ADQL query does not specify a limit.
  • Aggregation queries: the total returned row count is limited by the limit in the URL query parameter, and is not directly related to the limits specified in the ADQL query statement itself. The limits in the ADQL query apply only to bucket counts in aggregations.
  • Non-aggregation queries: If LIMIT is not specified in the SELECT statement, the value specified in the URL query parameter is used. If the limit query parameter is also absent, the default is 100.

Query Events (Single Query)

This API can be used either as a simple text-formatted query or as a JSON-formatted query. The JSON-formatted query can accommodate multiple queries per call and is described in Query Events (Multiple Queries).

An event type might search against multiple event types. Therefore, the event type is not provided in the URL path or as a query parameter, but as part of the ADQL query provided in the request body itself. Your ADQL queries must adhere to the syntax described in the ADQL Reference.

This section describes the single query form for querying events.

Format

Query Params

Headers

Example SaaS Query

Query Events (Multiple Queries)

Use this API to execute multiple queries against a particular account and event type in parallel. A query event that specifies multiple queries does so by including multiple ADQL queries in the body of the request. Your ADQL queries must adhere to the syntax described in the ADQL Reference.

Using queries in this form takes advantage of certain backend optimizations in query performance. Query filter criteria, such as time range and limit, can be overridden by each inner query.

Format

Path Params

None

Query Params

Headers

Payload

Example SaaS Multiple Query