Guida introduttiva a REST APIs

Informazioni su requisiti generali, autenticazione, parametri di query facoltativi, richiesta URLs e altri riferimenti.

Raccomandazioni e requisiti per l’utilizzo delle API

Operazioni da eseguire con Audience Manager APIs.

Quando lavori con il codice Audience Manager API, tieni presente quanto segue:

  • Parametri di richiesta: tutti i parametri di richiesta sono richiesti, se non diversamente specificato.
  • Intestazioni di richiesta: quando utilizzi Adobe I/ Otokens, devi fornire l’ x-api-key intestazione . Puoi ottenere la tua chiave API seguendo le istruzioni contenute nella pagina Integrazione account di servizio .
  • JSONtipo di contenuto: specifica content-type: application/json ** accept: application/json e nel codice.
  • Richieste e risposte: invia richieste come JSON oggetto formattato correttamente. Audience Manager risponde con dati JSON formattati. Le risposte del server possono contenere dati richiesti, un codice di stato o entrambi.
  • Accesso: il tuo Audience Manager consulente ti fornirà un ID cliente e una chiave che ti permetterà di effettuare API richieste.
  • Documentazione ed esempi di codice: il testo in ** corsivo rappresenta una variabile fornita o passata durante la creazione o la ricezione API dei dati. Sostituisci il testo in corsivo con codice, parametri o altre informazioni richieste.

Autenticazione

I Audience Manager REST APIs supportano due metodi di autenticazione.

IMPORTANTE

A seconda del metodo di autenticazione, è necessario regolare di conseguenza la richiesta URLs. Per informazioni dettagliate sui nomi host da utilizzare, consulta la sezione Ambienti .

JWT (Service Account) Autenticazione tramite Adobe I/O

Panoramica dell’Adobe I/O

Adobe I/O è l'ecosistema e la comunità di sviluppatori di Adobe. Include gli strumenti per sviluppatori Adobe I/O e le API e API per tutti i prodotti Adobe.

Questo è il modo consigliato per configurare e utilizzare Adobe APIs.

Prerequisiti

Prima di configurare l'autenticazione JWT, assicurati di avere accesso a Adobe Developer Console in Adobe I/O. Per le richieste di accesso, contatta l’amministratore dell’organizzazione.

Autenticazione

Segui i passaggi seguenti per configurare l’autenticazione JWT (Service Account) utilizzando Adobe I/O:

  1. Accedi a Adobe Developer Console.
  2. Segui i passaggi descritti in Connessione account di servizio.
  3. Prova la connessione effettuando la tua prima API chiamata in base alle istruzioni del passaggio 3.
NOTA

Per configurare e lavorare con Audience Manager REST APIs in modo automatico, puoi generare il JWT a livello di programmazione. Per istruzioni dettagliate, consulta JWT (Service Account) Authentication .

Autorizzazioni RBAC dell'account tecnico

Se il tuo account di Audience Manager utilizza Controllo accessi basato su ruolo, devi creare un account utente tecnico Audience Manager e aggiungerlo al gruppo RBAC di Audience Manager che effettuerà le chiamate API.

Segui i passaggi riportati di seguito per creare un account utente tecnico e aggiungerlo a un gruppo RBAC:

  1. Effettua una chiamata GET a https://aam.adobe.io/v1/users/self. La chiamata crea un account utente tecnico visibile nella pagina Admin Console.Users

    conto tecnico

  2. Accedi al tuo account di Audience Manager e aggiungi l'account utente tecnico al gruppo di utenti che effettuerà le chiamate API.

OAuth Autenticazione (obsoleta)

AVVERTENZA

Audience Manager REST API l’autenticazione e il rinnovo dei token tramite OAuth 2.0 è ora obsoleto.

Utilizza invece JWT (Service Account) Authentication.

Il Audience Manager REST API segue gli standard OAuth 2.0 per l’autenticazione e il rinnovo dei token. Le sezioni seguenti descrivono come eseguire l'autenticazione e iniziare a lavorare con gli APIs.

Creare un utente generico API

È consigliabile creare un account utente tecnico separato per l’utilizzo di Audience Manager APIs. Si tratta di un account generico che non è associato o associato a un utente specifico della tua organizzazione. Questo tipo di account utente API consente di eseguire 2 operazioni:

  • Identifica quale servizio sta chiamando il API (ad esempio, le chiamate dalle tue app che utilizzano i nostri APIs o da altri strumenti che effettuano richieste API).
  • Fornire l'accesso ininterrotto ai APIs. Un account associato a una persona specifica può essere cancellato quando lascia la tua azienda. Questo ti impedirà di lavorare con il codice API disponibile. Un account generico che non è legato a un particolare dipendente ti aiuta a evitare questo problema.

Come esempio o caso d'uso per questo tipo di account, supponiamo che desideri cambiare un sacco di segmenti contemporaneamente con gli Strumenti di gestione in blocco. Beh, per fare questo, il tuo account utente ha bisogno di API accesso. Invece di aggiungere autorizzazioni a un utente specifico, crea un account utente API non specifico che disponga delle credenziali, della chiave e del segreto appropriati per effettuare chiamate API. Questa funzione è utile anche se si sviluppano applicazioni personalizzate che utilizzano Audience Manager APIs.

Rivolgiti al tuo consulente Audience Manager per configurare un account utente generico API solo.

Flusso di lavoro di autenticazione della password

Accesso protetto tramite autenticazione tramite password REST API. I passaggi seguenti delineano il flusso di lavoro per l’autenticazione tramite password da un client JSON nel browser.

SUGGERIMENTO

Cifra token di accesso e aggiornamento se li archivi in un database.

Passaggio 1: Richiedi accesso API

Contatta il tuo Partner Solutions Manager. Ti forniranno un API ID client e un segreto. L'ID e il segreto ti autenticano nel API.

Nota: Se desideri ricevere un token di aggiornamento, specifica che quando richiedi l’accesso a API .

Passaggio 2: Richiedere il token

Passa una richiesta di token con il client JSON preferito. Quando crei la richiesta:

  • Utilizza un metodo POST per chiamare https://api.demdex.com/oauth/token.
  • Converti l'ID client e il segreto in una stringa con codifica base-64. Separa l’ID e il segreto con due punti durante il processo di conversione. Ad esempio, le credenziali testId : testSecret vengono convertite in dGVzdElkOnRlc3RTZWNyZXQ=.
  • Passa i valori HTTP headers Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Ad esempio, l’intestazione potrebbe avere l’aspetto seguente:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Imposta il corpo della richiesta come segue:

    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Passaggio 3: Ricevere il token

La risposta JSON contiene il token di accesso. La risposta dovrebbe essere simile alla seguente:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

La chiave expires_in rappresenta il numero di secondi fino alla scadenza del token di accesso. Come best practice, utilizza brevi tempi di scadenza per limitare l’esposizione se il token è mai esposto.

Aggiorna token

I token di aggiornamento rinnovano l’accesso API dopo la scadenza del token originale. Se richiesto, la risposta JSON nel flusso di lavoro della password include un token di aggiornamento. Se non ricevi un token di aggiornamento, creane uno nuovo tramite il processo di autenticazione tramite password.

Puoi anche utilizzare un token di aggiornamento per generare un nuovo token prima della scadenza del token di accesso esistente.

Se il token di accesso è scaduto, riceverai un 401 Status Code e la seguente intestazione nella risposta:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

I passaggi seguenti delineano il flusso di lavoro per l’utilizzo di un token di aggiornamento per creare un nuovo token di accesso da un client JSON nel browser.

Passaggio 1: Richiedere il nuovo token

Passa una richiesta di aggiornamento del token con il client JSON preferito. Quando crei la richiesta:

  • Utilizza un metodo POST per chiamare https://api.demdex.com/oauth/token.
  • Converti l'ID client e il segreto in una stringa con codifica base-64. Separa l’ID e il segreto con due punti durante il processo di conversione. Ad esempio, le credenziali testId : testSecret vengono convertite in dGVzdElkOnRlc3RTZWNyZXQ=.
  • Passa le intestazioni HTTP Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded. Ad esempio, l’intestazione potrebbe avere l’aspetto seguente:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Nel corpo della richiesta, specifica grant_type:refresh_token e passa il token di aggiornamento ricevuto nella richiesta di accesso precedente. La richiesta deve essere simile alla seguente:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Passaggio 2: Ricevere il nuovo token

La risposta JSON contiene il nuovo token di accesso. La risposta dovrebbe essere simile alla seguente:

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Codice di autorizzazione e autenticazione implicita

Il Audience Manager REST API supporta il codice di autorizzazione e l'autenticazione implicita. Per utilizzare questi metodi di accesso, gli utenti devono accedere a https://api.demdex.com/oauth/authorize per ottenere i token di accesso e aggiornamento.

Effettuare richieste API autenticate

Requisiti per la chiamata dei metodi API dopo aver ricevuto un token di autenticazione.

Per effettuare chiamate ai metodi API disponibili:

  • Nell’intestazione HTTP, imposta Authorization: Bearer <token>.
  • Quando utilizzi JWT (Service Account) Authentication, devi fornire l'intestazione x-api-key , che sarà la stessa del tuo client_id. Puoi ottenere il tuo client_id dalla pagina Integrazione Adobe I/O .
  • Chiama il metodo API richiesto.

Parametri di query API facoltativi

Impostare i parametri facoltativi disponibili per i metodi che restituiscono tutte le proprietà di un oggetto.

È possibile utilizzare questi parametri facoltativi con metodi API che restituiscono le proprietà all per un oggetto. Imposta queste opzioni nella stringa di richiesta quando trasmetti la query in a API.

Parametro Descrizione
page Restituisce i risultati per numero di pagina. La numerazione inizia da 0.
pageSize Imposta il numero di risultati di risposta restituiti dalla richiesta (10 è l’impostazione predefinita).
sortBy Ordina e restituisce i risultati in base alla proprietà JSON specificata.
descending Ordina e restituisce i risultati in ordine decrescente. ascending è il valore predefinito.
search Restituisce i risultati in base alla stringa specificata che si desidera utilizzare come parametro di ricerca. Ad esempio, supponiamo che tu voglia trovare risultati per tutti i modelli con la parola "Test" in uno qualsiasi dei campi di valore per quell’elemento. La richiesta di esempio potrebbe essere simile alla seguente: GET https://aam.adobe.io/v1/models/?search=Test. Puoi cercare qualsiasi valore restituito da un metodo "get all".
folderId Restituisce tutti gli ID di traits all'interno della cartella specificata. Non disponibile per tutti i metodi.
permissions Restituisce un elenco di segmenti in base all’autorizzazione specificata. READ è il valore predefinito. Le autorizzazioni includono:
  • READ : Restituisce e visualizza informazioni su un segmento.
  • WRITE : Utilizza PUT per aggiornare un segmento.
  • CREATE : Utilizza POST per creare un segmento.
  • DELETE : Elimina un segmento. Richiede l’accesso alle caratteristiche sottostanti, se presenti. Ad esempio, se desideri rimuoverlo, avrai bisogno dei diritti per eliminare le caratteristiche che appartengono a un segmento.

Specifica più autorizzazioni con coppie chiave-valore separate. Ad esempio, per restituire un elenco di segmenti solo con autorizzazioni READ e WRITE , passa "permissions":"READ", "permissions":"WRITE" .
includePermissions (Boolean) Imposta su true per restituire le autorizzazioni per il segmento. Il valore predefinito è false.

Nota sulle opzioni di pagina

Quando le informazioni di pagina non sono specificate, la richiesta restituisce normale JSON restituisce un array. Se le informazioni di pagina sono specificate, l’elenco restituito viene racchiuso in un oggetto JSON che contiene informazioni sul risultato totale e sulla pagina corrente. La richiesta di esempio utilizzando le opzioni di pagina potrebbe avere un aspetto simile al seguente:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs per richieste, ambienti di staging e produzione e versioni.

Richiesta URLs

Nella tabella seguente è riportato l’elenco della richiesta URLs utilizzata per trasmettere le richieste API tramite metodo .

A seconda del metodo di autenticazione utilizzato, è necessario regolare la richiesta URLs in base alle tabelle seguenti.

Richiesta URLs di autenticazione JWT

API Metodi Richiesta URL
Algorithmic Modeling https://aam.adobe.io/v1/models/
Data Source https://aam.adobe.io/v1/datasources/
Derived Signals https://aam.adobe.io/v1/signals/derived/
Destinations https://aam.adobe.io/v1/destinations/
Domains https://aam.adobe.io/v1/partner-sites/
Folders Caratteristiche: https://aam.adobe.io/v1/folders/traits /
Segmenti: https://aam.adobe.io/v1/folders/segments /
Schema https://aam.adobe.io/v1/schemas/
Segments https://aam.adobe.io/v1/segments/
Traits https://aam.adobe.io/v1/traits/
Trait Types https://aam.adobe.io/v1/customer-trait-types
Taxonomy https://aam.adobe.io/v1/taxonomies/0/

Richiesta URLs di autenticazione OAuth (obsoleta)

API Metodi Richiesta URL
Algorithmic Modeling https://api.demdex.com/v1/models/
Data Source https://api.demdex.com/v1/datasources/
Derived Signals https://api.demdex.com/v1/signals/derived/
Destinations https://api.demdex.com/v1/destinations/
Domains https://api.demdex.com/v1/partner-sites/
Folders Caratteristiche: https://api.demdex.com/v1/folders/traits /
Segmenti: https://api.demdex.com/v1/folders/segments /
Schema https://api.demdex.com/v1/schemas/
Segments https://api.demdex.com/v1/segments/
Traits https://api.demdex.com/v1/traits/
Trait Types https://api.demdex.com/v1/customer-trait-types
Taxonomy https://api.demdex.com/v1/taxonomies/0/

Ambienti

I Audience Manager APIs consentono l'accesso a diversi ambienti di lavoro. Questi ambienti consentono di testare il codice in base a database separati senza influire sui dati di produzione live. Nella tabella seguente sono elencati gli ambienti API disponibili e i nomi host delle risorse corrispondenti.

A seconda del metodo di autenticazione utilizzato, è necessario regolare l’ambiente URLs in base alla tabella seguente.

Ambiente Nome host per l’autenticazione JWT Nome host per l’autenticazione OAuth
Produzione https://aam.adobe.io/... https://api.demdex.com/...
Beta https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
NOTA

L’ Audience Manager ambiente beta è una versione autonoma e su scala ridotta dell’ambiente di produzione. Tutti i dati da testare devono essere immessi e raccolti in questo ambiente.

Versioni

Le nuove versioni di questi APIs vengono rilasciate regolarmente. Una nuova versione incrementa il numero di versione API. Il numero di versione è indicato nella richiesta URL come v<version number> come mostrato nell'esempio seguente:

https://<host>/v1/...

Codici di risposta definiti

HTTP codici di stato e testo di risposta restituiti da Audience Manager REST API.

ID codice di risposta Testo di risposta Definizione
200 OK La richiesta è stata elaborata correttamente. Se necessario, restituirà il contenuto o i dati previsti.
201 Created La risorsa è stata creata. Restituisce le richieste PUT e POST .
204 No Content La risorsa è stata eliminata. Il corpo della risposta sarà vuoto.
400 Bad Request Il server non ha capito la richiesta. Di solito a causa di sintassi non corretta. Controlla la richiesta e riprova.
403 Forbidden Non hai accesso alla risorsa.
404 Not Found Impossibile trovare la risorsa per il percorso specificato.
409 Conflict Impossibile completare la richiesta a causa di un conflitto con lo stato della risorsa.
500 Server Error Errore imprevisto del server che ne impediva l'esecuzione della richiesta.

In questa pagina