Entitlement Service Monitoring API entitlement-service-monitoring-api

API-overzicht api-overview

De Controle van de Dienst van het recht (ESM) wordt uitgevoerd als WOLAP (Web-based Online Analytische Verwerking) project. ESM is een generisch zaken-meldend Web API die door een gegevenspakhuis wordt gesteund. Het doet dienst als de vraagtaal van HTTP die typische verrichtingen toelaat OLAP om RESTfully worden uitgevoerd.

ESM API verstrekt een hiërarchische mening van de onderliggende kubussen OLAP. Elk middel ( afmetingin de afmetinghiërarchie, in kaart gebracht als segment van de weg URL) produceert rapporten met (bijeengevoegde) metriekvoor de huidige selectie. Elke bron wijst naar de bovenliggende bron (voor roll-up) en de bijbehorende subbronnen (voor boor-down). Segmenteren en dicing worden bereikt via parameters van queryreeksen die de afmetingen vastzetten op specifieke waarden of bereiken.

De REST API verstrekt de beschikbare gegevens binnen een tijdsinterval dat in het verzoek wordt gespecificeerd (die terug naar standaardwaarden als niets wordt verstrekt), volgens de afmetingspad, verstrekte filters, en geselecteerde metriek. Het tijdbereik wordt niet toegepast op rapporten die geen tijdafmetingen bevatten (jaar, maand, dag, uur, minuut, seconde).

Het eindpunt URL wortelweg zal de algemene bijeengevoegde metriek binnen één enkel verslag, samen met de verbindingen aan de beschikbare boor-down opties terugkeren. De API-versie wordt toegewezen als het volgende segment van het URI-eindpuntpad. https://mgmt.auth.adobe.com/esm/v3 betekent bijvoorbeeld dat de clients toegang hebben tot WOLAP versie 3.

De beschikbare URL-paden kunnen worden gevonden via koppelingen in het antwoord. Geldige URL-paden worden vastgehouden om een pad in de onderliggende boor-down structuur toe te wijzen dat (pre)geaggregeerde metriek bevat. Een pad in de vorm /dimension1/dimension2/dimension3 geeft een pre-aggregatie van deze drie dimensies weer (het equivalent van een SQL clause GROUP BY dimension1 , dimension2 , dimension3 ). Als een dergelijke pre-samenvoeging niet bestaat en het systeem het niet kan onmiddellijk berekenen, zal API een 404 niet Gevonden reactie terugkeren.

Boor-down Boom drill-down-tree

De volgende boor-benedenbomen illustreren de afmetingen (middelen) beschikbaar in ESM 3.0 voor Programmersen MVPDs.

Dimensionen beschikbaar voor programmeurs progr-dimensions

Dag

Uur

Minute

Dimensionen die beschikbaar zijn voor MVPD's mvpd-dimensions

Een GET naar het API-eindpunt van https://mgmt.auth.adobe.com/esm/v3 retourneert een representatie met:

Na een boor-down weg (stap voor stap):
/dimensionA/year/month/day/dimensionX haalt het volgende op
reactie:

Filters

Met uitzondering van de datum-/tijddimensies, kan elke dimensie die beschikbaar is voor de huidige projectie (dimensiepad) worden gefilterd door de naam ervan als parameter voor queryreeksen te gebruiken.

De volgende filteropties zijn beschikbaar:

Er is ook een speciaal gebruik voor de afmetingsnamen in het vraagkoord: Als de afmetingsnaam als parameter van het vraagkoord zonder waarde wordt gebruikt, zal dit API instrueren om een projectie terug te keren die die afmeting in het rapport omvat.

Voorbeeld-ESM-query's

De volgende parameters van het vraagkoord hebben gereserveerde betekenis voor API (en daarom kunnen zij niet als afmetingsnamen worden gebruikt, of anders geen het filtreren zou voor zulk een afmeting mogelijk zijn).

Door ESM API gereserveerde parameters voor queryreeks

De enige beschikbare HTTP-methode die momenteel beschikbaar is, is GET.

ESM API-statuscodes esm-api-status-codes

Gegevensindelingen data-formats

De gegevens zijn beschikbaar in de volgende indelingen:

De volgende strategieën voor inhoudonderhandeling kunnen door klanten worden gebruikt (de prioriteit wordt gegeven door de positie in de lijst - eerst dingen):

Zowel ondersteunen de parameter "extension" als de parameter query de volgende waarden:

Als geen mediatype wordt opgegeven door een van de strategieën, produceert de API standaard JSON-inhoud.

Toepassingstaal Hypertext hypertext-application-language

Voor JSON en XML wordt de payload gecodeerd als HAL, zoals hier beschreven: http://stateless.co/hal_specification.html .

Het werkelijke rapport (een geneste tag/eigenschap genaamd "report") bestaat uit de feitelijke lijst met records die alle geselecteerde/toepasselijke afmetingen en meetgegevens met hun waarden bevatten, en die als volgt zijn gecodeerd:

JSON

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

XML

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

Voor XML- en JSON-indelingen is de volgorde van de velden (afmetingen en metriek) in een record niet opgegeven, maar consistent (de volgorde is in alle records hetzelfde). Klanten mogen echter niet vertrouwen op een bepaalde volgorde van de velden in een record.

De middelverbinding (het "zelf"rel in JSON en het "href"middelattribuut in XML) bevat de huidige weg en het vraagkoord dat voor het gealigneerde rapport wordt gebruikt. De vraagkoord zal alle impliciete en expliciete parameters openbaren, zodat de nuttige lading uitdrukkelijk het gebruikte tijdinterval, de impliciete filters (als om het even welk) zal wijzen, etc. De rest verbindingen binnen het middel zullen alle beschikbare segmenten bevatten die kunnen worden gevolgd om neer in de huidige gegevens te boren. Er wordt ook een koppeling voor roll-up toegevoegd die naar het bovenliggende pad verwijst (indien aanwezig). De href -waarde voor de boor-down/roll-up koppelingen bevat alleen het URL-pad (de queryreeks is niet inbegrepen, dus deze moet zo nodig door de client worden toegevoegd). Merk op dat niet alle parameters van het vraagkoord die (of geïmpliceerd) door het huidige middel worden gebruikt voor "roll-up"of "boor-down"verbindingen van toepassing zullen zijn (bijvoorbeeld, kunnen de filters niet op sub of super-middelen van toepassing zijn).

Voorbeeld (ervan uitgaande dat er één metrische waarde is met de naam clients en dat er een vooraggregatie voor year/month/day/... is):

   <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

In de CSV-gegevensindeling worden geen koppelingen of andere metagegevens (behalve de koptekstrij) inline verschaft. In plaats daarvan worden de metagegevens van de selectie opgenomen in de bestandsnaam, die als volgt wordt weergegeven:

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

CSV zal een kopbalrij en dan de rapportgegevens als verdere rijen bevatten. De koptekstrij bevat alle afmetingen gevolgd door alle meetgegevens. De soortorde van de rapportgegevens zal in de orde van de dimensies worden weerspiegeld. Als de gegevens daarom worden gesorteerd op D1 en vervolgens op D2 , ziet de CSV-header er als volgt uit: D1, D2, ...metrics... .

De volgorde van de velden in de koptekstrij komt overeen met de sorteervolgorde van de tabelgegevens.

Voorbeeld: https://mgmt.auth.adobe.com/esm/v3/year/month.csv maakt een bestand met de naam report__2024-07-20_2024-08-20_1000.csv met de volgende inhoud:

Gegevensversheid data-freshness

De geslaagde HTTP-reacties bevatten een Last-Modified -header die aangeeft op welk tijdstip het rapport in de hoofdtekst voor het laatst is bijgewerkt. Het gebrek aan een Laatst-Gewijzigde kopbal wijst erop dat de rapportgegevens in real time worden gegevens verwerkt.

Gewoonlijk worden grove korrelige gegevens minder vaak bijgewerkt dan fijnkorrelige gegevens (bijv. waarden per minuut of uurwaarden kunnen actueler zijn dan de dagelijkse waarden, vooral voor metriek die niet kan worden berekend op basis van kleinere granulariteiten, zoals unieke tellingen).

GZIP-compressie gzip-compression

De Adobe adviseert sterk dat u gzip steun in cliënten toelaat die ESM- rapporten halen. Dit zal de responsgrootte aanzienlijk verminderen, wat op zijn beurt de responstijd vermindert. (De compressieverhouding voor ESM-gegevens ligt in het bereik 20-30.)

Als u gzip-compressie wilt inschakelen in uw client, stelt u de header Accept-Encoding: als volgt in: