API di monitoraggio del servizio di adesione entitlement-service-monitoring-api

Panoramica API api-overview

Il monitoraggio del servizio di titolarità è implementato come progetto WOLAP (Web-based Online Analytical Processing). ESM è un’API web generica per la generazione di rapporti di business supportata da un data warehouse. Funge da linguaggio di query HTTP che consente l'esecuzione completa di operazioni OLAP tipiche.

L'API ESM fornisce una visualizzazione gerarchica dei cubi OLAP sottostanti. Ogni risorsa (dimensione nella gerarchia delle dimensioni, mappata come segmento di percorso URL) genera rapporti con metriche (aggregate) per la selezione corrente. Ogni risorsa punta alla relativa risorsa padre (per l’aggregazione) e alle relative risorse secondarie (per l’espansione). Le operazioni di suddivisione in porzioni e dicing vengono eseguite tramite parametri di stringa di query che fissano dimensioni a valori o intervalli specifici.

L’API REST fornisce i dati disponibili entro un intervallo di tempo specificato nella richiesta (fallback ai valori predefiniti se non ne viene fornito alcuno), in base al percorso della dimensione, ai filtri forniti e alle metriche selezionate. L’intervallo di tempo non verrà applicato ai rapporti che non contengono dimensioni temporali (anno, mese, giorno, ora, minuto, secondo).

Il percorso radice dell’URL dell’endpoint restituisce le metriche aggregate complessive all’interno di un singolo record, insieme ai collegamenti alle opzioni di drill-down disponibili. La versione API è mappata come segmento finale del percorso URI dell’endpoint. https://mgmt.auth.adobe.com/esm/v3, ad esempio, indica che i client accederanno a WOLAP versione 3.

I percorsi URL disponibili sono individuabili tramite i collegamenti contenuti nella risposta. I percorsi URL validi vengono mantenuti per mappare un percorso all’interno della struttura di drill-down sottostante che contiene le metriche (pre)aggregate. Un percorso nel modulo /dimension1/dimension2/dimension3 rifletterà una preaggregazione di queste tre dimensioni (l'equivalente di un SQL clause GROUP BY dimension1, dimension2, dimension3). Se tale preaggregazione non esiste e il sistema non è in grado di calcolarla immediatamente, l’API restituirà una risposta 404 Not Found.

Albero drill-down drill-down-tree

Le seguenti strutture di espansione illustrano le dimensioni (risorse) disponibili in ESM 3.0 per Programmatori e MVPDs.

Dimension disponibili per i programmatori progr-dimensions

Giorno

Hour

Minuto

Dimension disponibili per gli MVPD mvpd-dimensions

Un GET all'endpoint API https://mgmt.auth.adobe.com/esm/v3 restituirà una rappresentazione contenente:

Seguire un percorso di espansione (passo dopo passo):
/dimensionA/year/month/day/dimensionX recupera quanto segue
risposta:

Filtri

Ad eccezione delle dimensioni data/ora, qualsiasi dimensione disponibile per la proiezione corrente (percorso dimensione) può essere filtrata utilizzando il suo nome come parametro della stringa di query.

Sono disponibili le seguenti opzioni di filtro:

Esiste anche un utilizzo speciale per i nomi delle dimensioni nella stringa di query: se il nome della dimensione viene utilizzato come parametro della stringa di query senza valore, questo indicherà all’API di restituire una proiezione che include tale dimensione nel rapporto.

Esempio di query ESM

I seguenti parametri della stringa di query hanno significati riservati per l’API (e pertanto non possono essere utilizzati come nomi di dimensioni, altrimenti non sarebbe possibile alcun filtro per tale dimensione).

Parametri stringa query riservata API ESM

Al momento l’unico metodo HTTP disponibile è GET.

Codici di stato API ESM esm-api-status-codes

Formati dati data-formats

I dati sono disponibili nei seguenti formati:

I client possono utilizzare le seguenti strategie di negoziazione dei contenuti (la precedenza è data dalla posizione nell'elenco, prima le cose):

Sia l’"estensione" che il parametro query supportano i seguenti valori:

Se nessuna delle strategie specifica un tipo di file multimediale, l’API produrrà il contenuto JSON per impostazione predefinita.

Lingua applicazione ipertesto hypertext-application-language

Per JSON e XML, il payload verrà codificato come HAL, come descritto qui: http://stateless.co/hal_specification.html.

Il rapporto effettivo (un tag/proprietà nidificata denominata "report") sarà costituito dall’elenco effettivo di record contenenti tutte le dimensioni e le metriche selezionate/applicabili con i relativi valori, codificati come segue:

JSON

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

XML

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

Per i formati XML e JSON, l’ordine dei campi (dimensioni e metriche) all’interno di un record non è specificato, ma è coerente (l’ordine è lo stesso in tutti i record). Tuttavia, i clienti non devono basarsi su un ordine particolare dei campi all’interno di un record.

Il collegamento della risorsa (il rel "self" in JSON e l’attributo di risorsa "href" in XML) contiene il percorso corrente e la stringa di query utilizzati per il rapporto in linea. La stringa di query rivelerà tutti i parametri impliciti ed espliciti, in modo che il payload indichi esplicitamente l’intervallo di tempo utilizzato, i filtri impliciti (se presenti) e così via. Gli altri collegamenti all’interno della risorsa conterranno tutti i segmenti disponibili che possono essere seguiti per eseguire il drill-down dei dati correnti. Verrà inoltre fornito un collegamento per il rollup che punterà al percorso principale (se presente). Il valore href per i collegamenti drill-down/roll-up contiene solo il percorso URL (non include la stringa di query, pertanto se necessario il client deve accodarlo). Nota che non tutti i parametri della stringa di query utilizzati (o impliciti) dalla risorsa corrente saranno applicabili per i collegamenti "roll-up" o "drill-down" (ad esempio, i filtri potrebbero non essere applicabili alle risorse secondarie o super).

Esempio (supponendo che sia presente una singola metrica denominata clients ed una preaggregazione per 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

Nel formato dati CSV, non verranno forniti collegamenti o altri metadati (tranne la riga di intestazione) in linea; invece, i metadati di selezione verranno forniti nel nome file, che seguirà questo pattern:

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

Il file CSV conterrà una riga di intestazione e quindi i dati del rapporto come righe successive. La riga di intestazione conterrà tutte le dimensioni seguite da tutte le metriche. L’ordinamento dei dati del rapporto si rifletterà nell’ordine delle dimensioni. Pertanto, se i dati sono ordinati per D1 e poi per D2, l'intestazione CSV sarà simile a: D1, D2, ...metrics....

L’ordine dei campi nella riga di intestazione rifletterà l’ordinamento dei dati della tabella.

Esempio: https://mgmt.auth.adobe.com/esm/v3/year/month.csv produrrà un file denominato report__2024-07-20_2024-08-20_1000.csv con il seguente contenuto:

Aggiornamento dei dati data-freshness

Le risposte HTTP riuscite contengono un'intestazione Last-Modified che indica l'ora dell'ultimo aggiornamento del report nel corpo. L’assenza di un’intestazione Ultima modifica indica che i dati del rapporto vengono calcolati in tempo reale.

In genere, i dati a grana grossa vengono aggiornati meno frequentemente dei dati a grana fine (ad esempio, i valori orari o di by-the-minuti possono essere più aggiornati dei valori giornalieri, soprattutto per le metriche che non possono essere calcolate in base a granularità più piccole, come i conteggi univoci).

Compressione GZIP gzip-compression

Adobe consiglia vivamente di abilitare il supporto gzip nei client che recuperano i rapporti ESM. In questo modo si riduce notevolmente la dimensione della risposta, con conseguente riduzione dei tempi di risposta. Il rapporto di compressione per i dati ESM è compreso nell'intervallo 20-30.

Per abilitare la compressione Gzip nel client, impostare l'intestazione Accept-Encoding: come segue: