API de surveillance du service de droit entitlement-service-monitoring-api

Présentation de l’API api-overview

La surveillance du service de droit (ESM) est mise en œuvre en tant que projet WOLAP (Web-based Online Analytical Processing). ESM est une API Web de création de rapports d’entreprise générique soutenue par un entrepôt de données. Il agit comme un langage de requête HTTP qui permet d’effectuer entièrement des opérations OLAP standard avec REST.

L’API ESM offre une vue hiérarchique des cubes OLAP sous-jacents. Chaque ressource (dimension de la hiérarchie des dimensions, mappée en tant que segment de chemin d’URL) génère des rapports avec des mesures (agrégées) pour la sélection en cours. Chaque ressource pointe vers sa ressource parent (pour le cumul) et ses sous-ressources (pour l’exploration vers le bas). Le découpage et la division sont réalisés au moyen de paramètres de chaîne de requête qui épinglent des dimensions à des valeurs ou des plages spécifiques.

L’API REST fournit les données disponibles dans un intervalle de temps spécifié dans la requête (en revenant aux valeurs par défaut si aucune valeur n’est fournie), en fonction du chemin d’accès à la dimension, des filtres fournis et des mesures sélectionnées. La période ne sera pas appliquée aux rapports qui ne contiennent pas de dimensions temporelles (année, mois, jour, heure, minute, seconde).

Le chemin d’accès racine de l’URL du point d’entrée renvoie les mesures agrégées globales dans un seul enregistrement, ainsi que les liens vers les options d’analyse disponibles. La version de l’API est mappée comme segment de fin du chemin d’URI du point d’entrée. Par exemple, https://mgmt.auth.adobe.com/esm/v3 signifie que les clients accéderont à WOLAP version 3.

Les chemins d’URL disponibles sont détectables via les liens contenus dans la réponse. Des chemins d’URL valides sont conservés pour mapper un chemin dans l’arborescence d’exploration en profondeur sous-jacente qui contient des mesures (pré) agrégées. Un chemin d’accès dans l’/dimension1/dimension2/dimension3 de formulaire reflétera une pré-agrégation de ces trois dimensions (l’équivalent d’un clause GROUP SQL PAR dimension1, dimension2, dimension3). Si une telle pré-agrégation n’existe pas et que le système ne peut pas la calculer à la volée, l’API renvoie une réponse 404 Introuvable.

Arborescence déroulante drill-down-tree

Les arborescences détaillées suivantes illustrent les dimensions (ressources) disponibles dans ESM 3.0 pour Programmeurs et MVPD.

Dimensions disponibles pour les programmeurs progr-dimensions

Jour

Heure

Minute

Dimensions disponibles pour les MVPD mvpd-dimensions

Un GET au point d’entrée de l’API https://mgmt.auth.adobe.com/esm/v3 renvoie une représentation contenant les éléments suivants :

En suivant un chemin d’exploration (étape par étape) :
/dimensionA/year/month/day/dimensionX récupère les éléments suivants :
réponse :

Filtres

À l’exception des dimensions date/heure, toute dimension disponible pour la projection actuelle (chemin de dimension) peut être filtrée en utilisant son nom comme paramètre de chaîne de requête.

Les options de filtrage disponibles sont les suivantes :

Il existe également une utilisation spéciale pour les noms de dimension dans la chaîne de requête : si le nom de la dimension est utilisé comme paramètre de chaîne de requête sans valeur, l’API est chargée de renvoyer une projection qui inclut cette dimension dans le rapport.

Exemples de requêtes ESM

Les paramètres de chaîne de requête suivants ont une signification réservée pour l’API (ils ne peuvent donc pas être utilisés comme noms de dimension, ou aucun filtrage ne serait possible pour une telle dimension).

Paramètres de chaîne de requête réservés à l’API ESM

Actuellement, la seule méthode HTTP disponible est GET.

Codes d’état de l’API ESM esm-api-status-codes

Formats de données data-formats

Les données sont disponibles dans les formats suivants :

Les stratégies de négociation de contenu suivantes peuvent être utilisées par les clients (la priorité est donnée par la position dans la liste - premiers éléments) :

L’« extension » et le paramètre de requête prennent en charge les valeurs suivantes :

Si aucun type de média n’est spécifié par l’une des stratégies, l’API génère du contenu JSON par défaut.

Langage D'Application Hypertexte hypertext-application-language

Pour JSON et XML, la payload sera codée en tant que HAL, comme décrit ici : http://stateless.co/hal_specification.html.

Le rapport réel (une balise/propriété imbriquée appelée « rapport ») se compose de la liste réelle des enregistrements contenant toutes les dimensions et mesures sélectionnées/applicables avec leurs valeurs, encodées comme suit :

JSON

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

XML

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

Pour les formats XML et JSON, l’ordre des champs (dimensions et mesures) au sein d’un enregistrement n’est pas spécifié, mais cohérent (l’ordre sera le même dans tous les enregistrements). Toutefois, les clients ne doivent pas se fier à un ordre particulier des champs dans un enregistrement.

Le lien de ressource (le lien de ressource « self » dans le JSON et l’attribut de ressource « href » dans le XML) contient le chemin d’accès actuel et la chaîne de requête utilisée pour le rapport intégré. La chaîne de requête affiche tous les paramètres implicites et explicites, de sorte que la payload indique explicitement l’intervalle de temps utilisé, les filtres implicites (le cas échéant), etc. Le reste des liens de la ressource contient tous les segments disponibles qui peuvent être suivis afin d’analyser en profondeur les données actives. Un lien pour le cumul est également fourni, et il pointe vers le chemin d’accès parent (le cas échéant). La valeur href pour les liens d’exploration/de cumul contient uniquement le chemin de l’URL (elle n’inclut pas la chaîne de requête, elle doit donc être ajoutée par le client si nécessaire). Notez que tous les paramètres de chaîne de requête utilisés (ou implicites) par la ressource actuelle ne s’appliqueront pas aux liens « de cumul » ou « d’exploration » (par exemple, les filtres peuvent ne pas s’appliquer aux sous-ressources ou aux super-ressources).

Exemple (en supposant que nous ayons une mesure unique appelée clients et qu’il existe une pré-agrégation pour 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

Au format de données CSV, aucun lien ni aucune autre métadonnée (à l’exception de la ligne d’en-tête) ne sont fournis en ligne ; à la place, les métadonnées de sélection sont fournies dans le nom du fichier, qui suit ce modèle :

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

Le fichier CSV contient une ligne d’en-tête, puis les données du rapport en tant que lignes suivantes. La ligne d’en-tête contient toutes les dimensions suivies de toutes les mesures. L’ordre de tri des données du rapport est reflété dans l’ordre des dimensions. Par conséquent, si les données sont triées par D1, puis par D2, l’en-tête CSV ressemble à ceci : D1, D2, ...metrics....

L’ordre des champs dans la ligne d’en-tête reflète l’ordre de tri des données du tableau.

Exemple : https://mgmt.auth.adobe.com/esm/v3/year/month.csv génère un fichier nommé report__2024-07-20_2024-08-20_1000.csv avec le contenu suivant :

Actualisation des données data-freshness

Les réponses HTTP réussies contiennent un en-tête Last-Modified qui indique l’heure de la dernière mise à jour du rapport dans le corps. L’absence d’en-tête Dernière modification indique que les données du rapport sont calculées en temps réel.

En règle générale, les données grossières sont mises à jour moins fréquemment que les données fines (par exemple, les valeurs par minute, ou les valeurs horaires, peuvent être plus récentes que les valeurs quotidiennes, en particulier pour les mesures qui ne peuvent pas être calculées sur la base de granularités plus petites, comme des décomptes uniques).

Compression GZIP gzip-compression

Adobe recommande vivement d’activer la prise en charge gzip sur les clients qui récupèrent des rapports ESM. Cela permet de réduire considérablement la taille de la réponse, ce qui réduit votre temps de réponse. (Le taux de compression des données ESM est compris entre 20 et 30.)

Pour activer la compression GZIP dans votre client, définissez l’en-tête Accept-Encoding: comme suit :