Best Practices for Application Development

トップに戻る

アプリケーションにデータアクセス権を付与する際に、HP DaaSメンバーの信頼性と快適さを向上するためには、データが使用される方法について透明性を提供することが重要です。アプリケーションでHP DaaSメンバーに価値を提供できるように、以下の提案事項に従ってください。

 

自主管理またはパートナー管理のAPIの比較

 

TechPulseによるHP DaaS (サービスとしてのデバイス) プロアクティブ管理 (以下、「プロアクティブ管理」) のレポートでは、プランニングやコスト最適化に関する有益なアナリティクスと、プロジェクト管理に登録されたデバイスのサービス管理機能を提供します。

プロアクティブ管理アナリティクスを自分で管理することを望むお客様は、「自主管理のお客様」と呼びます。プロアクティブ管理アナリティクスの管理を、希望するパートナーに外注するお客様は、「パートナー管理のお客様」と呼びます。

自主管理のお客様は、プロアクティブ管理アカウントのデータのみを取得することができます。パートナー管理のお客様は、プロアクティブ管理で管理されるすべての顧客のデータを取得することができます。たとえば、プロアクティブ管理のパートナーAが3名の顧客 (X、Y、Z) を管理している場合、HP TechPulse Analytics APIを呼び出すと、3名の顧客すべてのアナリティクス情報が返されます。この場合、Details APIでは3名の顧客が個別に返され、Summary APIでは3名の顧客すべての集計情報が返されます。

 

POSTリクエストの例 - 自主管理のSummary API
HTTPリクエスト
POST /analytics/v1/reports/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Body: NO need to specify any tenantd id here

HTTPレスポンス
{
    "totalResults": 1,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "byPercentages": [
                {
                    "appName": "Windows Explorer",
                    "usage": 52.44
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 51.87
                }
            ],
            "byUsageHours": [
                {
                    "appName": "Windows Explorer",
                    "usage": 81.6
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 50.27
                }
            ]
        }
    ]
}

 

POSTリクエストの例 - 自主管理のDetails API
HTTPリクエスト
POST /analytics/v1/reports/softuti/summary/type/grid?count=2 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Body: NO need to specify any tenantd id here

HTTPレスポンス
{
    "totalResults": 31,
    "startIndex": 0,
    "itemsPerPage": 2,
    "resources": [
        {
            "appName": "ApplicationFrameHost",
            "appVersion": "",
            "deviceCount": "105873",
            "appUsageCount": "63919",
            "appUsagePercent": "60.37",
            "appUsageHours": "8630562.00",
            "appAvgUsageTime": "81.52",
            "rankAppUsagePercent": "1",
            "rankAppUsageHrs": "3"
        },
        {
            "appName": "Windows Explorer",
            "appVersion": "10.0.15063.0",
            "deviceCount": "105873",
            "appUsageCount": "55523",
            "appUsagePercent": "52.44",
            "appUsageHours": "8639202.00",
            "appAvgUsageTime": "81.60",
            "rankAppUsagePercent": "2",
            "rankAppUsageHrs": "2"
        }
    ]
}

 

POSTリクエストの例 - パートナー管理のDetails API
HTTPリクエスト
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: NO tenant ids

HTTPレスポンス
{
    "totalResults": 11,
    "startIndex": 0,
    "itemsPerPage": 11,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "Unknown",
            "osversion": "Unknown",
            "osreleselToggaleEnabled": true
        },
        {
            "counterId": 97989,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP Elite Slice",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "08/31/2018",
            "endDate": null,
            "lastOnlineDate": "11/28/2018 at 08:33 AM (UTC)",
            "memory": "8 GB  2400 MHz",
            "graphics": "Intel(R) HD Graphics 630",
            "processor": "Intel(R) Core(TM) i3-7310T CPU @ 3.40GHz",
            "mfgDate": "01/03/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Aug 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17134.407",
            "osversion": "10.0.17134.407",
            "osreleselToggaleEnabled": true
        },
        ... // 11 Records
    ]
}

 

POSTリクエストの例 - パートナー管理のSummary API
HTTPリクエスト
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: NO tenant ids

HTTPレスポンス
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 8,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                ...// 4 records
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "Windows 8",
            "total": 2,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                ...// sample data removed
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "OSX 10",
            "total": 1,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "OSX 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "OS X Version 10.14 (Build 18A391)",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "OSX",
            "productOs": null,
            "osreleselToggaleEnabled": true
        }
    ]
}

 

POSTリクエストの例 - パートナー管理のDetails API
HTTPリクエスト
POST /analytics/v1/reports/hwinv/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":"( devicetype eq \"Desktop\" ) "
}

HTTPレスポンス
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17763.134",
            "osversion": "10.0.17763.134",
            "osreleselToggaleEnabled": true
        },
        {
            "counterId": 97989,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP Elite Slice",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "08/31/2018",
            "endDate": null,
            "lastOnlineDate": "11/28/2018 at 08:33 AM (UTC)",
            "memory": "8 GB  2400 MHz",
            "graphics": "Intel(R) HD Graphics 630",
            "processor": "Intel(R) Core(TM) i3-7310T CPU @ 3.40GHz",
            "mfgDate": "01/03/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Aug 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17134.407",
            "osversion": "10.0.17134.407",
            "osreleselToggaleEnabled": true
        },{
            "counterId": 21649,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "APPLE",
            "deviceModel": "Macmini6 1",
            "deviceSn": "device-sn",
            "deviceOs": "OSX 10",
            "dateEnrolled": "09/09/2018",
            "endDate": null,
            "lastOnlineDate": "11/26/2018 at 01:54 PM (UTC)",
            "memory": "8 GB 1600 MHz",
            "graphics": "Intel HD Graphics 4000",
            "processor": "Intel(R) Core(TM) i5-3210M CPU @ 2.50GHz",
            "mfgDate": "Unknown",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "OSX 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "OS X Version 10.14 (Build 18A391)",
            "osversion": "OS X Version 10.14 (Build 18A391)",
            "osreleselToggaleEnabled": true
        }
    ]
}

 

POSTリクエストの例 - パートナー管理のSummary API
HTTPリクエスト
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <Access Token>
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":"( devicetype eq \"Desktop\" ) "
}

HTTPレスポンス
{
    "totalResults": 2,
    "startIndex": 0,
    "itemsPerPage": 2,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 2,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                {
                    "deviceOs": "Windows 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "10.0.17763.134",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "OSX 10",
            "total": 1,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "OSX 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "OS X Version 10.14 (Build 18A391)",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "OSX",
            "productOs": null,
            "osreleselToggaleEnabled": true
        }
    ]
}

 

 

 

企業、ユーザー、デバイスの識別子

 

弊社のAnalyticsおよびIncident APIでは、企業、デバイス、ユーザーのGUIDタイプの一意の識別子に対応していますが、APIでは数字からなる識別子で応答します。数字の識別子に対応するGUIDタイプの識別子を取得するには、Identity Map APIを呼び出すことができます。

Identity Map APIの例
HTTPリクエスト
GET /analytics/v1/reports/id/{int-id}/type/{id-type} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTPレスポンス
デバイスの場合:
{
    "intId": 12345,
    "idType": "deviceid",
    "uuid": "device-uuid-1"
}

ユーザーの場合:
{
    "intId": 1234,
    "idType": "userid",
    "uuid": "user-uuid-1"
}

企業の場合:
{
    "intId": 1458,
    "idType": "companyid",
    "uuid": "tenant-uuid-1"
}

 

これは、すべてのユーザー詳細を取得するIdentity Service APIであるか、user_idに基づきます。

Identity APIの例: ユーザー詳細を取得するには
HTTPリクエスト
GET /analytics/v1/identity/users HTTP/1.1
または
GET /analytics/v1/identity/users/{user-id} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTPレスポンス
{
    "schemas": [
        "urn:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "user-uuid-1",
    "userName": "test-email@email.com",
    "name": {
        "honorificPrefix": "",
        "familyName": "test",
        "givenName": "testuser",
        "honorificSuffix": ""
    },
    "displayName": "User Name",
    "addresses": [],
    "phoneNumbers": []
    .....
}

 

これは、すべてのテナント詳細を取得するIdentity Service APIであるか、tenant_idに基づきます。

Identity APIの例: テナント詳細を取得するには
HTTPリクエスト
GET /analytics/v1/identity/tenants HTTP/1.1
または
GET /analytics/v1/identity/tenants/{tenant-id} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTPレスポンス
{
    "schemas": [
        "urn:scim:schemas:core:2.0:Tenant"
    ],
    "id": "tenant-uuid-1",
    "displayName": "Customer Name",
    "description": "",
    "tenantType": "CUSTOMER",
    "subTypes": [],
    "phoneNumber": {
        "value": "555-5555",
        "type": "work"
    },
    "ownerId": "test-emailid@email.com"
    ....
}

 

 

 

フィルタリング、並べ替え、ページネーションの演算

 

フィルタリング

フィルタリングはオプションで使用できます。ユーザーは、filter式を含む「filter」URLクエリパラメーターを指定して、リソースのサブセットをリクエストできます。このパラメーターが指定された場合、filter式と一致するリソースのみを返します。filterパラメーターで使用される式言語では、属性および直定数の参照がサポートされます。直定数の値には、二重引用符で囲まれた文字列、数字、二重引用符で囲まれた日時、ブール値 (trueまたはfalse) を使用できます。文字列直定数は、有効なJSON文字列であることが必要です。属性名および属性演算子では、大文字と小文字が区別されません。

たとえば、以下の2つの式は同じ論理値と見なされます。
filter=userName Eq "john"
filter=Username eq "john"

filterパラメーターには、1つ以上の有効なブール式を含める必要があります。各式には、属性名の後に、属性演算子とオプションの値を含める必要があります。2つの論理演算子を使用して、複数の式を組み合わせることができます。さらに、「()」を使用して式をグループ化することができます。以下の表には、式でサポートされる演算子が挙げられています。

属性演算子
演算子
説明
動作
eq
equal (等しい)
一致するには、属性と演算子の値が同じである必要があります。
co
contains (含む)
一致するには、演算子の値全体が属性値の文字列に含まれている必要があります。
sw
starts with (...から始まる)
一致するには、演算子の値全体が属性値の文字列に含まれており、属性値で開始される必要があります。2つの文字列が同一である場合に、この条件が満たされます。
pr
present (has value) (存在する、値がある)
属性に空以外の値がある場合、または複雑な属性では空以外のノードが含まれている場合に、一致と見なされます。
gt
greater than (...より大きい)
属性値が演算子の値より大きい場合に、一致と見なされます。実際の比較方法は、属性のタイプによって異なります。文字列の属性タイプでは、辞書学的観点での比較になり、日時タイプでは時系列の比較になります。
ge
greater than or equal (...以上)
属性値が演算子の値以上の場合に、一致と見なされます。実際の比較方法は、属性のタイプによって異なります。文字列の属性タイプでは、辞書学的観点での比較になり、日時タイプでは時系列の比較になります。
lt
less than (...より小さい)
属性値が演算子の値より小さい場合に、一致と見なされます。実際の比較方法は、属性のタイプによって異なります。文字列の属性タイプでは、辞書学的観点での比較になり、日時タイプでは時系列の比較になります。
le
less than or equal (...以下)
属性値が演算子の値以下の場合に、一致と見なされます。実際の比較方法は、属性のタイプによって異なります。文字列の属性タイプでは、辞書学的観点での比較になり、日時タイプでは時系列の比較になります。
neq
not equal (等しくない)
一致するには、属性と演算子の値が同じではない必要があります

 

論理演算子
演算子
説明
動作
and
論理積
両方の式がtrueの場合にのみ、フィルターに一致すると見なされます。
or
論理和
いずれかの式がtrueの場合に、フィルターに一致すると見なされます。

 

グループ化演算子
演算子
説明
動作
()
優先順位を指定するグループ化
ブール式では、半角括弧を使用してグループ化し、演算で評価される標準の順番を変更できます。つまり、OR論理演算子の後に、AND論理演算子が評価されます。

 

フィルターは、演算の標準の順番で評価される必要があります。属性演算子が最も優先され、その次にグループ化演算子 (半角括弧)、AND論理演算子、OR論理演算子と続きます。

filter式で指定した属性が、複数値の属性である場合、指定された属性のインスタンスのいずれかが、指定された条件を満たす場合に、リソースが一致するものと見なされます。例: ユーザーに複数のメールアドレス値が指定されている場合、その1つが一致するだけで、ユーザー自体が一致すると見なされます。複雑な属性では、標準の属性表記を用いて、完全に指定された副属性を指定する必要があります。たとえば、userNameでフィルタリングするには、パラメーター値はuserNameになり、ファーストネームでフィルタリングするには、パラメーター値はname.givenNameになります。

プロバイダーは、追加のフィルター演算をサポートしている場合があります。プロバイダーは、指定したフィルター演算が認識されない場合には、結果のフィルタリングを拒否し、人間が判読できる適切なレスポンスとともにHTTP 400エラーを返す必要があります。たとえば、ユーザーが「regex」という名前のサポート対象外の演算子を指定した場合、サービスプロバイダーはユーザーのエラーを特定するエラーレスポンスの説明を指定する必要があります。例: 「演算子「regex」はサポートされていません。」

文字列タイプの属性では、デフォルトで大文字と小文字が区別されません。ただし、属性タイプがcaseExact文字列で定義されている場合を除きます。属性演算子「eq」、「co」、「sw」は、すべての文字属性でcaseIgnore一致を実行する必要があります。ただし、属性がcaseExactとして定義されている場合を除きます。デフォルトで、すべての文字列属性はcaseIgnoreです。

例:
filter=dateenrolled gt "2011-05-13T04:42:34Z"

filter= ( devicetype eq \"Desktop\" ) and ( devicetype eq \"Notebook\" )

 

並べ替え

並べ替えはオプションで使用できます。並べ替えにより、ユーザーはリソースが返される順番を指定できます。このためには、sortByとsortOrderのURLパラメーターの組み合わせを指定します。

sortBy
sortByパラメーターでは、返されるレスポンスの順番を指定するために使用される値の属性を指定します。sortBy属性が単一の属性に対応する場合、リソースはその属性の値に応じて並べ替えられます。複数の値を持つ属性である場合は、リソースはプライマリ属性の値 (該当する場合)、またはリストの最初の値 (該当する場合) によって並べ替えられます。属性が複雑な場合、属性名は標準の属性表記で指定された副属性へのパスであることが必要です。例: sortBy=name.givenName。すべての属性タイプで、指定されたsortBy値にデータがない場合は、「sortOrder」パラメーターによって並べ替えられます。つまり、ascendingであれば末尾に、descendingであれば先頭に並べ替えられます。

sortOrder
sortByパラメーターが適用される順番です。許可される値は「ascending」と「descending」です。sortByに値が指定されており、sortOrderが指定されていない場合は、デフォルトでsortOrderはascendingに設定されます。文字列タイプの属性では、デフォルトで大文字と小文字が区別されません。ただし、属性タイプがcaseExact文字列で定義されている場合を除きます。sortOrderでは、属性タイプに沿って並べ替えられる必要があります。つまり、caseIgnore属性では、大文字と小文字を区別せずに、Unicodeのアルファベット順に結果が並べ替えられます (固有のロケールは考慮されません)。caseExact属性タイプでは、大文字と小文字を区別して、Unicodeのアルファベット順に並べ替えられます。

 

サンプル: 単一列の並べ替え
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled&sortOrder=asc HTTP/1.1
Host: daas.api.hp.com
Query String Parameters: sortBy=dateenrolled& sortOrder=asc

 

サンプル: 複数列の並べ替え
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled%20desc,devicename%20asc HTTP/1.1
Host: daas.api.hp.com
Query String Parameters: sortBy: dateenrolled desc, devicename asc

 

 

ページネーション

ページネーションパラメーターはまとめて使用して、ユーザーやサービスプロバイダーが読みやすいように、多数のリソースを「ページ分け」できます。ページネーションはセッションベースではないため、反復可能な結果は期待できません。たとえば、1のstartIndexから始まる10個のリリースのリストをリクエストすると、リクエストを反復するたびに異なる結果が返されることがあります。これは、リクエストの合間に元の結果に含まれるリソースが削除されたり、新しいリソースが追加されたりするためです。ページネーションパラメーターと一般的な動作には、OpenSearchプロトコルのものが使用されます。

以下の表では、URLページネーションパラメーターについて説明しています。

 

ページネーションリクエストパラメーター
パラメーター
説明
デフォルト
startIndex
最初の検索結果に対する1ベースのインデックス。
1
count
負の数ではない整数。ページごとに、希望する検索結果の最大数を指定します。例: 10。
なし。これを指定する場合、サービスプロバイダーは、指定された数よりも多くの結果を返してはいけません。ただし、これよりも少ない結果を返すことはできます。これが指定されない場合、結果の最大数はサービスプロバイダーが設定します。

 

ページネーションのレスポンスエレメント
エレメント
説明
itemsPerPage
負の数ではない整数。クエリレスポンスのページで返される検索結果の数を指定します。例: 10。
totalResults
負の数ではない整数。ユーザーのクエリと一致する結果の合計数を指定します。例: 1000。
startIndex
検索結果の現在のセットにおける最初の結果の1ベースのインデックス。例: 1。

たとえば、最初の10名のユーザーを取得するには、startIndexを1に、countを10に指定します。

レスポンスのサンプル

{
  "totalResults":100,
  "itemsPerPage":10,
  "startIndex":1,
  "schemas":["urn:scim:schemas:core:1.0"],
  "Resources":[{
    ...
  }]
}

上記の例で、ページングを続行するには、startIndexを11に設定して、再度取得します。

 

 

日時変換

 

APIレスポンスで日付とタイムスタンプのデータタイプが指定された属性については、HP TechPulse Analytics APIは、以下の2つのシナリオのいずれかを活用します。

  • シナリオ1: プロアクティブ管理サーバーの時間から、APIを呼び出しているユーザーの企業またはパートナーのプロアクティブ管理ポータルの優先タイムゾーン設定に、データの日付とタイムスタンプを変換します。または、
  • シナリオ2: 現地のタイムゾーンでデバイスから報告されたデータの日付とタイムスタンプを使用します。

Swagger APIリファレンスでは、日付およびタイムスタンプの各属性に使用されるシナリオが一覧表示されています。

シナリオ1

  • (APIを呼び出す) ユーザーが企業に属している場合、APIレスポンスでは、企業のプロアクティブ管理ポータルで設定された優先タイムゾーン設定に基づいて、日付とタイムスタンプの値を返します。
例: 優先タイムゾーン (lastSeenDate)
HTTPリクエスト
POST /analytics/v1/reports/batteryrep/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <Access Token>
Body: No tenants

HTTPレスポンス
{
    "totalResults": 7,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "counterId": 7,
            "companyId": "1",
            "companyName": "company-name",
            "deviceId": "123456",
            "deviceName": "device-name",
            "serialNumber": "device-sn",
            "deviceManufacturer": "HP",
            "manufactureDate": "07/16/2014",
            "lastSeenDate": "11/12/2018 at 09:45 PM (CDT)",
            "batterySn": "battery-sn",
            "batteryGrade": "Severe degradation",
            "batteryReplacementTimeframe": "0",
            "deviceType": "Notebook",
            "deviceModel": "HP EliteBook Folio 9480m",
            "locationcc": "United States",
            "batteryHealth": "Fail",
            "warStatus": "Out of warranty",
            "ctNumber": "ct-number",
            "dwarstatus": "Unknown",
            "oblenddate": "Unknown"
        }
    ]
}

 

  • (APIを呼び出している) ユーザーが3社を管理するパートナーに所属しており、3社それぞれが異なる優先タイムゾーン (TZ1、TZ2、TZ3) を設定し、パートナーの優先タイムゾーンがTZ4に設定されている場合、レスポンスではパートナーのプロアクティブ管理ポータルで設定された優先タイムゾーン (TZ4) に基づいて、日付とタイムスタンプの値が返されます。
例: 現地のタイムゾーン (Date Occurred - dateList)
HTTPリクエスト
POST /analytics/v1/reports/hwbluescreen/details/type/grid?count=1&startIndex=0 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ]
}

HTTPレスポンス
{
    "totalResults": 153919,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "deviceId": "12345",
            "devicename": "device-name",
            "devicesn": "device-sn",
            "drivercrashBugcheckcode": "000000d1",
            "drivercrashDescription": "DRIVER_IRQL_NOT_LESS_OR_EQUAL",
            "drivercrashHyperlink": "https://msdn.microsoft.com/en-us/library/windows/hardware/ff560244(v=vs.85).aspx",
            "counterid": 50,
            "dateList": "08/28/2018 18:37:09",
            "lastonlinedate": "01/23/2019 at 06:58 AM (CST)",
            "causedByDriver": "Unable to determine",
            "driverVersion": "Unable to determine",
            "locationcc": "United States",
            "osRelease": "Win10 - 1703"
        }
    ]
}

 

 

 

数字形式

 

HP TechPulse Analytics APIでは、数字形式を使用した属性については、APIを呼び出すユーザーのプロアクティブ管理ポータルのユーザー言語設定を活用します。たとえば、ユーザーの言語設定が英語 (米国) に設定されている場合には、APIによって返されるすべての数値属性の値で、米国の表記方法が使用されます。

ユーザーの言語設定を指定するには、プロアクティブ管理ポータルで手動で設定するか、を呼び出すことができます。

言語設定を手動で設定するには、IT管理者、レポート管理者、パートナー管理者、またはパートナースペシャリストの役割が割り当てられたプロアクティブ管理ユーザーが、プロアクティブ管理ポータルにサインインして、以下のステップを実行します。1. プロアクティブ管理ポータルにログインします。2. メインページで、ユーザーアイコン、[EDIT MY PROFILE] (自分のプロフィールを編集) の順にクリックして、[User Details] (ユーザー詳細) ページを開きます。3. [User Details] (ユーザー詳細) ページで、最初のセクションの [Edit] (編集) ボタンをクリックします。4. [Language] (言語) ドロップダウンから言語を変更します。5. [Save] (保存) をクリックします。

ユーザーの既存の言語設定を取得するには、次を使用します:

HTTPリクエスト:
POST /analytics/v1/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTPレスポンス:
{
    "totalResults": 1,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "byPercentages": [
                {
                    "appName": "Windows Explorer",
                    "usage": 52.44
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 51.87
                }
            ],
            "byUsageHours": [
                {
                    "appName": "Windows Explorer",
                    "usage": 81.6
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 50.27
                }
            ]
        }
    ]
}

 

 

 

Exclude/Include属性

 

指定する属性を指定します。HP TechPulse Analyticsではデフォルトで、リソースがリクエストされると、クライアントアプリケーションが読み取りを許可されているすべての属性を返します。この動作をオーバーライドするには、以下の特別なクエリパラメーターのいずれかを指定します。

パラメーター
説明
attributes
レスポンスに属性のセットを含めることを意味します。属性名をコンマ区切りのリストで指定できます。拡張スキーマ属性名には、プレフィックスとして拡張スキーマURNを指定する必要があります。
excludedAttributes
レスポンスで属性のセットを除外することを意味します。属性名をコンマ区切りのリストで指定できます。拡張スキーマ属性名には、プレフィックスとして拡張スキーマURNを指定する必要があります。

attributesとexcludedAttributesパラメーターは相互に排他的です。同じリクエストで両方を指定しないでください。各リソースの詳しい属性のリストについては、APIリファレンスを参照してください。

注: 読みやすくするため、ここに記載のfilter文字列とattributesリストには、URLエンコードが行われていません。

特定の除外属性以外のすべての属性を返すPOSTリクエストの例
HTTPリクエスト
POST /analytics/v1/reports/softuti/summary/type/grid?count=2&startIndex=1&excludedAttributes=resources.appName,resources.appVersion HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTPレスポンス
{
    "totalResults": 31,
    "startIndex": 1,
    "itemsPerPage": 2,
    "resources": [
        {
            "deviceCount": "105873",
            "appUsageCount": "55160",
            "appUsagePercent": "52.10",
            "appUsageHours": "7900112.50",
            "appAvgUsageTime": "74.62",
            "rankAppUsagePercent": "3",
            "rankAppUsageHrs": "4"
        },
        {
            "deviceCount": "105873",
            "appUsageCount": "54915",
            "appUsagePercent": "51.87",
            "appUsageHours": "9808576.00",
            "appAvgUsageTime": "92.64",
            "rankAppUsagePercent": "4",
            "rankAppUsageHrs": "5"
        }
    ]
}

 

特定の除外属性を返すPOSTリクエストの例
HTTPリクエスト
POST /analytics/v1/reports/softuti/summary/type/grid?count=2&startIndex=1&attributes=resources.appName,resources.appVersion HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTPレスポンス
{
    "resources": [
        {
            "appName": "Windows Shell Experience Host",
            "appVersion": "10.0.15063.909"
        },
        {
            "appName": "Internet Explorer",
            "appVersion": "11.00.15063.0"
        }
    ]
}

 

 

 

デフォルトのレスポンス制限

 

大量のデータを要求する複数のリクエストがAPIに集中することを防ぐため、プロアクティブ管理には、Details APIリクエストでデフォルトのレスポンス制限が設定されています。リクエスト送信数がデフォルトのレスポンス制限を上回る場合、プロアクティブ管理はこれを明示的にデフォルトの制限に置き換え、これに基づいて応答します。API開発者は、個々のDetails APIに制限を設け、すべてのAPIの全体的なパフォーマンスを向上し、ページネーションオプションを活用することができます。デフォルトのレスポンス制限 (最大1000) は、現在のサーバー構成と全体的なシステムパフォーマンスに基づいています。

 

 

Summary APIとDetails APIの比較

 

HP TechPulse Analyticsでは、以下の2種類のAPIを提供しています。

  • Summary API: Summary APIでは、特定の属性に関する集計情報を提供します。通常使用される命名規則は、< /analytics/v1/reports/report-name/report-option/type/graph>の形式です。提供される最も一般的な集計形式には、特定の属性に対するSUM、COUNT、DISTINCT COUNTがあり、特定の他の属性に基づいてグループ化されます。

たとえば、/analytics/v1/reports/hwinv/deviceType/type/graphでは、さまざまなデバイスタイプ (ノートブック、デスクトップ、タブレット、スマートフォンなど) ごとに、デバイス数に関する集計情報を提供します。

Details APIの例
HTTPリクエスト
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTPレスポンス
{
    "totalResults": 11,
    "startIndex": 0,
    "itemsPerPage": 11,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "Unknown",
            "osversion": "Unknown",
            "osreleselToggaleEnabled": true
        },
        ... // 11 Records
    ]
}

 

  • Details API: Details APIでは、すべての属性に関する詳細情報を提供します。通常使用される命名規則は、</analytics/v1/reports/report-name/report-option /type/grid>の形式です。

たとえば、/analytics/v1/reports/hwinv/details/type/gridでは、プロアクティブ管理で認識されたハードウェアインベントリの属性すべてに関する情報を提供します。

 

Summary APIの例
HTTPリクエスト
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTPレスポンス
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 8,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                ...// 4 records
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        ...// 2 records
    ]
}

 

 

 

エラーメッセージ

承認エラー

HP DaaSで承認リクエストのエラーが発生した場合 (/oauth/v1/authorizeリクエスト自体またはこのリクエストの処理で)、以下の2つの方法のうち、いずれかで応答します。

リダイレクトURIが無効であるか、他の理由で使用できない場合、またはクライアントIDが欠落しているか、無効な場合には、HP DaaSはアプリケーションにエラーを送信できません。この場合は、エンドユーザーに直接エラーメッセージを表示します。

それ以外の場合は、HP DaaSではリダイレクトURIにリダイレクトし、errorおよびerror_descriptionのクエリパラメーターを付加します。たとえば、承認URLで無効な範囲がリクエストされた場合には、HP DaaSは以下のURLを呼び出します。

無効な範囲

http://redirect-uri/?error=invalid_scope&error_description=The%20requested%20scope%20is%20invalid,%20unknown,%20or%20malformed&state=daas_session
 
無効なリダイレクトURL

http://redirect-uri/?error=invalid_request&error_description=Invalid%20redirect_uri%20parameter&state=daas_session

 

トークンのエラー

oauth/v1/tokenエンドポイントから返されるエラーでは通常、400のHTTPステータスを使用します。本文は、エラーの説明からなるJSONドキュメントです。

例:

無効なレスポンス
{ 
  "Error": "Incorrect or missing authorization code" 
}

 

エラーコードと説明に使用できる値は、以下のように指定されます。

エラーコード
エラーの説明
400
承認コードが正しくないか、指定されていません。
401
承認されていません
402
クライアントIDが無効です
500
内部サーバーエラーです。