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 は、コントローラの場所によって異なります。SaaS ドメインと IP 範囲に関する IoT REST API の行を参照してください。たとえば、アメリカ地域の 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/applications/<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 ネットワーク リクエスト イベントと関連付ける方法について説明します。

1. AppDynamics HTTP リクエストヘッダー ADRUM と ADRUM_1  を含むネットワークリクエストをビジネスアプリケーションの 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

2. ビジネスアプリケーションは、関連するビジネストランザクションの情報を含む応答ヘッダーを返します。これらの 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

3. 返された 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
               }
            ]
         }
   ]

   JS

4. 次のような 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

5. コールが成功した場合、応答ヘッダーは次のようになります。

   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

6. コントローラ 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