IoT REST APIでのアプリケーションのインストゥルメンテーション

IoT REST API を使用すると、インストゥルメンテーション データを EUM サーバーに直接報告することができます。HTTPS リクエストと JSON をサポートしているプラットフォームまたは言語を使用できます。

このページでは、JSON リクエスト本文を作成し、リソース URI を作成して、IoT REST API への HTTPS リクエストを作成することにより、サポートされている 3 つのイベントのインストゥルメンテーション データを報告する方法について説明します。

EUM アプリケーションキーを取得し、IoT REST API を使用するには、次の手順を実行します。

  1. 要件の確認

  2. IoT REST URL の作成

  3. JSON リクエスト本文の作成

  4. ビーコンデータの送信

  5. コントローラ UI でのインストルメンテーションの確認

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

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

  8. IoT REST API インストゥルメンテーションのトラブルシューティング

要件の確認

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

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 は次のようになります。

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

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

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 にビーコンとして送信します。

注: タイムスタンプは秒単位ではなくミリ秒単位で保存してください。
[
{
"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 アプリケーションキーで置き換えます。

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

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

< HTTP/1.1 202 Accepted

Correlate Business Transactions with Network Requests (Optional)

To correlate business transactions (BTs) with network requests, you need to have instrumented a business application and enabled business transactions in the Controller UI. See Correlate Business Transactions for IoT Monitoring to learn more.

The steps below show you how to get the BT response headers and use them to correlate the BT with an IoT Network Request event.

  1. Make a network request that includes the AppDynamics HTTP request headers ADRU
    M and ADRUM_1 to one of your business applications: 
    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. The business application will return response headers that contain information for correlating business transactions. If you were to print these BT response headers, you would see something like the following: 
    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. Create a beacon file btCorrelation.json with the returned BT response headers (only those headers that include ADRUM_*). You assign the returned ADRUM_* response headers from the network event request to the business application to the object responseHeaders in the beacon as shown below. 
    [
{
'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. Send the beacon containing the BT headers to the EUM Server with a cURL command similar to the one here: 
    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. For a successful call, the response headers should be similar to the following: 
    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. In the Controller UI, you should be able to view the correlated business transaction in the Device Details dialog.

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

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

Run the Sample Python Application

The sample Python application uses the IoT REST API to send sample data for Custom, Network Request, and Error events. The Network Request events include correlated business transactions. The data mocks a smart car application, capturing usage information, network performance, and errors.

To run the sample app, follow the instructions given in the GitHub repository iot-rest-api-sample-apps.

IoT REST API インストゥルメンテーションのトラブルシューティング

 次のセクションでは、IoT REST API インストゥルメンテーションのトラブルシューティング手順について説明します。

IoT アプリケーションが有効になっていることの確認

アプリケーションキーを使用して、IoT アプリケーションが有効になっていることを確認します。

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

アプリケーションキーが有効になっている場合は、次の応答を取得します。

< 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

アプリケーションキーが存在しない場合は、次のようになります。

< HTTP/1.1 403 Forbidden

ビーコンの検証

検証ビーコンエンドポイント（/validate-beacons）REST API スキーマを使用できます。

注: ビーコンを送信する前にビーコンを検証する必要はなく、推奨もされません。開発のこのエンドポイントは、テストおよびトラブルシューティング目的でのみ使用する必要があります。

この cURL の例では、ファイル testBeacon.json に指定されている JSON が有効であることを確認しています。<appKey> は EUM アプリケーションキーに置き換えます。

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

 ビーコンデータが含まれている JSON リクエスト本文が有効な場合、IoT モニタリング REST API は HTTP ステータス 200 を返します。

HTTP/1.1 200 OK

 JSON リクエスト本文が無効な場合、IoT REST API は HTTP ステータス 422 と、エラーメッセージの説明を含む応答本文を返します。

< HTTP/1.1 422 Unprocessable Entity

タイムスタンプの確認

JSON 本文を作成し、timestamp プロパティの値を置き換える場合、タイムスタンプが秒ではなくミリ秒単位であることを確認します。