Berechtigungs-Service-Überwachungs-API entitlement-service-monitoring-api

API-Übersicht api-overview

Die Überwachung von Berechtigungen für Services (Entitlement Service Monitoring, ESM) wird als WOLAP-Projekt (Web-basierte Online-) implementiert. ESM ist eine generische Business-Reporting-Web-API, die von einem Data Warehouse unterstützt wird. Sie dient als HTTP-Abfragesprache, mit der typische OLAP-Vorgänge RESTful ausgeführt werden können.

Die ESM-API bietet eine hierarchische Ansicht der zugrunde liegenden OLAP-Cubes. Jede Ressource (Dimension in der Dimensionshierarchie, zugeordnet als URL-Pfadsegment) generiert Berichte mit (aggregierten) Metriken für die aktuelle Auswahl. Jede Ressource verweist auf ihre übergeordnete Ressource (für die Aufschlüsselung) und ihre Unterressourcen (für die Aufschlüsselung). Slicing und Dicing werden über Abfragezeichenfolgen-Parameter erreicht, die Dimensionen an bestimmte Werte oder Bereiche anheften.

Die REST-API stellt die verfügbaren Daten innerhalb eines in der Anfrage angegebenen Zeitintervalls (d. h. zurück auf die Standardwerte, wenn keine Werte angegeben wurden) bereit, und zwar entsprechend dem Dimensionspfad, den bereitgestellten Filtern und den ausgewählten Metriken. Der Zeitbereich wird nicht auf Berichte angewendet, die keine Zeitdimensionen enthalten (Jahr, Monat, Tag, Stunde, Minute, Sekunde).

Der Endpunkt-URL-Stammpfad gibt die gesamten aggregierten Metriken innerhalb eines einzigen Datensatzes zusammen mit den Links zu den verfügbaren Drilldown-Optionen zurück. Die API-Version wird als nachfolgendes Segment des Endpunkt-URI-Pfads zugeordnet. https://mgmt.auth.adobe.com/esm/v3 bedeutet beispielsweise, dass die Clients auf WOLAP Version 3 zugreifen.

Die verfügbaren URL-Pfade sind über in der Antwort enthaltene Links auffindbar. Gültige URL-Pfade werden gespeichert, um einen Pfad innerhalb der zugrunde liegenden Drilldown-Struktur zuzuordnen, der (vor-)aggregierte Metriken enthält. Ein Pfad in der /dimension1/dimension2/dimension3 spiegelt eine Voraggregation dieser drei Dimensionen wider (das Äquivalent eines SQL-clause GROUP NACH dimension1, dimension2, dimension3). Wenn eine solche Voraggregation nicht vorhanden ist und das System sie nicht spontan berechnen kann, gibt die API die Antwort „404 Nicht gefunden“ zurück.

Drilldown-Baum drill-down-tree

Die folgenden Drill-down-Bäume veranschaulichen die in ESM 3.0 verfügbaren Dimensionen (Ressourcen) für Programmierer und MVPD.

Für Programmierer verfügbare Dimensionen progr-dimensions

Tag

Stunde

Minute

Für MVPDs verfügbare Dimensionen mvpd-dimensions

Eine GET an den https://mgmt.auth.adobe.com/esm/v3-API-Endpunkt gibt eine Darstellung zurück, die Folgendes enthält:

Folgen eines Drilldown-Pfads (Schritt für Schritt):
/dimensionA/year/month/day/dimensionX ruft Folgendes ab
Antwort:

Filter

Mit Ausnahme der Datums-/Uhrzeitdimensionen können alle für die aktuelle Projektion verfügbaren Dimensionen (Dimensionspfad) gefiltert werden, indem ihr Name als Abfragezeichenfolgenparameter verwendet wird.

Die folgenden Filteroptionen sind verfügbar:

Es gibt auch eine besondere Verwendung für die Dimensionsnamen in der Abfragezeichenfolge: Wenn der Dimensionsname als Abfragezeichenfolgenparameter ohne Wert verwendet wird, wird die API angewiesen, eine Projektion zurückzugeben, die diese Dimension im Bericht enthält.

Beispiele für ESM-Abfragen

Die folgenden Abfragezeichenfolgenparameter haben reservierte Bedeutungen für die API (und können daher nicht als Dimensionsnamen verwendet werden, da ansonsten keine Filterung für eine solche Dimension möglich wäre).

ESM API reservierte Abfragezeichenfolgen-Parameter

Die einzige verfügbare HTTP-Methode ist derzeit GET.

ESM-API-Status-Codes esm-api-status-codes

Datenformate data-formats

Die Daten sind in den folgenden Formaten verfügbar:

Die folgenden Strategien zur Inhaltsaushandlung können von Clients verwendet werden (der Vorrang wird durch die Position in der Liste gegeben - erste Dinge):

Sowohl die Erweiterung als auch der Abfrageparameter unterstützen die folgenden Werte:

Wenn in einer der Strategien kein Medientyp angegeben ist, erstellt die API standardmäßig JSON-Inhalte.

Hypertext-Anwendungssprache hypertext-application-language

Für JSON und XML wird die Payload als HAL codiert, wie hier beschrieben: http://stateless.co/hal_specification.html.

Der eigentliche Bericht (ein verschachteltes Tag/eine verschachtelte Eigenschaft namens „Bericht„) besteht aus der tatsächlichen Liste von Datensätzen, die alle ausgewählten/anwendbaren Dimensionen und Metriken mit ihren Werten enthalten, und zwar wie folgt:

JSON

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

XML

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

Bei XML- und JSON-Formaten ist die Reihenfolge der Felder (Dimensionen und Metriken) in einem Datensatz nicht angegeben, aber konsistent (die Reihenfolge ist in allen Datensätzen gleich). Kunden sollten sich jedoch nicht auf eine bestimmte Reihenfolge der Felder innerhalb eines Datensatzes verlassen.

Der Ressourcen-Link (das „Selbst“-rel in JSON und das „href“-Ressourcenattribut in XML) enthält den aktuellen Pfad und die Abfragezeichenfolge, die für den Inline-Bericht verwendet wird. Die Abfragezeichenfolge enthüllt alle impliziten und expliziten Parameter, sodass die Payload explizit auf das verwendete Zeitintervall, die impliziten Filter (falls vorhanden) usw. hinweist. Der Rest der Links innerhalb der Ressource enthält alle verfügbaren Segmente, denen Sie folgen können, um eine Aufschlüsselung der aktuellen Daten durchzuführen. Ein Link für die Datenaggregation wird ebenfalls bereitgestellt und verweist auf den übergeordneten Pfad (falls vorhanden). Der href für die Drill-down-/Roll-up-Links enthält nur den URL-Pfad (er enthält nicht die Abfragezeichenfolge, daher muss dieser bei Bedarf vom Client angehängt werden). Beachten Sie, dass nicht alle der von der aktuellen Ressource verwendeten (oder implizierten) Abfragezeichenfolgenparameter für „Hochrechnungs“- oder „Drilldown“-Links gelten (die Filter können beispielsweise nicht auf Unter- oder Überressourcen angewendet werden).

Beispiel (vorausgesetzt, wir haben eine einzelne Metrik namens clients und es gibt eine Voraggregation für 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

Im CSV-Datenformat werden keine Links oder anderen Metadaten (mit Ausnahme der Kopfzeile) inline bereitgestellt. Stattdessen werden die Auswahl-Metadaten im Dateinamen bereitgestellt, der diesem Muster folgt:

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

Die CSV enthält eine Kopfzeile und die Berichtsdaten als nachfolgende Zeilen. Die Kopfzeile enthält alle Dimensionen gefolgt von allen Metriken. Die Sortierreihenfolge der Berichtsdaten wird in der Reihenfolge der Dimensionen angezeigt. Wenn die Daten also nach D1 und dann nach D2 sortiert werden, sieht die CSV-Kopfzeile wie folgt aus: D1, D2, ...metrics....

Die Reihenfolge der Felder in der Kopfzeile entspricht der Sortierreihenfolge der Tabellendaten.

Beispiel: https://mgmt.auth.adobe.com/esm/v3/year/month.csv erstellt eine Datei mit dem Namen report__2024-07-20_2024-08-20_1000.csv mit folgendem Inhalt:

Aktualität der Daten data-freshness

Die erfolgreichen HTTP-Antworten enthalten eine Last-Modified-Kopfzeile, die den Zeitpunkt angibt, zu dem der Bericht im Hauptteil zuletzt aktualisiert wurde. Das Fehlen einer Kopfzeile „Zuletzt geändert“ zeigt an, dass die Berichtsdaten in Echtzeit berechnet werden.

Normalerweise werden grobkörnige Daten seltener aktualisiert als feinkörnige Daten (z. B. könnten minutengenaue Werte oder stündliche Werte aktueller sein als die täglichen Werte, insbesondere bei Metriken, die nicht auf Grundlage kleinerer Granularitäten berechnet werden können, z. B. eindeutige Zahlen).

GZIP-Komprimierung gzip-compression

Adobe empfiehlt dringend, die gzip-Unterstützung in Clients zu aktivieren, die ESM-Berichte abrufen. Dadurch wird die Größe der Antwort erheblich reduziert, was wiederum die Reaktionszeit verkürzt. (Das Komprimierungsverhältnis für ESM-Daten liegt im Bereich von 20-30.)

Um die Gzip-Komprimierung in Ihrem Client zu aktivieren, legen Sie die Accept-Encoding:-Kopfzeile wie folgt fest: