API zur Überwachung von Entitätsdiensten entitlement-service-monitoring-api
API-Übersicht api-overview
Entitlement Service Monitoring (ESM) wird als WOLAP-Projekt (Web-based Online Analytical Processing) implementiert. ESM ist eine generische Web-API für Geschäftsberichte, die von einem Data Warehouse unterstützt wird. Es dient als HTTP-Abfragesprache, die die Ausführung typischer OLAP-Vorgänge in RESTfull ermöglicht.
Die ESM-API bietet eine hierarchische Ansicht der zugrunde liegenden OLAP-Cubes. Jede Ressource (Dimension in der Dimensionshierarchie, die als URL-Pfadsegment zugeordnet ist) generiert Berichte mit (aggregierten) Metriken für die aktuelle Auswahl. Jede Ressource verweist auf ihre übergeordnete Ressource (für Datenaggregationen) und ihre Unterressourcen (für Drilldown). Slicing und Dicing werden über Abfragezeichenfolgenparameter erreicht, die Dimensionen an bestimmte Werte oder Bereiche anhängen.
Die REST-API stellt die verfügbaren Daten innerhalb eines in der Anfrage angegebenen Zeitintervalls bereit (wobei auf die Standardwerte zurückgegriffen wird, wenn keine Werte angegeben sind). Dies hängt vom Dimensionspfad, den bereitgestellten Filtern und ausgewählten Metriken ab. Der Zeitraum wird nicht für Berichte angewendet, die keine Zeitdimensionen enthalten (Jahr, Monat, Tag, Stunde, Minute, Sekunde).
Der Stammpfad der Endpunkt-URL gibt die aggregierten Gesamtmetriken innerhalb eines einzelnen Datensatzes zusammen mit den Links zu den verfügbaren Drilldown-Optionen zurück. Die API-Version wird als nachstehendes Segment des Endpunkt-URI-Pfads zugeordnet. Beispiel: https://mgmt.auth.adobe.com/*v2*
bedeutet, dass die Clients auf WOLAP Version 2 zugreifen.
Die verfügbaren URL-Pfade können über die in der Antwort enthaltenen Links gefunden werden. Gültige URL-Pfade werden gespeichert, um einen Pfad innerhalb der zugrunde liegenden Drilldown-Struktur zuzuordnen, der aggregierte (vorab erstellte) Metriken enthält. Ein Pfad im Formular /dimension1/dimension2/dimension3
spiegelt eine Voraggregation dieser drei Dimensionen wider (entspricht einer SQL clause GROUP
BY dimension1
, dimension2
, dimension3
). Wenn eine solche Voraggregation nicht vorhanden ist und das System sie nicht sofort berechnen kann, gibt die API eine Antwort "404 Not Found"zurück.
Drilldown-Struktur drill-down-tree
Die folgenden Drilldown-Bäume veranschaulichen die in ESM 2.0 verfügbaren Dimensionen (Ressourcen) für Programmierer und MVPDs.
Dimensionen für Programmierer progr-dimensions
Tag
Stunde
Minute
Für MVPDs verfügbare Dimensionen mvpd-dimensions
Ein GET zum API-Endpunkt https://mgmt.auth.adobe.com/v2
gibt eine Darstellung zurück, die Folgendes enthält:
-
Links zu den verfügbaren Root-Drilldown-Pfaden:
-
<link rel="drill-down" href="/v2/dimensionA"/>
-
<link rel="drill-down" href="/v2/dimensionB"/>
-
-
Eine Zusammenfassung (aggregierte Werte) für alle Metriken (standardmäßig
-Intervall, da keine Abfragezeichenfolgenparameter angegeben sind, siehe unten).
Folgen Sie einem Drilldown-Pfad (Schritt für Schritt):/dimensionA/year/month/day/dimensionX
ruft Folgendes ab
Antwort:
-
Links zu den Drilldown-Optionen "
dimensionY
"und "dimensionZ
" -
Ein Bericht mit täglichen Aggregaten für jeden Wert von
dimensionX
Filter
Mit Ausnahme der Datums-/Uhrzeitdimensionen kann jede für die aktuelle Projektion (Dimensionspfad) verfügbare Dimension anhand ihres Namens als Abfragezeichenfolgenparameter gefiltert werden.
Die folgenden Filteroptionen sind verfügbar:
-
Entspricht Filtern wird bereitgestellt, indem der Dimensionsname in der Abfragezeichenfolge auf einen bestimmten Wert gesetzt wird.
-
IN -Filter können angegeben werden, indem der Parameter "dimension-name"mehrmals mit verschiedenen Werten hinzugefügt wird: dimension=value1&dimension=value2
-
Nicht gleich Filter müssen den '!' verwenden Symbol hinter dem Dimensionsnamen, das zu "!"führt.=' "operator": dimension!=value
-
NOT IN -Filter erfordern den '!=''-Operator, der mehrmals verwendet wird, einmal für jeden Wert im Satz: Dimension!=value1&dimension!=value2&…
Außerdem werden die Dimensionsnamen in der Abfragezeichenfolge besonders verwendet: Wenn der Dimensionsname als Abfragezeichenfolgenparameter ohne Wert verwendet wird, weist dies die API an, eine Projektion zurückzugeben, die diese Dimension im Bericht enthält.
Beispiel-ESM-Abfragen
GROUP BY dimension1, dimension2, dimension3
GROUP BY dimension1, dimension2, dimension3
, aber es gibt einen Pfad: /dimension1/dimension2/dimension3
/dimension1?dimension3
date/time
-Dimensionen. Die einzige Möglichkeit, date/time
-Dimensionen zu filtern, besteht darin, die Abfragezeichenfolgenparameter start
und end
(siehe unten) auf die erforderlichen Werte festzulegen.Die folgenden Abfragezeichenfolgenparameter haben reservierte Bedeutungen für die API (und können daher nicht als Dimensionsnamen verwendet werden, sonst ist keine Filterung für eine solche Dimension möglich).
ESM API-reservierte Abfragezeichenfolgenparameter
Die einzige verfügbare HTTP-Methode ist derzeit GET. Unterstützung für OPTIONS /
HEAD-Methoden können in zukünftigen Versionen bereitgestellt werden.
ESM-API-Statuscodes esm-api-status-codes
Dem Status "Ungültige Anfrage 400"wird ein erläuternder Text im Antworttext (Nur-/Text-Medientyp) hinzugefügt, der nützliche Informationen zum Client-Fehler liefert. Neben trivialen Szenarien wie ungültigen Datumsformaten oder Filtern, die auf nicht vorhandene Dimensionen angewendet werden, weicht das System auch die Beantwortung von Abfragen ab, bei denen ein massives Datenvolumen sofort zurückgegeben oder aggregiert werden muss.
Datenformate data-formats
Die Daten sind in den folgenden Formaten verfügbar:
- JSON (Standard)
- XML
- CSV
- HTML (zu Demozwecken)
Die folgenden Strategien für die Inhaltsverhandlung können von Kunden verwendet werden (der Vorrang wird durch die Position in der Liste gegeben - das erste Mal):
- Eine "Dateierweiterung", die an das letzte Segment des URL-Pfads angehängt wird, z. B.
/esm/v2/media-company/year/month/day.xml
. Wenn die URL eine Abfragezeichenfolge enthält, muss die Erweiterung vor dem Fragezeichen stehen:/esm/v2/media-company/year/month/day.csv?mvpd= SomeMVPD
- Ein Formatabfragezeichenfolgenparameter, z. B.
/esm/report?format=json
- Die standardmäßige HTTP-Accept-Kopfzeile, z. B.
Accept: application/xml
Sowohl die "Erweiterung"als auch der Abfrageparameter unterstützen die folgenden Werte:
- xml
- json
- csv
- html
Wenn von keiner der Strategien ein Medientyp angegeben wird, erzeugt die API standardmäßig JSON-Inhalte.
Hypertext Application Language hypertext-application-language
Bei JSON und XML wird die Payload als HAL kodiert, wie hier beschrieben: http://stateless.co/hal_specification.html.
Der tatsächliche Bericht (ein verschachteltes Tag/eine verschachtelte Eigenschaft namens "Bericht") besteht aus der tatsächlichen Liste der Datensätze, die alle ausgewählten/anwendbaren Dimensionen und Metriken mit ihren Werten enthalten, die wie folgt kodiert sind:
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 identisch). Clients sollten sich jedoch nicht auf eine bestimmte Reihenfolge der Felder in einem Datensatz verlassen.
Der Ressourcenlink (das "self"-rel in JSON und das "href"-Ressourcenattribut in XML) enthält den aktuellen Pfad und die Abfragezeichenfolge, die für den Inline-Bericht verwendet werden. Die Abfragezeichenfolge zeigt alle impliziten und expliziten Parameter an, sodass die Payload explizit auf das verwendete Zeitintervall, die impliziten Filter (falls vorhanden) usw. verweist. Der Rest der Links innerhalb der Ressource enthält alle verfügbaren Segmente, die verfolgt werden können, um einen Drilldown in den aktuellen Daten durchzuführen. Es wird auch ein Link für die Datenaggregation bereitgestellt, der auf den übergeordneten Pfad verweist (falls vorhanden). Der Wert href
für die Drilldown-/Rollup-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 von der aktuellen Ressource verwendeten (oder impliziten) Abfragezeichenfolgenparameter für "Datenaggregations"- oder "Drilldown"-Links gelten (z. B. gelten die Filter nicht für Unter- oder Super-Ressourcen).
Beispiel (vorausgesetzt, wir haben eine einzelne Metrik namens clients
und es gibt eine Voraggregation für year/month/day/...
):
- https://mgmt.auth.adobe.com/esm/v2/year/month.xml
<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>
-
https://mgmt.auth.adobe.com/esm/v2/year/month.json
code language-json { "_links" : { "self" : { "href" : "/esm/v2/year/month?start=2012-07-20T00:00:00&end=2012-08-20T14:35:21" }, "roll-up" : { "href" : "/esm/v2/year" }, "drill-down" : { "href" : "/esm/v2/year/month/day" } }, "report" : [ { "month" : "6", "year" : "2012", "clients" : "205" }, { "month" : "7", "year" : "2012", "clients" : "466" } ] }
CSV
Im CSV-Datenformat werden keine Links oder anderen Metadaten (mit Ausnahme der Kopfzeile) inline bereitgestellt. Stattdessen werden die Auswahlmetadaten im Dateinamen bereitgestellt, der diesem Muster folgt:
esm__<start-date>_<end-date>_<filter-values,...>.csv
Die CSV-Datei enthält eine Kopfzeile und dann 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 Daten nach D1
und dann nach D2
sortiert werden, sieht der CSV-Header daher wie folgt aus: D1, D2, ...metrics...
.
Die Reihenfolge der Felder in der Kopfzeile entspricht der Sortierreihenfolge der Tabellendaten.
Beispiel: https://mgmt.auth.adobe.com/v2/year/month.csv erstellt eine Datei mit dem Namen report__2012-07-20_2012-08-20_1000.csv
mit folgendem Inhalt:
Datenfreude data-freshness
Die erfolgreichen HTTP-Antworten enthalten einen Last-Modified
-Header, der den Zeitpunkt angibt, zu dem der Bericht im Textkörper zuletzt aktualisiert wurde. Das Fehlen einer Kopfzeile vom Typ Letzte Änderung zeigt an, dass die Berichtsdaten in Echtzeit berechnet werden.
Normalerweise werden grobkörnige Daten weniger häufig aktualisiert als fein abgestufte Daten (z. B. Minuswerte oder Stundenwerte), die aktueller als die täglichen Werte sein können, insbesondere für Metriken, die nicht anhand kleinerer Granularitäten berechnet werden können (z. B. eindeutige Werte).
Zukünftige Versionen von ESM können es Kunden ermöglichen, bedingte GETs auszuführen, indem sie die standardmäßige "If-Modified-Since"-Kopfzeile bereitstellen.
GZIP-Komprimierung gzip-compression
Adobe empfiehlt dringend, dass Sie die gzip-Unterstützung in Clients aktivieren, die ESM-Berichte abrufen. Dadurch wird die Größe der Antwort erheblich reduziert, was wiederum Ihre Reaktionszeit reduziert. (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 Kopfzeile Accept-Encoding:
wie folgt fest:
- Accept-Encoding: gzip, deflate