Download PDF
Download page IoT REST APIでのアプリケーションのインストゥルメンテーション.
IoT REST APIでのアプリケーションのインストゥルメンテーション
IoT REST API を使用すると、インストゥルメンテーション データを EUM サーバに直接報告することができます。HTTPS リクエストと JSON をサポートしているプラットフォームまたは言語を使用できます。
このページでは、JSON リクエスト本文を作成し、リソース URI を作成して、IoT REST API への HTTPS リクエストを作成することにより、サポートされている 3 つのイベントのインストゥルメンテーション データを報告する方法について説明します。
EUM アプリケーションキーを取得し、IoT REST API を使用するには、次の手順を実行します。
要件の確認
開始する前に、次の要件を満たしていることを確認します。
- EUM アプリケーションキーの取得
- HTTPS リクエストをサポートするプラットフォーム/言語
- JSON のサポート
IoT REST URL の作成
IoT モニタリング REST リソース URL を作成するには、IoT REST API ベースの URL とポート、およびアプリケーションキーを知っている必要があります。
IoT REST API ベースの URL
IoT REST API ベース URL は、コントローラの場所によって異なります。
各地域の EUM コレクタ URL については、「Cisco AppDynamics SaaS Domains and IP Ranges」を参照してください。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 をファイル(例: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 アプリケーションがコントローラにデータをレポートしたことの確認」を参照してインストゥルメンテーションを確認します。
ビジネストランザクションをネットワークリクエストと関連付ける(オプション)
ビジネストランザクション(BT)をネットワークリクエストと関連付けるには、ビジネスアプリケーションをインストゥルメント化し、コントローラ UI でビジネストランザクションを有効にしておく必要があります。詳細については、「IoT モニタリング用のビジネストランザクションの相関」を参照してください。
次の手順では、BT 応答ヘッダーを取得し、それらを使用して、その BT を IoT ネットワーク リクエスト イベントと関連付ける方法について説明します。
AppDynamics HTTP リクエストヘッダー
ADRUM
とADRUM_1
を含むネットワークリクエストをビジネスアプリケーションのいずれかに実行します。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>
BASHビジネスアプリケーションは、関連するビジネストランザクションの情報を含む応答ヘッダーを返します。これらの BT 応答ヘッダーを出力する場合は、次のように表示されます。
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)
BASH返された BT 応答ヘッダー(
ADRUM_*).
を含むヘッダーのみ)を使用してビーコンファイルbtCorrelation.json
を作成します。次に示すように、ビジネスアプリケーションへのネットワーク イベント リクエストから返されたADRUM_*
応答ヘッダーをビーコンのオブジェクトresponseHeaders
に割り当てます。[ { '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 } ] } ]
JSON次のような cURL コマンドを使用して、BT ヘッダーを含むビーコンを EUM サーバに送信します。
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
BASHコールが成功した場合、応答ヘッダーは次のようになります。
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
BASHコントローラ UI では、関連するビジネストランザクションを [Device Details] ダイアログで確認できます。
IoT REST API インストゥルメンテーションのカスタマイズ(オプション)
IoT REST API を使用して、IoT インストゥルメンテーションをさらにカスタマイズすることができます。最新の IoT REST API ドキュメント、または以下に記載されている以前のバージョンを参照してください。
- https://sdkdocs.appdynamics.com/javadocs/iot-rest-api/4.5/4.5.0/
- https://sdkdocs.appdynamics.com/javadocs/iot-rest-api/4.5/4.5.1/
- https://sdkdocs.appdynamics.com/javadocs/iot-rest-api/4.5/4.5.2/
- https://sdkdocs.appdynamics.com/javadocs/iot-rest-api/4.5/4.5.4/
サンプル Python アプリケーションの実行
サンプル Python アプリケーションは、IoT REST API を使用して、カスタム、ネットワークリクエスト、およびエラーイベントのサンプルデータを送信します。ネットワーク リクエスト イベントには、関連するビジネストランザクションが含まれます。データは、スマート カー アプリケーションをモックし、使用状況情報、ネットワークパフォーマンス、およびエラーをキャプチャします。
サンプルアプリケーションを実行するには、GitHub リポジトリ 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)
を使用すると、ビーコンの JSON リクエスト本文が 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 プロパティの値を置き換える場合、タイムスタンプが秒ではなくミリ秒単位であることを確認します。