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 でのインストゥルメンテーションの確認No Content found for /db/organizations/splunk/repositories/appdsaas-26_1_0/content/documents/AppDynamics/c_verify_the_instrumentation_in_the_controller_ui.dita

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

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

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

要件の確認

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

Form the IoT REST URLs

To form the IoT Monitoring REST resource URL, you will need to know the IoT REST API base URL and port as well as your App Key.

IoT REST API Base URL

The IoT REST API base URL depends on your Controller location.

注: See Splunk AppDynamics SaaS Domains and IP Ranges for EUM Collector URLs in each geographic region. If the EUM Collector URL is not specified, the default SaaS Collector URL is used.

For example, the IoT base URL for the Americas region would be:

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

After creating your IoT Application, use your App Key to test your IoT endpoint and look for a HTTP 200 response. For example, for the Americas region, run the following command:

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

IoT Endpoints

With your App Key, you can form the IoT resource endpoints. See the Summary of the IoT endpoints for the list of supported resource endpoints and their descriptions.

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.

注: 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.