IoT REST APIでのアプリケーションのインストゥルメンテーション
IoT REST API を使用すると、インストゥルメンテーション データを EUM サーバーに直接報告することができます。HTTPS リクエストと JSON をサポートしているプラットフォームまたは言語を使用できます。
このページでは、JSON リクエスト本文を作成し、リソース URI を作成して、IoT REST API への HTTPS リクエストを作成することにより、サポートされている 3 つのイベントのインストゥルメンテーション データを報告する方法について説明します。
EUM アプリケーションキーを取得し、IoT REST API を使用するには、次の手順を実行します。
要件の確認
開始する前に、次の要件を満たしていることを確認します。
- EUM アプリケーションキーの取得
- HTTPS リクエストをサポートするプラットフォーム/言語
- JSON のサポート
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.
For example, the IoT base URL for the Americas region would be:
https://iot-col.eum-appdynamics.com/eumcollector/iot/v1After 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:
curl -I https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<APPKEY>/enabledIoT 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 をファイル（例：testBeacon.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コントローラ UI でのインストゥルメンテーションの確認
IoT アプリケーションがコントローラにデータをレポートしたことの確認Troubleshoot the IoT REST API Instrumentation
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.
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.
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:
curl -v -X GET https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/enabledIf 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.
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.
curl -v -X POST -d '@testBeacon.json' https://iot-col.eum-appdynamics.com/eumcollector/iot/v1/application/<appKey>/validate-beaconsIf the JSON request body containing the beacon data is valid, the IoT Monitoring REST API will return the HTTP Status 200:
HTTP/1.1 200 OKIf 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.
< HTTP/1.1 422 Unprocessable EntityVerify Timestamps
When you create the JSON body and replace the values for the timestamp properties, make sure the timestamps are in milliseconds, not seconds.