Instrument Applications with the IoT REST APIs

The IoT REST APIs enable you to report instrumentation data directly to the EUM Server. You can use any platform or language that has support for HTTPS requests and JSON.

This page describes how to create a JSON request body, form the resource URI, and make an HTTPS request to the IoT REST APIs to report instrumentation data for the three supported events.

Follow these steps to get your EUM App Key and use the IoT REST API:

  1. Review the Requirements

  2. Form the IoT REST URLs

  3. Create the JSON Request Body

  4. Transmit the Beacon Data

  5. Verify the Instrumentation in the Controller UI

  6. Correlate Business Transactions with Network Requests (Optional)

  7. Customize the IoT REST API Instrumentation (Optional)

  8. Troubleshoot the IoT REST API Instrumentation

要件の確認

開始する前に、次の要件を満たしていることを確認します。

IoT REST URL の作成

IoT モニタリング REST リソース URL を作成するには、IoT REST API ベースの URL とポート、およびアプリケーションキーを知っている必要があります。

IoT REST API ベースの URL

IoT REST API ベース URL は、コントローラの場所によって異なります。

注: 各地域の EUM コレクタ URL については、「Splunk AppDynamics SaaS ドメインと IP 範囲」を参照してください。EUM コレクタ URL が指定されていない場合は、デフォルトの SaaS コレクタ URL が使用されます。

たとえば、アメリカ地域の IoT ベース URL は次のようになります。

CODE 
https://iot-col.eum-appdynamics.com/eumcollector/iot/v1

IoT アプリケーションを作成したら、アプリケーションキーを使用して IoT エンドポイントをテストし、HTTP 200 レスポンスを探します。たとえば、アメリカ地域の場合は、次のコマンドを実行します。

CODE 
curl -I https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<APPKEY>/enabled

IoT エンドポイント

アプリケーションキーを使用して、IoT リソースエンドポイントを作成できます。サポートされているリソースエンドポイントのリストとその説明については、IoT エンドポイントの概要を参照してください。

JSON リクエスト本文の作成

デバイス情報とイベントは、JSON リクエスト本文で報告します。JSON には beacon オブジェクトの配列が含まれていて、各 beacon オブジェクトにはデバイスデータとイベントが含まれています。配列を使用すると、1 つのリクエスト内の複数のデバイスから EUM サーバにデータを送信できます。リクエストごとに最大 200 のビーコンを送信できます。

次の JSON をファイル（例：ttestBeacon.json など）に保存し、timestamp プロパティの値を UNIX エポック時間を表す整数（ミリ秒単位）に置き換えます。JSON には、スマートサーモスタットのサポートされている 3 つのイベント customEvents、networkRequestEvents、および errorEvents が含まれています。次の 2 つの手順では、JSON を検証し、IoT REST API にビーコンとして送信します。

注: タイムスタンプは秒単位ではなくミリ秒単位で保存してください。
JSON 
[
{
"deviceInfo": {
"deviceType": "Thermostat",
"deviceId": "4e75d70d-a3f9-474b-bacf-0f4a57fa944c"
},
"versionInfo": {
"hardwareVersion": "Board Rev. 13A",
"firmwareVersion": "123.5.31",
"softwareVersion": "9.1.3",
"operatingSystemVersion": "Linux 13.4"
},
"customEvents": [
{
"timestamp": <UNIX_Epoch_time_in_milliseconds>,
"eventType": "Temperature Reading",
"eventSummary": "Temperature: 25° c",
"doubleProperties": {
"celsius": 25.0
}
}
],
"networkRequestEvents": [
{
"timestamp": <UNIX_Epoch_time_in_milliseconds>,
"duration": 245,
"url": "https://api.company.com/v1/temperature",
"statusCode": 200,
"requestContentLength": 32,
"responseContentLength": 0,
"doubleProperties": {
"reportedTemperature": 25.0
}
}
],
"errorEvents": [
{
"timestamp": <UNIX_Epoch_time_in_milliseconds>,
"name": "SQLException",
"message": "open() failed because db is locked"
}
]
}
]

ビーコンデータの送信

ビーコンを送信するには、JSON リクエスト本文を /beacons エンドポイントにポストします。この cURL の例でも、ファイル testBeacon.json に保存した JSON を使用して、<appKey> を EUM アプリケーションキーで置き換えます。

CODE 
curl -v -X POST -d '@testBeacon.json' https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/beacons

ビーコンが正常に送信された場合、IoT REST API は HTTP ステータスコード 202 を返します。

CODE 
< HTTP/1.1 202 Accepted

ビジネストランザクションをネットワークリクエストと関連付ける（オプション）

ビジネストランザクション（BT）をネットワークリクエストと関連付けるには、ビジネスアプリケーションをインストゥルメント化し、コントローラ UI でビジネストランザクションを有効にしておく必要があります。IoT モニタリング用のビジネストランザクションの相関 IoT モニタリング用のビジネストランザクションの相関

次の手順では、BT レスポンスヘッダーを取得し、それらを使用して、その BT を IoT ネットワーク リクエスト イベントと関連付ける方法について説明します。

  1. AppDynamics HTTP リクエストヘッダー ADRU M と ADRUM_1 を含むネットワークリクエストを、
    ビジネスアプリケーションの 1 つに対して作成します。
    CODE 
    curl -H "ADRUM: isAjax:true" -H "ADRUM_1: isMobile:true" -H "Accept: application/json" -H "Content-Type: application/xml" -H "Content-Length: 0" -X GET http://<url_to_business_app>
  2. ビジネスアプリケーションは、関連するビジネストランザクションの情報を含むレスポンスヘッダーを返します。これらの BT 応答ヘッダーを出力する場合は、次のように表示されます。
    CODE 
    ADRUM_0: clientRequestGUID:a27ce4da-d4e6-4bf5-bbca-9b1751aa44a4
ADRUM_1: globalAccountName:customer1_78203698-278e-428f-8726-bb381219c6cb
ADRUM_2: btId:4423
ADRUM_3: btERT:267
ADRUM_4: btDuration:368
Content-Length: 469
Server: Jetty(9.4.z-SNAPSHOT)
  3. 返された BT 応答ヘッダー（ADRUM_* を含むヘッダーのみ）でビーコンファイル btCorrelation.json を作成します。以下に示すように、ビジネスアプリケーションへのネットワーク イベント リクエストから返された ADRUM_* レスポンスヘッダーを、ビーコン内の responseHeaders オブジェクトに割り当てます。
    JSON 
    [
{
'deviceInfo':{
'deviceId':'1111',
'deviceName':'AudiS3',
'deviceType':'SmartCar'
},
'versionInfo':{
'hardwareVersion':'1.0',
'firmwareVersion':'1.0',
'softwareVersion':'1.0',
'operatingSystemVersion':'1.0'
},
'networkRequestEvents':[
{
'url':'<url_to_business_app>',
'statusCode':200,
'responseHeaders':{
'ADRUM_0':[
'<value_returned_from_business_app>'
],
'ADRUM_1':[
'<value_returned_from_business_app>'
],
'ADRUM_2':[
'<value_returned_from_business_app>'
],
'ADRUM_3':[
'<value_returned_from_business_app>'
]
},
'timestamp':1525226857000,
'duration':0,
'requestContentLength':0,
'responseContentLength':457
}
]
}
]
  4. 次のような cURL コマンドを使用して、BT ヘッダーを含むビーコンを EUM サーバに送信します。
    CODE 
    curl -I -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @btCorrelation.json -H https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/beacons
  5. コールが成功した場合、応答ヘッダーは次のようになります。
    CODE 
    HTTP/1.1 202 Accepted
Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0, proxy-revalidate, s-maxage=0
Expires: 0
Pragma: no-cache
Vary: *
Transfer-Encoding: chunked
Via: 1.1 sjc12-dmz-wsa-5.cisco.com:80 (Cisco-WSA/X)
Connection: keep-alive
  6. コントローラ UI では、[Device Details] ダイアログで関連するビジネストランザクションを確認できます。

IoT REST API インストゥルメンテーションのカスタマイズ（オプション）

 IoT REST API を使用して、IoT インストゥルメンテーションをさらにカスタマイズすることができます。最新の IoT REST API ドキュメント、または以下に記載されている以前のバージョンを参照してください。

サンプル Python アプリケーションの実行

サンプル Python アプリケーションは、IoT REST API を使用して、カスタム、ネットワークリクエスト、およびエラーイベントのサンプルデータを送信します。ネットワーク リクエスト イベントには、関連するビジネストランザクションが含まれます。データは、スマート カー アプリケーションをモックし、使用状況情報、ネットワークパフォーマンス、およびエラーをキャプチャします。

サンプルアプリケーションを実行するには、GitHub リポジトリ iot-rest-api-sample-apps に記載されている手順に従います。

Troubleshoot the IoT REST API Instrumentation

The sections below provide instructions for troubleshooting your IoT REST API Instrumentation.

Verify Your IoT App Has Been Enabled

Using your App Key, verify that your IoT app has been enabled:

CODE 
curl -v -X GET https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/enabled

If your App Key has been enabled, you should get the following response:

< HTTP/1.1 200 OK
< Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0, proxy-revalidate, s-maxage=0
< Date: Sat, 19 Aug 2017 01:20:39 GMT
< Expires: 0
< Pragma: no-cache
< Vary: *
< Content-Length: 0
< Connection: keep-alive

If the App Key does not exist:

< HTTP/1.1 403 Forbidden

Validate Beacons

You can use the validate beacon endpoint ( /validate-beacons) REST API schema.

Note: You are not required or recommended to validate beacons before transmitting them. You should only use this endpoint in development for testing and troubleshooting.

In this cURL example, you are verifying that the JSON given in the file testBeacon.json is valid. Replace <appKey> with your EUM App Key.

CODE 
curl -v -X POST -d '@testBeacon.json' https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/validate-beacons

If the JSON request body containing the beacon data is valid, the IoT Monitoring REST API will return the HTTP Status 200:

CODE 
HTTP/1.1 200 OK

If the JSON request body is invalid, the IoT REST API will return the HTTP Status 422 and a response body with the description of the error message.

CODE 
< HTTP/1.1 422 Unprocessable Entity

Verify Timestamps

When you create the JSON body and replace the values for the timestamp properties, make sure the timestamps are in milliseconds, not seconds.