Dokumentation Adobe Pass Adobe Pass-Authentifizierung

API zur Überwachung von Entitätsdiensten entitlement-service-monitoring-api

Last update: Thu Jul 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Themen:
Authentication

NOTE

Der Inhalt dieser Seite dient nur Informationszwecken. Für die Verwendung dieser API ist eine aktuelle Lizenz von Adobe erforderlich. Eine unbefugte Anwendung ist nicht zulässig.

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.

NOTE

Die ESM-API ist nicht allgemein verfügbar. Wenden Sie sich bei Fragen zur Verfügbarkeit an Ihren Adobe-Support-Mitarbeiter.

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

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

URL

SQL-Äquivalent

/dimension1/dimension2/dimension3?dimension1=value1

SELECT * from projektion WHERE dimension1 = 'value1'
GROUP BY dimension1, dimension2, dimension3

/dimension1/dimension2/dimension3?dimension1=value1&dimension1=value2

SELECT * from projektion WHERE dimension1 IN ('value1', 'value2')
GROUP BY dimension1, dimension2, dimension3

/dimension1/dimension2/dimension3?dimension1!=value1

SELECT * from projektion WHERE dimension1 <> 'value1'

/dimension1/dimension2/dimension3?dimension1!=value1&dimension2!=value2

SELECT * from projektion WHERE dimension1 NOT IN ('value1', 'value2')

Angenommen, es gibt keinen direkten Pfad: /dimension1/dimension3
, aber es gibt einen Pfad: /dimension1/dimension2/dimension3

/dimension1?dimension3

AUSWÄHLEN * AUS ProjektionsGRUPPE NACH Dimension1, Dimension3

NOTE

Keine dieser Filtermethoden funktioniert für 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

Parameter

Optional

Beschreibung

Standardwert

Beispiel

access_token

Wenn der IMS OAuth-Schutz aktiviert ist, kann das IMS-Token entweder als standardmäßiges Authorization-Bearer-Token oder als Abfragezeichenfolgenparameter übergeben werden.

Keines

access_token=XXXXXX

dimension-name

Jeder Dimensionsname - entweder im aktuellen URL-Pfad oder in einem gültigen Unterpfad enthalten; der Wert wird als gleich Filter behandelt. Wenn kein Wert angegeben wird, erzwingt dies, dass die angegebene Dimension in die Ausgabe aufgenommen wird, auch wenn sie nicht enthalten ist oder an den aktuellen Pfad angrenzt

Keines

someDimension=someValue&someOtherDimension

end

Endzeit für den Bericht in Millisekunden

Aktuelle Zeit des Servers

end=2012-07-30

format

Wird für die Inhaltsverhandlung verwendet (mit demselben Effekt, aber geringerer Priorität als der Pfad "Erweiterung"- siehe unten).

Keine: Bei der Inhaltsverhandlung werden die anderen Strategien getestet

format=json

limit

Maximale Anzahl an zurückzugebenden Zeilen

Der vom Server im Self-Link gemeldete Standardwert, wenn in der Anfrage keine Begrenzung angegeben ist

limit=1500

Metriken

Kommagetrennte Liste der zurückzugebenden Metriknamen. Diese sollte zum Filtern einer Untergruppe der verfügbaren Metriken (um die Payload-Größe zu reduzieren) und auch zum Erzwingen der API verwendet werden, eine Projektion zurückzugeben, die die angeforderten Metriken enthält (und nicht die standardmäßige optimale Projektion).

Alle für die aktuelle Projektion verfügbaren Metriken werden zurückgegeben, falls dieser Parameter nicht angegeben wird.

metrics=m1,m2

start

Startzeit für den Bericht als ISO8601; der Server füllt den verbleibenden Teil aus, wenn nur ein Präfix angegeben wird: Beispielsweise führt start=2012 zu start=2012-01-01:00:00:00.

Vom Server in der Selbstverknüpfung gemeldet; der Server versucht, basierend auf der ausgewählten Zeitgranularität angemessene Standardwerte bereitzustellen.

start=2012-07-15

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

Status-Code

Reason Phrase

Beschreibung

200

Die Antwort enthält Links für "Datenaggregation"und "Drilldown"(falls zutreffend). Der Bericht wird als Attribut der Ressource gerendert: als verschachteltes Element/Eigenschaft "Bericht".

400

Ungültige Anfrage

Der Antworttext enthält eine Textmeldung, die erklärt, was mit der Anfrage nicht stimmt.

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.

401

Unerlaubt

Wird durch eine Anfrage ausgelöst, die nicht die richtigen OAuth-Header enthält, um den Benutzer zu authentifizieren

403

Verboten

Gibt an, dass die Anfrage im aktuellen Sicherheitskontext nicht zulässig ist. Dies geschieht, wenn der Benutzer authentifiziert ist, aber nicht auf die angeforderten Informationen zugreifen darf

404

Nicht gefunden

Tritt auf, wenn die Anfrage einen ungültigen URL-Pfad enthält. Dies sollte niemals vorkommen, wenn der Client den Links "Drilldown"/"Rollout" folgt, die mit 200 Antworten bereitgestellt werden

405

Methode nicht zulässig

Signalisiert, dass in der Anfrage eine nicht unterstützte Methode verwendet wurde. Obwohl derzeit nur die GET-Methode unterstützt wird, können zukünftige Versionen HEAD oder OPTIONS zulassen

406

Nicht akzeptabel

Signalisiert, dass ein nicht unterstützter Medientyp vom Client angefordert wurde

500

Interner Server-Fehler

"Das sollte niemals geschehen"

503

Dienst nicht verfügbar

Signalisiert einen Fehler innerhalb der Anwendung oder deren Abhängigkeiten

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

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" } ] }`

    {
      "_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:

Jahr

Monat

Kunden

2012

580

2012

231

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

recommendation-more-help

3f5e655c-af63-48cc-9769-2b6803cc5f4b