API de supervisión del servicio de derechos entitlement-service-monitoring-api

Resumen de API api-overview

La supervisión del servicio de derechos (ESM) se implementa como un proyecto WOLAP (Web-based Online Analytical Processing). ESM es una API web genérica de informes empresariales respaldada por un almacén de datos. Actúa como lenguaje de consulta HTTP que permite realizar operaciones OLAP típicas con RESTful.

La API de ESM proporciona una vista jerárquica de los cubos OLAP subyacentes. Cada recurso (dimensión en la jerarquía de dimensiones, asignado como segmento de ruta de URL) genera informes con métricas (agregadas) para la selección actual. Cada recurso señala a su recurso principal (para el resumen) y a sus subrecursos (para el desglose). El corte y el trozo se logran mediante parámetros de cadena de consulta que anclan dimensiones a valores o rangos específicos.

La API de REST proporciona los datos disponibles en un intervalo de tiempo especificado en la solicitud (volviendo a los valores predeterminados si no se proporciona ninguno), según la ruta de dimensión, los filtros proporcionados y las métricas seleccionadas. El intervalo de tiempo no se aplicará a los informes que no contengan dimensiones de tiempo (año, mes, día, hora, minuto, segundo).

La ruta raíz de la URL del punto de conexión devolverá las métricas agregadas generales dentro de un único registro, junto con los vínculos a las opciones de desglose disponibles. La versión de la API se asigna como el segmento final de la ruta del URI del extremo. Por ejemplo, https://mgmt.auth.adobe.com/esm/v3 significa que los clientes tendrán acceso a WOLAP versión 3.

Las rutas URL disponibles se pueden detectar mediante los vínculos contenidos en la respuesta. Las rutas de URL válidas se mantienen para asignar una ruta dentro del árbol de desglose subyacente que contiene las métricas agregadas (previamente). Una ruta de acceso en el formulario /dimension1/dimension2/dimension3 reflejará una agregación previa de esas tres dimensiones (el equivalente de un SQL clause GROUP BY dimension1, dimension2, dimension3). Si esta agregación previa no existe y el sistema no puede calcularla sobre la marcha, la API devolverá una respuesta 404 Not Found.

Árbol de desglose drill-down-tree

Los siguientes árboles de desglose ilustran las dimensiones (recursos) disponibles en ESM 3.0 para programadores y MVPD.

Dimension disponibles para programadores progr-dimensions

Día

Hora

Minuto

Dimension disponibles para MVPD mvpd-dimensions

Una GET al extremo de API https://mgmt.auth.adobe.com/esm/v3 devolverá una representación que contiene:

Siguiendo una ruta detallada (paso a paso):
/dimensionA/year/month/day/dimensionX recupera lo siguiente
respuesta:

Filtros

Excepto para las dimensiones de fecha y hora, cualquier dimensión disponible para la proyección actual (ruta de dimensión) puede filtrarse utilizando su nombre como parámetro de cadena de consulta.

Están disponibles las siguientes opciones de filtrado:

También existe un uso especial para los nombres de dimensión en la cadena de consulta: Si el nombre de dimensión se utiliza como parámetro de cadena de consulta sin valor, se indica a la API que devuelva una proyección que incluya esa dimensión en el informe.

Ejemplo de consultas de ESM

Los siguientes parámetros de cadena de consulta tienen significados reservados para la API (y, por lo tanto, no se pueden usar como nombres de dimensión o, de lo contrario, no sería posible ningún filtrado para una dimensión de este tipo).

Parámetros de cadena de consulta reservada de API de ESM

El único método HTTP disponible actualmente es GET.

Códigos de estado de API de ESM esm-api-status-codes

Formatos de datos data-formats

Los datos están disponibles en los siguientes formatos:

Los clientes pueden utilizar las siguientes estrategias de negociación de contenido (la prioridad viene dada por la posición en la lista: lo primero es lo primero):

Tanto la "extensión" como el parámetro de consulta admiten los siguientes valores:

Si ninguna de las estrategias especifica ningún tipo de medio, la API producirá contenido JSON de forma predeterminada.

Lenguaje de aplicación de hipertexto hypertext-application-language

Para JSON y XML, la carga útil se codificará como HAL, tal como se describe aquí: http://stateless.co/hal_specification.html.

El informe real (una etiqueta o propiedad anidada denominada "informe") constará de la lista real de registros que contienen todas las dimensiones y métricas seleccionadas o aplicables con sus valores, codificados de la siguiente manera:

JSON

 "report": [
  {
    "dimension1": "d1",
    ...
    "metric1": "m1",
    ...
  }, {
    ...
  }
]

XML

 <report>
  <record dimension1="d1" ... metric1="m1" ... />
  ...
</report

Para los formatos XML y JSON, el orden de los campos (dimensiones y métricas) dentro de un registro no está especificado, pero es coherente (el orden será el mismo en todos los registros). Sin embargo, los clientes no deben depender de ningún orden en particular de los campos de un registro.

El vínculo de recurso (la base "self" en JSON y el atributo de recurso "href" en XML) contiene la ruta actual y la cadena de consulta utilizada para el informe en línea. La cadena de consulta revelará todos los parámetros implícitos y explícitos, de modo que la carga útil señalará explícitamente el intervalo de tiempo utilizado, los filtros implícitos (si los hay), etc. El resto de los vínculos dentro del recurso contienen todos los segmentos disponibles que se pueden seguir para explorar en profundidad los datos actuales. También se proporciona un vínculo para el resumen y señalará la ruta principal (si la hay). El valor href de los vínculos de exploración o resumen solo contiene la ruta de acceso a la dirección URL (no incluye la cadena de consulta, por lo que el cliente debe agregarla si es necesario). Tenga en cuenta que no todos los parámetros de cadena de consulta utilizados (o implícitos) por el recurso actual serán aplicables para los vínculos de "resumen" o "desglose" (por ejemplo, es posible que los filtros no se apliquen a los subrecursos o superrecursos).

Ejemplo (suponiendo que tenemos una sola métrica llamada clients y que hay una agregación previa para year/month/day/...):

   <resource href="/esm/v3/year/month?start=2024-07-20T00:00:00&end=2024-08-20T14:35:21">
   <links>
   <link rel="roll-up" href="/esm/v3/year"/>
   <link rel="drill-down" href="/esm/v3/year/month/day"/>
   </links>
   <report>
   <record month="6" year="2024" clients="205"/>
   <record month="7" year="2024" clients="466"/>
   </report>
   </resource>

CSV

En el formato de datos CSV, no se proporcionarán vínculos ni otros metadatos en línea (excepto la fila de encabezado); en su lugar, los metadatos de selección se proporcionarán en el nombre del archivo, que seguirá este patrón:

    esm__<start-date>_<end-date>_<filter-values,...>.csv

El CSV contendrá una fila de encabezado y, a continuación, los datos del informe como filas posteriores. La fila de encabezado contendrá todas las dimensiones seguidas de todas las métricas. El orden de los datos del informe se reflejará en el orden de las dimensiones. Por lo tanto, si los datos se ordenan por D1 y después por D2, el encabezado CSV tendrá el siguiente aspecto: D1, D2, ...metrics....

El orden de los campos en la fila de encabezado reflejará el orden de los datos de tabla.

Ejemplo: https://mgmt.auth.adobe.com/esm/v3/year/month.csv producirá un archivo de nombre report__2024-07-20_2024-08-20_1000.csv con el siguiente contenido:

Actualización de datos data-freshness

Las respuestas HTTP correctas contienen un encabezado Last-Modified que indica la hora en la que se actualizó por última vez el informe del cuerpo. La falta de un encabezado Última modificación indica que los datos del informe se calculan en tiempo real.

Por lo general, los datos granulados se actualizarán con menos frecuencia que los datos granulados (por ejemplo, los valores por minuto o por hora pueden estar más actualizados que los valores diarios, especialmente para las métricas que no se pueden calcular en función de granularidades más pequeñas, como los recuentos únicos).

Compresión GZIP gzip-compression

Adobe recomienda habilitar la compatibilidad con gzip en los clientes que recuperen informes de ESM. Al hacerlo, se reducirá en gran medida el tamaño de la respuesta, lo que a su vez reduce el tiempo de respuesta. (El índice de compresión de los datos de ESM está en el rango de 20 a 30).

Para habilitar la compresión gzip en su cliente, establezca el encabezado Accept-Encoding: de la siguiente manera: