API för tillståndsövervaknings-API entitlement-service-monitoring-api

API-översikt api-overview

ESM (Entitlement Service Monitoring) implementeras som ett WOLAP-projekt (webbaserad Online Analytical Processing). ESM är ett generiskt webb-API för affärsrapportering som backas upp av ett datalager. Det fungerar som ett HTTP-frågespråk som gör att vanliga OLAP-åtgärder kan utföras RESTfully.

ESM-API:t ger en hierarkisk vy över de underliggande OLAP-kubarna. Varje resurs (dimension i dimensionshierarkin, mappad som ett URL-sökvägssegment) genererar rapporter med (aggregerade) mått för den aktuella markeringen. Varje resurs pekar på sin överordnade resurs (för sammanslagning) och dess underresurser (för fördjupning). Segmentering och segmentering uppnås med frågesträngsparametrar som fäster dimensioner till specifika värden eller intervall.

REST API tillhandahåller tillgängliga data inom ett tidsintervall som anges i begäran (som faller tillbaka till standardvärdena om inget anges), enligt dimensionssökvägen, tillhandahållna filter och valda mätvärden. Tidsintervallet används inte för rapporter som inte innehåller tidsdimensioner (år, månad, dag, timme, minut, sekund).

Slutpunkts-URL-rotsökvägen returnerar sammanställda mått inom en enda post, tillsammans med länkarna till de tillgängliga detaljalternativen. API-versionen mappas som det avslutande segmentet i URI-sökvägen för slutpunkten. https://mgmt.auth.adobe.com/esm/v3 betyder till exempel att klienterna kommer åt WOLAP version 3.

De tillgängliga URL-sökvägarna kan identifieras via länkar i svaret. Giltiga URL-sökvägar hålls för att mappa en sökväg i det underliggande fördjupningsträdet som innehåller (pre-) aggregerade mått. En sökväg i formatet /dimension1/dimension2/dimension3 reflekterar en föraggning av dessa tre dimensioner (motsvarigheten till en SQL clause GROUP BY dimension1, dimension2, dimension3). Om det inte finns någon sådan föraggning och systemet inte kan beräkna den direkt, returnerar API:t ett 404-svar som inte hittades.

Detaljträd drill-down-tree

Följande detaljerade träd visar de dimensioner (resurser) som finns i ESM 3.0 för Programmerare och MVPD.

Dimensioner för programmerare progr-dimensions

Dag

Timme

Minut

Dimensioner tillgängliga för distributörer av videoprogrammeringstjänster mvpd-dimensions

En GET till API-slutpunkten https://mgmt.auth.adobe.com/esm/v3 returnerar en representation som innehåller:

Så här visar du en detaljerad sökväg (steg för steg):
/dimensionA/year/month/day/dimensionX hämtar följande
svar:

Filter

Förutom datum-/tidsdimensionerna kan alla dimensioner som är tillgängliga för den aktuella projektionen (dimensionssökväg) filtreras genom att använda dess namn som en frågesträngsparameter.

Följande filtreringsalternativ är tillgängliga:

Det finns också en särskild användning för dimensionsnamnen i frågesträngen: Om dimensionsnamnet används som en frågesträngsparameter utan värde instruerar detta API att returnera en projektion som innehåller den dimensionen i rapporten.

Exempel på ESM-frågor

Följande frågesträngsparametrar har reserverade betydelser för API (och kan därför inte användas som dimensionsnamn, annars går det inte att filtrera en sådan dimension).

ESM API Reserved Query String Parameters

Den enda tillgängliga HTTP-metoden är GET.

ESM API-statuskoder esm-api-status-codes

Dataformat data-formats

Data finns i följande format:

Följande strategier för innehållsförhandling kan användas av klienter (prioriteten ges av positionen i listan - första saker först):

Både "extension" och frågeparametern stöder följande värden:

Om ingen medietyp har angetts i någon av strategierna skapar API-gränssnittet JSON-innehåll som standard.

Hypertext Application Language hypertext-application-language

För JSON och XML kodas nyttolasten som HAL, vilket beskrivs här: http://stateless.co/hal_specification.html.

Den faktiska rapporten (en kapslad tagg/egenskap som kallas"rapport") består av den faktiska listan med poster som innehåller alla valda/tillämpliga mått och mått med deras värden, kodade enligt följande:

JSON

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

XML

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

För XML- och JSON-format är fältordningen (mått och mått) i en post ospecificerad - men konsekvent (ordningen är densamma i alla poster). Klienter bör dock inte förlita sig på någon särskild ordning för fälten i en post.

Resurslänken (self-rel i JSON och href-resursattributet i XML) innehåller den aktuella sökvägen och frågesträngen som används för den infogade rapporten. Frågesträngen visar alla implicita och explicita parametrar så att nyttolasten uttryckligen anger vilket tidsintervall som används, eventuella implicita filter och så vidare. Resten av länkarna i resursen innehåller alla tillgängliga segment som kan följas för att detaljgranska aktuella data. En länk för sammanslagning kommer också att anges och den kommer att peka på den överordnade sökvägen (om sådan finns). Värdet href för länkarna för detaljnivå/rollup innehåller bara URL-sökvägen (den innehåller inte frågesträngen, så klienten måste lägga till den om det behövs). Observera att inte alla frågesträngsparametrar som används (eller är underförstådda) av den aktuella resursen kan användas för länkar av typen "roll-up" eller "drill-down" (filtren kan till exempel inte gälla för underresurser eller superresurser).

Exempel (förutsatt att vi har ett enskilt mått med namnet clients och att det finns en föraggning 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

I CSV-dataformatet kommer inga länkar eller andra metadata (förutom rubrikraden) att anges. I stället kommer urvalsmetadata att anges i filnamnet, som kommer att följa detta mönster:

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

CSV-filen innehåller en rubrikrad och sedan rapportdata som efterföljande rader. Rubrikraden innehåller alla mått följt av alla mått. Sorteringsordningen för rapportdata återspeglas i dimensionernas ordning. Om data sorteras av D1 och sedan av D2 ser CSV-huvudet därför ut så här: D1, D2, ...metrics....

Ordningen på fälten i rubrikraden återspeglar sorteringsordningen för tabelldata.

Exempel: https://mgmt.auth.adobe.com/esm/v3/year/month.csv skapar en fil med namnet report__2024-07-20_2024-08-20_1000.csv med följande innehåll:

Datahastighet data-freshness

De lyckade HTTP-svaren innehåller ett Last-Modified-huvud som anger när rapporten i brödtexten senast uppdaterades. Avsaknaden av en senast ändrad rubrik anger att rapportdata beräknas i realtid.

Oftast uppdateras grova grå data mindre ofta än finkorniga data (t.ex. minutvärden eller timvärden kan vara mer aktuella än de dagliga värdena, särskilt för mätvärden som inte kan beräknas utifrån mindre granularitet, t.ex. unika tal).

GZIP-komprimering gzip-compression

Adobe rekommenderar starkt att du aktiverar GZIP-stöd i klienter som hämtar ESM-rapporter. Om du gör det minskar svarsstorleken avsevärt, vilket i sin tur minskar svarstiden. (Komprimeringsförhållandet för ESM-data ligger i intervallet 20-30.)

Om du vill aktivera gzip-komprimering i klienten anger du rubriken Accept-Encoding: enligt följande: