13 raccomandazioni per l'utilizzo dell'API di reporting di Eulerian

13 raccomandazioni per l'utilizzo dell'API di reporting di Eulerian



1. Principio chiave dell'API di reporting batch

L'API di reporting batch consente di estrarre i dati di reporting di Eulerian dalle viste disponibili nell'interfaccia.
Dovrebbe essere utilizzato come mezzo per automatizzare l'estrazione di report già disponibili nell'interfaccia Euleriana. Non deve essere considerato uno strumento per creare, con una singola query, un livello di granularità o una combinazione di dati non presenti nei report.
Ad esempio, se un'analisi richiede la combinazione di più fonti o punti di vista, è necessario effettuare più richieste API e successivamente i risultati devono essere aggregati sul lato BI, nel data warehouse o nello script di elaborazione.


2. Orario consigliato per avviare i processi API

Per recuperare i dati completi da J-1, si consiglia di avviare le esportazioni dalle ore 06:00 .
Durante la notte, Eulerian sincronizza il database "freddo" per integrare i dati del giorno precedente. Una query effettuata nelle primissime ore del mattino, ad esempio intorno alle 05:00, potrebbe verificarsi durante questa sincronizzazione e risultare indisponibile o restituire dati incompleti.
La raccomandazione operativa è pertanto di programmare i job API a partire dalle ore 06:00 .


3. Recuperare i parametri corretti per una richiesta API

Un metodo semplice per costruire una richiesta API consiste nel partire dal report desiderato nell'interfaccia Euleriana e quindi osservare la richiesta generata dall'interfaccia.
Passaggi consigliati:
    Aprire il report desiderato nell'interfaccia Euleriana.
    Apri gli strumenti per sviluppatori del browser con F12 .
    Vai alla scheda Rete .
    Identificare la query di reporting generata dall'interfaccia.
    Recupera i parametri necessari per costruire il corpo dell'API.
Gli elementi utili da recuperare includono:
Élément observé dans la requête réseau
Utilisation dans l’API
view-id
ID vista attribuzione
ea-datasource
Valore del kind , con il prefisso rt# nel corpo dell'API
path
Valore da utilizzare nel campo path del corpo JSON
ID presenti nel path
ID editore, leva finanziaria, piano media o campagna a seconda della visualizzazione
Il path visibile nella console contiene già gli ID corrispondenti al livello di dati visualizzato: publisher, leva, piano media, campagna, ecc.


4. Endpoint di query

L'endpoint utilizzato per interrogare l'API di reporting batch ha il seguente formato:
POST /ea/{site}/report/{batch}/query.json
Il corpo JSON in genere contiene un array
Content-Type: application/json
reports , nei quali definiamo:
Élément
Rôle
dateRanges
Periodo di analisi
dimensions
Punti chiave da considerare nel rapporto
kind
Fonte dati / tipo di report
metrics
Indicatori da estrarre
path
livello o ambito di copertura giornalistica
segmentFilterClauses
Filtri opzionali, ad esempio sui tipi di vendita
Esempio semplice:
 {
 "reports": [
 {
 "dateRanges": [
 {
 "range": "YESTERDAY"
 }
 ],
 "dimensions": [
 {
 "field": "ope_name",
 "name": "campaign"
 }
 ],
 "kind": "rt#insummary",
 "metrics": [
 {
 "field": "scartvalid",
 "name": "sales"
 }
 ],
 "path": "mcMEDIAINCOMING[?].mcMEDIAAD.mcOPE"
 }
 ]
IL
}

kind , path , le dimensioni e le metriche devono essere adattati al rapporto che desideriamo riprodurre.


5. Filtra per tipo di vendita

I filtri sui tipi di vendita vengono gestiti tramite segmentFilterClauses .
Nel caso delle tipologie di vendita, il campo da utilizzare è:
 Esempio di query con filtro sul tipo di vendita:
"field": "ordertype_id"

{
 "reports": [
 {
 "dateRanges": [
 {
 "range": "YESTERDAY"
 }
 ],
 "dimensions": [
 {
 "field": "ope_name",
 "name": "campaign"
 }
 ],
 "kind": "rt#insummary",
 "metrics": [
 {
 "field": "scartvalid",
 "name": "sales"
 }
 ],
 "path": "mcMEDIAINCOMING[?].mcMEDIAAD.mcOPE",
 "segmentFilterClauses": [
 {
 "field": "ordertype_id",
 "operator": "IN",
 "value": [
 1,
 2
 ]
 }
 ]
 }
 ]
Les IDs à ​​renseigner dans
}

value doivent être récupérés dans l'interface Eulerian tramite la recherche Liste des types de ventes .
Da ricordare: non è faut pas utilizzare direttamente il mestiere indicato nel tipo di vendita nella richiesta API. Il faut utiliser son ID tecnica.


6. Recuperare gli ID dei tipi di vendita

Per recuperare gli ID dei tipi di vento:
    Aller dans l'interface Eulerian.
    Utiliser la barre de recherche en haut à droite.
    Cerca l'elenco dei tipi di vento .
    Identificatore les IDs corrispondente ai tipi di ventes souhaités.
    Utilizza questi ID in segmentFilterClauses.value .
Esempio:
 "segmentFilterClauses": [
 {
 "field": "ordertype_id",
 "operator": "IN",
 "value": [
 117,
 135,
 159
 ]
 }
I valori citati sono riportati nel titolo dell'esempio. Dovranno essere adattati al client perimetrale e ai tipi di ventole effettivamente visibili nell'interfaccia.
]




7. ID dei prelievi media Eulerian

I principali ID di prelievo multimediale sono i seguenti:
ID
Levier
2
MAILING
3
PUBBLICITÀ / Visualizzazione
4
AFFILIAZIONE
5
SPONSOREDLINK / Vincoli sponsorizzati
6
PARTNER / Partenariat
7
INTERNO
8
FEED AFFIDABILE
10
BRANDING
16
OFFLINE
17
SOCIALE
20
GENERICO
Questi ID possono essere utilizzati per verificare o creare path relativi alle visualizzazioni multimediali.


8. ID del modello di attribuzione aumentato

Per gli algoritmi di attribuzione, gli ID sono visibili nell'interfaccia di Eulerian, tramite la pagina Crea e modifica i miei modelli .
Ciò vi permetterà di identificare il modello di attribuzione utilizzato nelle viste di reporting.


9. Migliori pratiche per l'integrazione tra BI e Data Warehouse

Per industrializzare l'utilizzo dell'API di reporting di Eulerian, si raccomanda di:
  • Partendo da una vista esistente nell'interfaccia Euleriana, si costruisce la richiesta API;
  • Recupera il kind , path e gli ID tramite la scheda Rete del browser;
  • Pianifica le chiamate API a partire dalle 06:00;
  • utilizzare identificativi tecnici anziché etichette commerciali;
  • Utilizzare segmentFilterClauses per applicare filtri specifici;
  • eseguire più query quando la vista desiderata combina più parametri;
  • aggregare i risultati sul lato BI, data warehouse o script di elaborazione;
  • conservare un timestamp di estrazione per facilitare la verifica dei dati.


10. Riepilogo operativo

Sujet
Recommandation
Punto finale
POST /ea/{site}/report/{batch}/query.json
Formato
JSON
Orario di lancio consigliato
A partire dalle ore 6:00
Costruzione della query
Partendo da una vista esistente nell'interfaccia
Recuperare il kind e path
Tramite la scheda Rete del browser
Filtro per tipo di vendita
segmentFilterClauses con field: "ordertype_id"
ID tipo di vendita
Da recuperare dall'elenco dei tipi di vendita
ID di leva media
Utilizza questo strumento per controllare i path
ID modello MTA potenziati
Tramite la pagina di creazione e modifica dei modelli
aggregazione complessa
Esegui più query e poi aggrega i risultati sul lato BI.


11. Come richiedere i piani media

Per interrogare i piani media tramite l'API di reporting di Eulerian, si consiglia di suddividere la query in più parti in modo che rimanga valida e utilizzabile.
La prassi migliore prevede l'esecuzione di una query per ciascun canale di acquisizione.
Ogni richiesta segue la stessa struttura, ma con un path diverso a seconda della leva desiderata.
Levier d’acquisition
Path à utiliser
Display
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[3].mcPUBLISHER
Mailing
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[2].mcPUBLISHER
Sociale
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[17].mcPUBLISHER
MARE
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[5].mcPUBLISHER
Affiliazione
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[4].mcPUBLISHER
In questi esempi:
  • mcWEBSITE[1] corrisponde al sito in questione;
  • mcMEDIAPLAN[1] corrisponde al piano media mirato;
  • mcMEDIA[x] corrisponde alla leva di acquisizione;
  • mcPUBLISHER consente di accedere al livello di supporto/editore.
Gli ID devono essere adattati al contesto del cliente e al livello di reporting desiderato.

Esempio di query per la leva di visualizzazione

Esempio per la leva Display , con viste di attribuzione 3 , 8 e 6 , nel periodo dal 01/04/2026 al 31/05/2026 .
 {
 "async": false,
 "reports": [
 {
 "kind": "rt#mediaplan",
 "path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[3].mcPUBLISHER",
 "segments": [
 {
 "name": "Attribution rule",
 "operator": "IN",
 "type": "attributionrule",
 "value": [
 3,
 8,
 6
 ]
 }
 ],
 "dimensions": [
 {
 "field": "publisheralias_alias",
 "name": "Support"
 }
 ],
 "metrics": [
 {
 "name": "Ventes réelles",
 "field": "realscartvalid"
 }
 ],
 "dateRanges": [
 {
 "dateFrom": "2026-04-01",
 "dateTo": "2026-05-31",
 "dateFormat": "YYYY-MM-DD"
 }
 ]
 }
 ]
Per interrogare un altro lever, è sufficiente utilizzare la stessa struttura e sostituire il valore del
}

path tramite quello della leva desiderata.
Ad esempio, per SEA, il path diventa:
 Questo approccio contribuisce a garantire tempi di risposta più rapidi, a controllare meglio i volumi restituiti e a facilitare l'aggregazione dei risultati sul lato BI o data warehouse.
"path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[5].mcPUBLISHER"



12. Raccomandazione: scegliere tra publisheralias_alias e publisher_name

Durante una query, può accadere che la dimensione publisheralias_alias restituisca un valore vuoto anche se sono presenti delle metriche.
Questo comportamento è normale e dipende da come il tracciamento euleriano è stato implementato sulle piattaforme dei partner.

Differenza tra publisheralias_alias e publisher_name

Quando il tracciamento euleriano viene implementato all'interno di una piattaforma di terze parti, come una DSP, un ad server o una piattaforma multimediale, i parametri di tracciamento della campagna non raccolgono direttamente l'editore o il nome della campagna tramite una macro leggibile, ad esempio:
 In questo caso, il tracciamento può essere effettuato tramite ID tecnici, ad esempio:
ead-publisher={{publisher_name}}, qui deviendrait "lequipe.fr"

 Eulerian utilizza quindi i connettori EPC per mappare l'ID raccolto nelle impostazioni di tracciamento all'etichetta effettiva dell'editore o della campagna, così come appare sulla piattaforma di terze parti.
ead-publisher={{publisher_id}}, qui deviendrait "1234"

Queste etichette riviste sono chiamate alias sul lato euleriano. Sono accessibili tramite la dimensione:
 {
 "field": "publisheralias_alias",
 "name": "Support"
Al contrario, quando il nome dell'editore viene inviato direttamente al sistema di tracciamento, senza richiedere la mappatura del connettore, è necessario utilizzare la seguente dimensione:
}

 {
 "field": "publisher_name",
 "name": "Support"
13. Utilizzare
}


overwriteNameByAlias ​​per gestire automaticamente gli alias

Per evitare di dover passare manualmente da publisher_name a publisheralias_alias , è possibile utilizzare la seguente opzione API:
 Questa opzione consente di chiedere all'API di dare priorità all'alias quando esiste, mantenendo il nome non elaborato quando l'alias non è disponibile.
"overwriteNameByAlias": true

Nello specifico, il documento affronta il seguente caso:
  • Se l'editore ha un alias, l'API restituisce l'alias;
  • Se l'editore non ha un alias, l'API restituisce il publisher_name .
Questo aiuta a limitare le righe vuote nelle esportazioni e a ottenere una dimensione "Supporto" più direttamente utilizzabile dal punto di vista della Business Intelligence o del data warehouse.

Dove inserire l'opzione nella query

L'opzione overwriteNameByAlias ​​deve essere aggiunta a livello di blocco del report, allo stesso livello di kind , path , segments , dimensions , metrics e dateRanges .
Esempio sulla leva sociale:
{
 "async": false,
 "reports": [
 {
 "kind": "rt#mediaplan",
 "path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[17].mcPUBLISHER",
 "overwriteNameByAlias": true,
 "segments": [
 {
 "name": "Attribution rule",
 "operator": "IN",
 "type": "attributionrule",
 "value": [
 3,
 8,
 6
 ]
 }
 ],
 "dimensions": [
 {
 "field": "publisher_name",
 "name": "Support"
 }
 ],
 "metrics": [
 {
 "name": "Ventes réelles",
 "field": "realscartvalid"
 }
 ],
 "dateRanges": [
 {
 "dateFrom": "2026-04-01",
 "dateTo": "2026-05-31",
 "dateFormat": "YYYY-MM-DD"
 }
 ]
 }
 ]
Dimensione da utilizzare con questa opzione
}




Quando overwriteNameByAlias ​​è attivo, si consiglia di utilizzare la dimensione standard publisher_name :
 "dimensions": [
 {
 "field": "publisher_name",
 "name": "Support"
 }
L'API si carica quando si applica l'alias quando celui-ci è disponibile.
]

Questo approccio è più semplice che richiedere separatamente publisher_name e publisheralias_alias , quindi riconciliare i due campi vicino BI.

Porta dell'opzione

L'opzione overwriteNameByAlias ​​non viene applicata esclusivamente agli editori.
Può anche essere applicato ad altre dimensioni a disposizione di un meccanismo di alias, ad esempio:
Dimension brute
Alias potentiellement appliqué
publisher_name
pseudonimo dell'editore
ope_name
alias della campagna
creative_name
alias per creazione
Questa opzione consente quindi di ottenere etichette più chiare e coerenti nelle esportazioni API quando i connettori euleriani utilizzano alias.

Raccomandazione operativa

Per domande da parte dell'assistenza/editore:
    Utilizzare publisher_name come dimensione primaria.
    Aggiungere "overwriteNameByAlias": true nel blocco del report.
    Verifica il risultato sulle leve in cui coesistono le due logiche, in particolare quella sociale.
    Mantieni questa opzione se i supporti vengono recuperati correttamente con gli alias previsti e senza righe vuote ingiustificate.
Questa opzione è particolarmente utile per il livello Social, dove alcune campagne possono essere tracciate tramite ID partner e poi rielaborate tramite alias, mentre altre campagne possono essere tracciate manualmente con un nome publisher già disponibile.