Getting started with the REST API

トップに戻る

REST APIは、TechPulseによるHP DaaS (サービスとしてのデバイス) プロアクティブ管理 (以下、「プロアクティブ管理」) と、プログラムで行うすべてのやり取りの中枢をなします。プロアクティブ管理では、HP TechPulse Analytics APIとHP Incident Integration APIの2種類のREST APIを提供しています。

  • HP TechPulse Analytics APIでは、プランニングやコスト最適化に関する有益なアナリティクスと、プロジェクト管理に登録されたデバイスのサービス管理機能を提供します。
  • HP Incident Integration APIでは、プロアクティブ管理インシデントの管理を行います。

 

 

APIリクエストの認証

 

HPでは、プライバシーが基本的人権であること、および世界中のお客様およびパートナー様にとってのプライバシー、セキュリティ、データ保護の必要性を認識しています。弊社のお客様またはパートナー様は、HPのすべての事業にわたって、皆様のデータが保護されることを信頼していただけます。お客様のアプリケーションからプロアクティブ管理APIにアクセスするには、認証が必要になります。プロアクティブ管理では、シンプルかつ実装しやすい、業界標準のOAuth 2.0プロトコルを活用してアクセスを付与します。

アプリケーションの認証方法や、プロアクティブ管理REST APIと正しくやり取りする方法の詳細については、弊社の「OAuth 2.0を使用した認証」セクションをお読みください。

 

 

データ形式

APIからデータをリクエストする

すべてのREST APIでは、リクエストされた情報をJSONデータ形式で返します。

 
POST https://daas.api.hp.com/analytics/v1/reports/hwinv/details/type/grid
 
レスポンスのサンプル

{
"totalResults": 10,
"startIndex": 0,
"itemsPerPage": 0,
"resources": [
{
"companyId": "12345",
"deviceType": "Notebook",
"dateListMonth": "Apr 2018",
"deviceCount": 10,
"dataAsOfDate": "04/03/2018",
"counterId": 69362,
"companyName": "company-name",
...
}
]
}
 

 

 

リクエストのスロットリングを理解する

 

悪用を防止し、安定性を確保するため、すべてのREST APIリクエストはスロットリングされます。1日にアプリケーションから実行できる呼び出しの正確な数は、実行するリクエストの種類に応じて異なります。この情報は、個々のAPI呼び出しのドキュメントに記載されています。プロアクティブ管理APIでは、アプリケーションレベルのスロットリングが設定されており、1日にアプリケーションで実行できる呼び出しの総数が制限されています。リクエストのスロットリングでは、APIサーバーの「1日」とは、深夜12時 (UTC) から翌日の深夜までの24時間として定義されています。

 

 

ページングされたレスポンスを使用して、大量のデータセットを処理する

 

大量の結果をリストとして返す呼び出しを行う際には、多くの場合、結果セットのページングを行うことが推奨されます。データのより小さなサブセットをリクエストすれば、大量になる可能性のあるデータセット全体をリクエストするよりも、レスポンスがはるかに速くなります。

結果セットのページングをサポートする呼び出しでは、ページのサイズや開始点を制御する次のパラメーターが渡されます。

ページングパラメーター

名前
説明
startIndex
最初の検索結果に対する1ベースのインデックスを示す整数。
count
ページごとに、希望する検索結果の最大数を指定する整数。

 

結果をページ分けするには、0の開始値とNのカウント値で開始します。次のページを取得するには、開始値をNにし、カウント値はそのままにします。以降のページは2N、3N、4N...で開始されます。

 

start値とcount値の和が、結果セットの「totalResults」の値と一致した場合に、すべての結果が表示されたことになります。

例:

 

POST https://daas.api.hp.com/analytics/v1/reports/hwinv/details/type/grid?startIndex=20&count=10
 
レスポンスのサンプル

{
"totalResults": 345,
"startIndex": 20,
"itemsPerPage": 10,
"resources": [
]
}
 

 

 

データ制御を変更する

 

HP TechPulse Analytics

特定の日時の後にデータをリクエストする

 

例 - 2019-01-08より後に登録されたデバイスのリスト
HTTPリクエスト
POST /analytics/v1/reports//hwinv/details/type/grid?count=100&attributes=resources.deviceId,resources.counterId, totalResults HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: 
{
"filter": "datelistMonth gt \"2019-01-08T11:59:05Z\""
}


HTTPレスポンス
{
"totalResults": 366,
"resources": [
{
"counterId": 14436,
"deviceId": "12345"
},
... // 366 Records
]
}

 

特定の日時の間にデータをリクエストする

 

例 - 2019-01-08から2019-01-09の間に登録されたデバイスのリスト
HTTPリクエスト
POST /analytics/v1/reports//hwinv/details/type/grid?count=100&attributes=resources.deviceId,resources.counterId, totalResults HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: 
{
"filter": "datelistMonth gt \"2019-01-08T11:59:05Z\" and datelistMonth gt \"2019-01-09T11:59:05Z\" "
}


HTTPレスポンス
{
"totalResults": 126,
"resources": [
{
"counterId": 68944,
"deviceId": "12345"
},
... // 126 Records
]
}
 
以下は、データ制御を変更する使用例です
 
レポート名
使用例
フィルター例
ハードウェアインベントリ
特定の日付の後に登録されたデバイス
Body: { "filter": "datelistMonth gt \"2019-01-08T11:59:05Z\"" }

 

HP TechPulse Incident Integration

特定の日時の後にデータをリクエストする

 

例 - 2019-03-05 00:00:00より後に作成されたインシデントのリスト
HTTPリクエスト
POST/analytics/v1/incidents/1.2/tenants/{tenantId}/incidents?filter=createdAt ge "2019-03-05 00:00:00"&startIndex=0&count=10 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: 
{
    Request Payload: {tenantIds: []}
}


HTTPレスポンス
{"totalResults":38,"startIndex":0,"itemsPerPage":10,
"resources":[
    {
        "id":123456,
        "guid":"XYZA-123456",
        "displayId":"456789",
        "createdAt":1551857130279,
        "updatedAt":1551857130292,
        "occuredAt":1551744000000,
        "description":"Low disk space has been detected for disk (disk-sn, disk-model) on device device-name with user user-name, Logged On User= user-name.Amount of disk consumed is 91-100%.Low disk space may impact system stability, update installation and performance.Device operating system: Windows 10.",
        "title":"Hard drive low disk space",
        "deviceId":"XYZ-12345678",
        "type":{"name":"HW_HEALTH","value":"Hardware Health"},
        "subtype":{"name":"HDD_STORAGE_FULL","value":"HDD Storage Capacity Full"},
        "os":"Windows10",
        "tenantId":"abcdef12-3456-789g-hi0j-k11l121314lm",
        "userId":"abcdef12-3456-789g-hi0j-k11l121314lm",
        "sourceId":"123456",
        "sourceLocation":"predalerts",
        "priority":{"name":"CRITICAL","value":"Critical"},
        "status":{"name":"NEW","value":"New"},
        "lastAssigeeUpdatedAt":0,
        "lastStatusUpdatedAt":1551857130279,
        "metadata":"{\"metaDataName\":\"SerialNumber\",\"metaDataProperty\":\"enabled\",\"metaDataValue\":\"device-sn\",\"metaDataUnit\":null}",
        "measureId":"123",
        "companyDetails":
            {
                "id":456,
                "tenantId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "companyName":"company-name",
                "isDeleted":false
            },
        "userDetails":
            {
                "id":789,
                "userId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "userName":"user-name",
                "emailId":"user-name@hp.com",
                "isDeleted":false
            },
        "deviceDetails":
            {
                "id":284,
                "deviceId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "deviceName":"device-name",
                "serialNumber":"device-sn",
                "deviceModel":"device-model",
                "deviceManufacturer":"HP",
                "isDeleted":false
            },
        "isDeleted":false
    },
.....
]}

 

特定の日時の間にデータをリクエストする

 

例 - 2019-01-08から2019-03-15の間に更新されたインシデントのリスト
HTTPリクエスト
POST /analytics/v1/incidents/1.2/tenants/{tenantId}/incidents?filter=updatedAt ge "2019-01-08 00:00:00"&updatedAt le "2019-03-15 23:59:59"&startIndex=0&count=10 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: 
{
  {tenantIds: []}
}


HTTPレスポンス
{"totalResults":38,"startIndex":0,"itemsPerPage":10,
"resources":[
    {
        "id":123456,
        "guid":"XYZA-123456",
        "displayId":"456789",
        "createdAt":1551857130279,
        "updatedAt":1551857130292,
        "occuredAt":1551744000000,
        "description":"Low disk space has been detected for disk (disk-sn, disk-model) on device device-name with user user-name, Logged On User= user-name.Amount of disk consumed is 91-100%.Low disk space may impact system stability, update installation and performance.Device operating system: Windows 10.",
        "title":"Hard drive low disk space",
        "deviceId":"XYZ-12345678",
        "type":{"name":"HW_HEALTH","value":"Hardware Health"},
        "subtype":{"name":"HDD_STORAGE_FULL","value":"HDD Storage Capacity Full"},
        "os":"Windows10",
        "tenantId":"abcdef12-3456-789g-hi0j-k11l121314lm",
        "userId":"abcdef12-3456-789g-hi0j-k11l121314lm",
        "sourceId":"123456",
        "sourceLocation":"predalerts",
        "priority":{"name":"CRITICAL","value":"Critical"},
        "status":{"name":"NEW","value":"New"},
        "lastAssigeeUpdatedAt":0,
        "lastStatusUpdatedAt":1551857130279,
        "metadata":"{\"metaDataName\":\"SerialNumber\",\"metaDataProperty\":\"enabled\",\"metaDataValue\":\"device-sn\",\"metaDataUnit\":null}",
        "measureId":"123",
        "companyDetails":
            {
                "id":456,
                "tenantId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "companyName":"company-name",
                "isDeleted":false
            },
        "userDetails":
            {
                "id":789,
                "userId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "userName":"user-name",
                "emailId":"user-name@hp.com",
                "isDeleted":false
            },
        "deviceDetails":
            {
                "id":284,
                "deviceId":"abcdef12-3456-789g-hi0j-k11l121314lm",
                "deviceName":"device-name",
                "serialNumber":"device-sn",
                "deviceModel":"device-model",
                "deviceManufacturer":"HP",
                "isDeleted":false
            },
        "isDeleted":false
    },
.....
]}