Best Practices for Application Development

Volver al principio

Para incrementar la confianza y comodidad de HP DaaS para los miembros al conceder acceso a la aplicación a sus datos, es importante ofrecer transparencia sobre cómo se usarán sus datos. Siga estas sugerencias para ayudarle a que su aplicación tenga éxito al entregar valor para los miembros de HP DaaS.

 

API autogestionadas vs. gestionadas por socio

 

Los informes de HP Device as a Service Proactive Management con TechPulse (de ahí el nombre Proactive Management) proporcionan un análisis detallado de las capacidades de planificación, optimización de costos y administración de servicios de los dispositivos registrados en Proactive Management.

Los clientes que desean gestionar la analítica de Proactive Management por su propia cuenta son llamados "clientes autogestionados". Los clientes que eligen externalizar la gestión de la analítica de Proactive Management con sus socios preferidos son llamados "clientes gestionados por socio".

Los clientes autogestionados únicamente pueden obtener datos para su cuenta de Proactive Management. Los clientes gestionados por socio pueden obtener datos para todos sus clientes gestionados en Proactive Management. Por ejemplo, si un socio A de Proactive Management gestiona tres clientes, X, Y y Z, invocar una API de HP TechPulse Analytics regresará información de analítica para los tres clientes, ya sea de forma separada para las API de detalles e información agregada para los tres clientes en la API de resumen.

 

Ejemplo de una solicitud de POST - API de resumen autogestionada
Solicitud de HTTP
POST /analytics/v1/reports/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Portador <ACCESS_TOKEN>
Cuerpo: NO se necesita especificar ningún ID de tenantid aquí

Respuesta de 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
                }
            ]
        }
    ]
}

 

Ejemplo de una solicitud de POST - API de detalles autogestionada
Solicitud de HTTP
POST /analytics/v1/reports/softuti/summary/type/grid?count=2 HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Portador <ACCESS_TOKEN>
Cuerpo: NO se necesita especificar ningún ID de tenantid aquí

Respuesta de 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"
        }
    ]
}

 

Ejemplo de una solicitud de POST - API de detalles gestionada por socio
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador
Cuerpo: SIN id de inquilino

Respuesta de 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 registros
    ]
}

 

Ejemplo de una solicitud de POST - API de resumen gestionada por socio
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador
Cuerpo: SIN id de inquilino

Respuesta de 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
        }
    ]
}

 

Ejemplo de una solicitud de POST - API de detalles gestionada por socio
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador
Cuerpo:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":" ( devicetype eq \"Desktop\" ) "
}

Respuesta de 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
        }
    ]
}

 

Ejemplo de una solicitud de POST - API de resumen gestionada por socio
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Portador <Access Token>
Cuerpo:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":" ( devicetype eq \"Desktop\" ) "
}

Respuesta de 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
        }
    ]
}

 

 

 

Identificadores de empresa, usuario y dispositivo

 

Todas nuestras API de analítica e incidentes aceptan identificadores únicos de empresa, dispositivo y usuario de tipo GUID, mientras que las API responden con identificadores numéricos. Una API de mapa de identidades puede ser llamada para obtener el identificador o GUID de tipo correspondiente para identificadores numéricos.

Ejemplos de API de mapa de identidades
Solicitud de HTTP
GET /analytics/v1/reports/id/{int-id}/type/{id-type} HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador

Respuesta de HTTP
Para dispositivo:
{
    "intId": 12345,
    "idType": "deviceid",
    "uuid": "device-uuid-1"
}

Para usuario:
{
    "intId": 1234,
    "idType": "userid",
    "uuid": "user-uuid-1"
}

Para empresa:
{
    "intId": 1458,
    "idType": "companyid",
    "uuid": "tenant-uuid-1"
}

 

Esta es un API de servicio de identidad para obtener todos los detalles de los usuarios o con base en el user_id.

Ejemplos de API de identidad: Para obtener los detalles del usuario
Solicitud de HTTP
GET /analytics/v1/identity/users HTTP/1.1
O
GET /analytics/v1/identity/users/{user-id} HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador

Respuesta de 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": []
    .....
}

 

Esta es un API de servicio de identidad para obtener todos los detalles de los inquilinos o con base en el tenant_id.

Ejemplos de API de identidad: Para obtener los detalles del inquilino
Solicitud de HTTP
GET /analytics/v1/identity/tenants HTTP/1.1
O
GET /analytics/v1/identity/tenants/{tenant-id} HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador

Respuesta de 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"
    ....
}

 

 

 

Operaciones de filtrado, ordenado y paginado

 

Filtrado

El filtrado es OPCIONAL. Los consumidores pueden solicitar un subconjunto de recursos al especificar el parámetro de consulta de URL 'filter' que contiene una expresión de filtro. Cuando se especifica, únicamente los recursos que coincidan con la expresión del filtro DEBEN retornarse. El lenguaje de expresión que se usa en el parámetro del filtro soporta referencias para atributos y literales. Los valores literales pueden ser cadenas entre comillas dobles, números, tiempos de fechas entre comillas dobles y valores booleanos; por ejemplo, verdadero o falso. Las literales de cadena DEBEN ser cadenas de JSON válidas. El nombre de atributo y el operador de atributo no distingue mayúsculas y minúsculas.

Por ejemplo, las siguientes dos expresiones evaluarán con el mismo valor lógico:
filter=userName Eq "john"
filter=Username eq "john"

El parámetro de filtro DEBE contener al menos una expresión booleana válida. Cada expresión DEBE contener un nombre de atributo seguido por un operador de atributo y un valor opcional. Múltiples expresiones PUEDEN combinarse usando los dos operadores lógicos. Otras expresiones pueden agruparse usando "()". Los operadores soportados en la expresión están listados en la siguiente tabla.

Operadores de atributo
Operador
Descripción
Comportamiento
eq
equal
Los valores de atributo y operador deben ser idénticos para que haya coincidencia.
co
contains
Todo el valor de operador debe ser una subcadena del valor de atributo para que haya coincidencia.
sw
starts with
Todo el valor de operador debe ser una subcadena del valor de atributo, comenzando al principio del valor de atributo. Este criterio se satisface si las dos cadenas son idénticas.
pr
present (has value)
Si el atributo tiene un valor no vacío, o si contiene un nodo no vacío para atributos complejos, hay coincidencia.
gt
greater than
si el valor de atributo es mayor que el valor de operador, hay coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, esta es una comparación lexicográfica, y para tipos de DateTime, es una comparación cronológica.
ge
greater than or equal
si el valor de atributo es mayor o igual que el valor de operador, hay coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, esta es una comparación lexicográfica, y para tipos de DateTime, es una comparación cronológica.
lt
less than
si el valor de atributo es menor que el valor de operador, hay coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, esta es una comparación lexicográfica, y para tipos de DateTime, es una comparación cronológica.
le
less than or equal
si el valor de atributo es menor o igual que el valor de operador, hay coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, esta es una comparación lexicográfica, y para tipos de DateTime, es una comparación cronológica.
neq
not equal
Los valores de atributo y operador no deben ser idénticos para que haya coincidencia

 

Operadores lógicos
Operador
Descripción
Comportamiento
and
Y lógico
El filtro únicamente es coincidencia si ambas expresiones se evalúan como verdaderas.
or
O lógico
El filtro es coincidencia si cualquier expresión se evalúa como verdadera.

 

Operadores de agrupación
Operador
Descripción
Comportamiento
()
Agrupación de precedencia
Las expresiones booleanas pueden agruparse usando paréntesis para cambiar el orden estándar de las operaciones; por ejemplo, evaluar operadores lógicos O antes que los operadores lógicos Y.

 

Los filtros DEBEN evaluarse usando el orden estándar de las operaciones. Los operadores de atributo tienen la precedencia más alta, seguidos por el operador de agrupación (es decir, paréntesis), seguido por el operador lógico U, seguido por el operador lógico O.

Si el atributo especificado en una expresión de filtro es un atributo multivalorado, el recurso DEBE coincidir si cualquiera de las instancias del atributo dado coincide con el criterio especificado; por ejemplo, si un usuario tiene múltiples valores de correo electrónico, únicamente uno debe coincidir para que el usuario completo coincida. Para atributos complejos, un subatributo calificado DEBE especificarse usando notación de atributo estándar. Por ejemplo, para filtrar por userName, el valor de parámetro es userName, y para filtrar por el nombre, el valor de parámetro es name.givenName.

Los proveedores PUEDEN soportar operaciones de filtro adicionales si lo desean. Los proveedores DEBEN rechazar el filtro de resultados si la operación de filtro especificada no es reconocida y regresar un error HTTP 400 con una respuesta legible para los humanos adecuada. Por ejemplo, si un consumidor especificó un operador no soportado llamado 'regex', el proveedor de servicios debe especificar una descripción de respuesta de error que identifique el error del consumidor; por ejemplo, "El operador 'regex' no es soportado'.

Los atributos de tipo de cadena no distinguen mayúsculas y minúsculas de forma predeterminada, a menos que el tipo de atributo se defina como una cadena caseExact. Los operadores de atributo 'eq', 'co' y 'sw' DEBEN realizar coincidencia de caseIgnore para todos los atributos de cadena, a menos que el atributo se defina como caseExact. De forma predeterminada, todos los atributos de cadena son caseIgnore.

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

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

 

Ordenación

La ordenación es OPCIONAL. La ordenación permite a los consumidores especificar el orden en el cual se regresan los recursos al especificar una combinación de parámetros de URL de sortBy y sortOrder.

sortBy
El parámetro de sortBy especifica el atributo cuyo valor DEBE usarse para ordenar las respuestas retornadas. Si el atributo de sortBy corresponde a un atributo singular, los recursos se ordenan de acuerdo con el valor de ese atributo; si es un atributo multivalorado, los recursos se ordenan por el valor del atributo primario, si existe, o de lo contrario por el primer valor en la lista, si existe. Si el atributo es complejo, el nombre del atributo debe ser una ruta hacia un subatributo en la notación de atributo estándar; por ejemplo, sortBy=name.givenName. Para todos los tipos de atributos, si no hay datos para el valor de sortBy especificado, se ordenan a través del parámetro 'sortOrder'; por ejemplo, se ordenan al último si es ascendente y primero si es descendente.

sortOrder
El orden en el cual se aplica el parámetro sortBy. Los valores permitidos son "ascendente" y "descendente". Si se proporciona un valor para sortBy y no se especifica un sortOrder, sortOrder DEBE ser ascendente de forma predeterminada. Los atributos de tipo de cadena no distinguen mayúsculas y minúsculas de forma predeterminada, a menos que el tipo de atributo se defina como una cadena caseExact. sortOrder DEBE ordenar de acuerdo con el tipo de atributo; por ejemplo, para atributos caseIgnore, ordena el resultado sin distinguir mayúsculas y minúsculas, orden alfabético de Unicode, sin local específico implícito y para tipos de atributo caseExact, ordena el resultado distinguiendo mayúsculas y minúsculas, orden alfabético de Unicode.

 

Ejemplo: ordenación de una sola columna
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled&sortOrder=asc HTTP/1.1
Host: daas.api.hp.com
Parámetros de cadena de consulta: sortBy=dateenrolled& sortOrder=asc

 

Ejemplo: ordenación de múltiples columnas
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled%20desc,devicename%20asc HTTP/1.1
Host: daas.api.hp.com
Parámetros de cadena de consulta: sortBy: dateenrolled desc, devicename asc

 

 

Paginación

Los parámetros de paginación pueden usarse juntos para "pasar páginas" de grandes números de recursos, para no abrumar al consumidor o proveedor de servicios. La paginación no se basa en la sesión, por lo que los consumidores nunca DEBEN asumir resultados repetibles. Por ejemplo, una solicitud para una lista de 10 recursos comenzando con un startIndex de 1 puede regresar resultados diferentes cuando se repite como un recurso en el resultado original, puede ser eliminado o se pueden agregar nuevos entre una solicitud y otra. Los parámetros de paginación y el comportamiento general se derivan del protocolo OpenSearch.

La siguiente tabla describe los parámetros de paginación de URL.

 

Parámetros de solicitud de paginación
Parámetro
Descripción
Predeterminado
startIndex
El índice basado en 1 del primer resultado de búsqueda.
1
count
Entero no negativo. Especifica el número máximo deseado de resultados de búsqueda por página: por ejemplo, 10.
Ninguno. Cuando se especifica, el proveedor de servicios no DEBE regresar más resultados que los especificados, pero PUEDE regresar menos resultados. Si no se especifica, el número máximo de resultados es establecido por el proveedor de servicios.

 

Elementos de respuesta de paginación
Elemento
Descripción
itemsPerPage
Entero no negativo. Especifica el número de resultados de búsqueda regresado en una página de respuesta de consulta; por ejemplo, 10.
totalResults
Entero no negativo. Especifica el número total de resultados que coinciden con la consulta del consumidor; por ejemplo, 1000.
startIndex
El índice basado en 1 del primer resultado en el conjunto actual de resultados de búsqueda; por ejemplo, 1.

Por ejemplo, para recuperar los primeros 10 usuarios, establezca startIndex en 1 y el conteo en 10.

Respuesta de ejemplo

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

Considerando el ejemplo anterior, para continuar la paginación, establezca startIndex en 11 y vuelva a obtener.

 

 

Conversiones de fecha y hora

 

Para atributos con tipos de datos de fecha y marca de tiempo en respuesta de API, las API de TechPulse Analytics aprovechan uno de los siguientes dos escenarios:

  • Escenario 1. Convertir la fecha y marca de tiempo de los datos del tiempo del servidor de Proactive Management en la configuración de zona horaria preferida del portal de Proactive Management de la empresa del usuario o del socio que llama las API, o
  • Escenario 2. Usar la fecha y marca de tiempo de los datos informados de los dispositivos en su zona horaria local.

La referencia de API swagger lista el escenario usado para cada uno de los atributos de fecha y marca de tiempo.

Escenario 1

  • Si el usuario (llamando las API) pertenece a una empresa, la respuesta de la API regresará los valores de fecha y marca de tiempo con base en la configuración de la zona horaria preferida establecida en el portal de Proactive Management para la empresa.
Ejemplo: Zona horaria preferida (lastSeenDate)
Solicitud de HTTP
POST /analytics/v1/reports/batteryrep/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Portador <Access Token>
Cuerpo: Sin inquilinos

Respuesta de 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"
        }
    ]
}

 

  • Si el usuario (llamando las API) pertenece a un socio que gestiona tres empresas y las tres empresas tienen diferentes configuraciones de zona horaria preferida (TZ1, TZ2 y TZ3) y la configuración de zona horaria preferida del socio es TZ4, la respuesta regresará los valores de fecha y marca de tiempo con base en la configuración de zona horaria preferida establecida en el portal de Proactive Management del socio (es decir, TZ4)
Ejemplo: Zona horaria local (Fecha de ocurrencia - dateList)
Solicitud de HTTP
POST /analytics/v1/reports/hwbluescreen/details/type/grid?count=1&startIndex=0 HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador
Cuerpo:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ]
}

Respuesta de 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"
        }
    ]
}

 

 

 

Formatos numéricos

 

Las API de HP TechPulse Analytics aprovechan la configuración de idioma del portal de Proactive Management del usuario que está llamando las API, para atributos con formatos numéricos. Por ejemplo, si la configuración de idioma del usuario está establecida como Inglés (Estados Unidos), entonces los valores de todos los atributos numéricos retornados por las API seguirán las convenciones de los Estados Unidos.

La configuración de idioma del usuario puede establecerse manualmente en el portal de Proactive Management o llamando la .

Para establecer la configuración de idioma manualmente, el usuario de Proactive Management con el rol de administrador de TI, administrador de informes, administrador de socios o especialista en socios inicia sesión en el portal de Proactive Management y realiza los siguientes pasos. 1. Iniciar sesión en el portal de Proactive Management. 2. En la página principal, hacer clic en el icono Usuario y después EDITAR MI PERFIL para abrir la página de Detalles del usuario. 3. En la página de Detalles del usuario, hacer clic en el botón Editar en la primera sección. 4. Cambiar el idioma en el menú desplegable Idioma. 5. Hacer clic en Guardar

Para obtener la configuración de idioma del usuario existente, use la

Ejemplo
Solicitud de HTTP:
POST /analytics/v1/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Autorización: Bearer <ACCESS_TOKEN>

Respuesta de 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
                }
            ]
        }
    ]
}

 

 

 

Excluir/incluir atributos

 

Al especificar atributos para regresar de forma predeterminada, HP TechPulse Analytics regresa todos los atributos que la aplicación de su cliente está autorizada para leer cuando solicite un recurso. Puede especificar cualquiera de los siguientes parámetros de consulta especiales para anular este comportamiento:

Parámetro
Descripción
attributes
Indica el conjunto de atributos a incluir en la respuesta. Requiere una lista de nombres de atributo separados por comas. Los nombres de atributo de esquema de extensión deben llevar un prefijo con el esquema de extensión URN.
excludedAttributes
Indica un conjunto de atributos a excluir de la respuesta. Requiere una lista de nombres de atributo separados por comas. Los nombres de atributo de esquema de extensión deben llevar un prefijo con el esquema de extensión URN.

Los parámetros attributes y excludedAttributes son mutuamente exclusivos. No especifique ambos en la misma solicitud. Consulte la Referencia de API para obtener una lista completa de atributos para cada recurso.

NOTA: Para legibilidad, la cadena de filtro y la lista de atributos mostrada aquí aún no han sido codificadas en URL.

Ejemplo de una solicitud POST que regresa todos los atributos, excepto los atributos específicos excluidos
Solicitud de 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
Autorización: Bearer <ACCESS_TOKEN>

Respuesta de 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"
        }
    ]
}

 

Ejemplo de una solicitud POST que regresa atributos específicos excluidos
Solicitud de 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
Autorización: Bearer <ACCESS_TOKEN>

Respuesta de HTTP
{
    "resources": [
        {
            "appName": "Windows Shell Experience Host",
            "appVersion": "10.0.15063.909"
        },
        {
            "appName": "Internet Explorer",
            "appVersion": "11.00.15063.0"
        }
    ]
}

 

 

 

Límite de respuesta predeterminado

 

Para evitar que las API sean abrumadas por solicitudes que piden grandes cantidades de datos, Proactive Management establece un límite de respuesta predeterminado en las solicitudes de API de detalles. Cuando los envíos de solicitudes exceden el límite de respuesta predeterminado, Proactive Management los reemplaza explícitamente con el límite predeterminado y responde acorde con ello. Como desarrollador de API, puede establecer los límites para API de detalles individuales para mejorar el rendimiento general a través de todas las API y aprovechar la opción de paginación. El límite de respuesta predeterminado (~1K) se basa en la configuración actual del servidor y en el rendimiento general del sistema.

 

 

API de resumen vs. de detalles

 

HP TechPulse Analytics proporciona dos tipos de API:

  • API de resumen. Las API de resumen proporcionan información agregada para ciertos atributos. La convención de nombres normalmente seguida tiene un formato de < /analytics/v1/reports/report-name/report-option/type/graph>. La forma más común de agregación proporcionada incluye SUM, COUNT y DISTINCT COUNT en atributos determinados, agrupados por otros atributos determinados.

Por ejemplo, /analytics/v1/reports/hwinv/deviceType/type/graph proporciona información de resumen sobre el conteo del número de dispositivos por diversos tipos de dispositivos (por ejemplo, Notebook, Desktop, Tablet, Smartphone etc.).

Ejemplo de API de detalles
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador

Respuesta de 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 registros
    ]
}

 

  • API de detalles. La API de detalles proporciona información detallada sobre todos los atributos. La convención de nombres normalmente seguida tiene un formato de </analytics/v1/reports/report-name/report-option /type/grid>.

Por ejemplo, /analytics/v1/reports/hwinv/details/type/grid proporciona información sobre todos los atributos del inventario de hardware expuesto en Proactive Management.

 

Ejemplo de API de resumen
Solicitud de HTTP
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Contenido-Tipo: application/json
Autorización: Token de acceso del portador

Respuesta de 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
    ]
}

 

 

 

Mensajes de error

Errores de autorización

Cuando HP DaaS encuentra un error en una solicitud de autorización, ya sea con la solicitud de /oauth/v1/authorize misma o con el procesamiento de la solicitud, responderá en una de dos formas:

Si el URI de redirección es inválido o no puede ser utilizado por alguna otra razón, o si el ID de cliente falta o es inválido, HP DaaS no podrá enviar un error de regreso a su aplicación. En este caso, mostrará un mensaje de error directamente para el usuario final.

De lo contrario, HP DaaS hará una redirección al URI de redirección, adjuntando el error y los parámetros de consulta de error_description. Por ejemplo, HP DaaS llamará el siguiente URL si se solicita un ámbito inválido en el URL de autorización:

Ámbito inválido

http://redirect-uri/?error=invalid_scope&error_description=The%20requested%20scope%20is%20invalid,%20unknown,%20or%20malformed&state=daas_session
 
URI de redirección inválido

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

 

Errores de token

Los errores retornados por el punto final de oauth/v1/token normalmente usan un estado de HTTP de 400; el cuerpo es un documento de JSON que consiste en la descripción del error.

Por ejemplo:

Respuesta inválida
{ 
  "Error": "Código de autorización incorrecto o faltante" 
}

 

Los posibles valores para el código de error y la descripción son como se muestra a continuación:

Código de error
Descripción del error
400
Código de autorización incorrecto o faltante.
401
No autorizado
402
clientId inválido
500
Error de servidor interno.