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

Présentation de l’API api-overview

Le contrôle du service de droits (ESM) est mis en oeuvre sous la forme d’un WOLAP (basé sur le Web). Traitement Analytics en ligne). 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.

L’API ESM fournit une vue hiérarchique des cubes OLAP sous-jacents. Chaque ressource (dimension dans la hiérarchie de dimension, mappée en tant que segment de chemin d’URL) génère des rapports avec (agrégé). mesures pour la sélection en cours. Chaque ressource pointe vers sa ressource parente (pour le cumul) et ses sous-ressources (pour l’analyse). Le découpage et la découpe s’effectuent par le biais de paramètres de chaîne de requête en épinglant 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 (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 de terminaison 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 en tant que segment de fin du chemin d’accès URI du point d’entrée. Par exemple : https://mgmt.auth.adobe.com/*v2* signifie que les clients auront accès à WOLAP version 2.

Les chemins d’URL disponibles sont détectables via des liens contenus dans la réponse. Les chemins d’URL valides sont conservés pour mapper un chemin d’accès dans l’arborescence déroulante sous-jacente qui contient des mesures agrégées (pré-). Un chemin dans le formulaire /dimension1/dimension2/dimension3 reflétera une pré-agrégation de ces trois dimensions (l’équivalent d’un SQL clause GROUP BY 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 Not Found.

Arborescence de défilement drill-down-tree

Les arborescences d’exploration suivantes illustrent les dimensions (ressources) disponibles dans ESM 2.0 pour [Programmeurs] (#esm_dimensions) et MVPD.

Dimensions disponibles pour les programmeurs progr-dimensions

Dimensions disponibles pour les MVPD mvpd-dimensions

Un GET au https://mgmt.auth.adobe.com/v2 Le point de terminaison de l’API renvoie une représentation contenant :

Suivez un chemin d’accès (étape par étape) :
/dimensionA/year/month/day/dimensionX récupère la réponse suivante :

Filtres

À l’exception des dimensions de 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 dimension est utilisé comme paramètre de chaîne de requête sans valeur, l’API aura pour instruction de renvoyer une projection incluant 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, sinon aucun filtrage ne serait possible pour une telle dimension).

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

La seule méthode HTTP actuellement disponible est GET. La prise en charge des OPTIONS/méthodes HEAD peut être fournie dans les versions ultérieures.

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 le poste dans la liste - premier élément) :

"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 de l’application hypertexte hypertext-application-language

Pour JSON et XML, la charge utile 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 d’enregistrements contenant toutes les dimensions et mesures sélectionnées/applicables avec leurs valeurs, codé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) dans 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 la ressource (le rel "self" dans JSON et l’attribut de ressource "href" dans XML) contient le chemin 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 charge utile indique explicitement l’intervalle de temps utilisé, les filtres implicites (le cas échéant), etc. Le reste des liens de la ressource contiendra tous les segments disponibles qui peuvent être suivis afin d’analyser en détail les données actives. Un lien de cumul est également fourni, qui pointe vers le chemin parent (le cas échéant). La variable href pour les liens d’analyse/de cumul contiennent uniquement le chemin d’URL (il n’inclut pas la chaîne de requête ; le client doit donc l’ajouter 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 qu’il existe une mesure unique appelée clients et il existe une pré-agrégation pour year/month/day/...) :

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

CSV

Dans le format de données CSV, aucun lien ou autre métadonnées (à l’exception de la ligne d’en-tête) ne sera fourni en ligne ; les métadonnées de sélection seront fournies dans le nom de fichier, selon le modèle suivant :

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

Le fichier CSV contient une ligne d’en-tête, puis les données du rapport sous forme de 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 se présente comme suit : 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/v2/year/month.csv produira un fichier nommé report__2012-07-20_2012-08-20_1000.csv avec le contenu suivant :

Actualisation des données data-freshness

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

En règle générale, les données de granularité grossière sont mises à jour moins fréquemment que les données d’granularité fine (par exemple, les valeurs par minute ou par heure peuvent être plus à jour que les valeurs quotidiennes, en particulier pour les mesures qui ne peuvent pas être calculées en fonction de granularités plus petites, comme les nombres uniques).

Les futures versions d’ESM peuvent permettre aux clients d’effectuer des GET conditionnels en fournissant l’en-tête "If-Modified-Since" standard.

Compression GZIP gzip-compression

Adobe recommande vivement d’activer la prise en charge de gzip dans les clients qui récupèrent les rapports ESM. Cela réduira 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 se situe entre 20 et 30.)

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