ARGOMENTI×
Getting Started with REST APIs
Informazioni su requisiti generali, autenticazione, parametri di query facoltativi, richieste URLse altri riferimenti.
Raccomandazioni e requisiti per l’utilizzo delle API
Cose che devi e che devi fare quando lavori con gli APIs.
Quando lavorate con
codice API
Audience Manager, tenete presente quanto segue:
- Parametri di richiesta: tutti i parametri di richiesta sono obbligatori, se non diversamente specificato.
- Intestazioni richieste: quando utilizzate i token di I/O di Adobe, dovete fornire l’ x-api-key intestazione. Per ottenere la API chiave, segui le istruzioni riportate nella pagina Integrazione account di servizio.
- JSONtipo di contenuto: Specificate content-type: application/json e inserite accept: application/json nel codice.
- Richieste e risposte: Invia le richieste come un JSON oggetto formattato correttamente. Audience Manager risponde con dati JSON formattati. Le risposte del server possono contenere i dati richiesti, un codice di stato o entrambi.
- Accesso: Il Audience Manager consulente vi fornirà un ID cliente e una chiave che vi consentirà 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 di API dati. Sostituite il testo in corsivo con codice, parametri o altre informazioni personali.
Autenticazione
Sono Audience Manager supportati due metodi di autenticazione REST APIs .
- Autenticazione JWT (Service Account) tramite Adobe I/O . Adobe I/O è l'ecosistema e la comunità di sviluppatori di Adobe. Include gli strumenti di sviluppo Adobe I/O, le API e le API per tutti i prodotti Adobe. Questo è il metodo consigliato per configurare e utilizzare Adobe . APIs
- Autenticazione OAuth (obsoleta) . Anche se questo metodo è obsoleto, i clienti con OAuth integrazioni esistenti possono continuare a utilizzare questo metodo.
A seconda del metodo di autenticazione, è necessario regolare la richiesta URLs di conseguenza. Consulta la sezione
Ambienti
per informazioni dettagliate sui nomi host da utilizzare.
JWT (Service AccountAutenticazione tramite I/O Adobe
Panoramica di Adobe I/O
Adobe I/O è l'ecosistema e la comunità di sviluppatori di Adobe. Include gli strumenti di sviluppo
Adobe I/O, le API
e
le API per tutti i prodotti
Adobe.
Questo è il metodo consigliato per configurare e utilizzare Adobe . APIs
Prerequisiti
Prima di configurare JWT l'autenticazione, accertatevi di disporre dell'accesso ad
Adobe Developer Console
in
Adobe I/O
. Contattate l’amministratore dell’organizzazione per le richieste di accesso.
Autenticazione
Per configurare l' JWT (Service Account) autenticazione tramite Adobe I/O:
- Accedete ad Adobe Developer Console .
- Seguite i passaggi in Connessione account di servizio.
- Durante il passaggio 2: Aggiungete un'API al progetto utilizzando l'autenticazione dell'account di servizio, scegliete l' Audience Manager opzione API .
- Prova la connessione effettuando la tua prima API chiamata in base alle istruzioni del passaggio 3 .
Per configurare e lavorare con Audience Manager l'app REST APIs in modo automatico, potete generare il file JWT programmaticamente. Per istruzioni dettagliate, consultate Autenticazione
JWT.md
JWT (Service Account).
OAuth Autenticazione (obsoleta)
Audience Manager REST API l'autenticazione token e il rinnovo tramite OAuth 2.0 è ora obsoleto.
Utilizzare invece l'autenticazione
#jwt-service-account-authentication-jwt
JWT (Service Account).
Gli Audience Manager standard REST API seguono OAuth 2.0 per l'autenticazione e il rinnovo dei token. Le sezioni seguenti descrivono come autenticarsi e iniziare a lavorare con gli APIs.
Creare un API utente generico
Vi consigliamo di creare un account utente tecnico separato per l’utilizzo degli APIs. Si tratta di un account generico che non è associato o associato a un utente specifico nell'organizzazione. Questo tipo di account API utente consente di realizzare 2 operazioni:
- Identificare il servizio che sta chiamando API (ad es., chiamate dalle vostre app che utilizzano i nostri APIo da altri strumenti che effettuano API richieste).
- Fornire l'accesso ininterrotto agli APIs. Un account legato a una persona specifica può essere eliminato quando esce dalla società. In questo modo non sarà possibile utilizzare il API codice disponibile. Un account generico che non è legato a un particolare dipendente consente di evitare questo problema.
Ad esempio, per questo tipo di account, supponiamo che tu voglia cambiare molti segmenti alla volta con gli Strumenti
di gestione
di massa. Per fare questo, il vostro account utente ha bisogno di API accesso. Invece di aggiungere autorizzazioni a un utente specifico, create un account utente non specifico API con le credenziali, la chiave e il segreto appropriati per effettuare API le chiamate. Questo è utile anche se si sviluppano applicazioni personalizzate che utilizzano Audience Manager gli APIs.
Consultate il vostro Audience Manager consulente per configurare un account utente generico APIsolo.
Flusso di lavoro di autenticazione della password
Accesso sicuro tramite autenticazione tramite password REST API. I passaggi riportati di seguito descrivono il flusso di lavoro per l'autenticazione tramite password da parte di un JSON client nel browser.
Cifra i token di accesso e di aggiornamento se li si archivia in un database.
Passaggio 1: Richiedi API accesso
Contatta il tuo Partner Solutions Manager. Forniranno un ID API cliente e un segreto. L’ID e il segreto vi autenticano nel APIsito.
Nota: Se desiderate ricevere un token di aggiornamento, specificatelo quando richiedete API l'accesso.
Passaggio 2: Richiedi il token
Passa una richiesta di token con il JSON client preferito. Al momento della creazione della richiesta:
- Utilizza un POST metodo per chiamare https://api.demdex.com/oauth/token .
- Converti l'ID client e il segreto in una stringa con codifica base 64. Separate l’ID e il segreto con due punti durante il processo di conversione. Ad esempio, le credenziali testId : testSecret vengono convertite in dGVzdElkOnRlc3RTZWNyZXQ= .
- Passa in HTTP e headers Authorization:Basic <base-64 clientID:clientSecret> Content-Type: application/x-www-form-urlencoded . Ad esempio, l’intestazione potrebbe essere simile al seguente:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=Content-Type: application/x-www-form-urlencoded
- Impostate il corpo della richiesta come segue:grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
Passaggio 3: Ricevere il token
La JSON risposta 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
expires_in
chiave rappresenta il numero di secondi fino alla scadenza del token di accesso. Come procedura ottimale, utilizzate brevi tempi di scadenza per limitare l'esposizione se il token è mai esposto.
Aggiorna token
Aggiorna token: API l'accesso viene rinnovato dopo la scadenza del token originale. Se richiesto, la risposta JSON nel flusso di lavoro della password include un token di aggiornamento. Se non ricevete un token di aggiornamento, createne uno nuovo tramite il processo di autenticazione tramite password.
Potete inoltre utilizzare un token di aggiornamento per generare un nuovo token prima della scadenza del token di accesso esistente.
Se il token di accesso è scaduto, nella risposta riceverete una
401 Status Code
e la seguente intestazione:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
Nei passaggi seguenti viene delineato il flusso di lavoro per l’utilizzo di un token di aggiornamento per creare un nuovo token di accesso da un JSON client nel browser.
Passaggio 1: Richiedi il nuovo token
Passa una richiesta di aggiornamento token con il JSON client preferito. Al momento della creazione della richiesta:
- Utilizza un POST metodo per chiamare https://api.demdex.com/oauth/token .
- Converti l'ID client e il segreto in una stringa con codifica base 64. Separate l’ID e il segreto con due punti durante il processo di conversione. Ad esempio, le credenziali testId : testSecret vengono convertite in dGVzdElkOnRlc3RTZWNyZXQ= .
- Trasmettere le intestazioni Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Ad esempio, l’intestazione potrebbe essere simile al seguente:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=Content-Type: application/x-www-form-urlencoded
- Nel corpo della richiesta, specificate il token di aggiornamento grant_type:refresh_token e trasmettetelo 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: Ricevi il nuovo token
La JSON risposta 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 file REST API supporta il codice di autorizzazione e l'autenticazione implicita. Per utilizzare questi metodi di accesso, gli utenti devono effettuare l'accesso per
https://api.demdex.com/oauth/authorize
ottenere l'accesso e aggiornare i token.
Rendi API richieste autenticate
Requisiti per i API metodi di chiamata dopo la ricezione di un token di autenticazione.
Per effettuare chiamate ai API metodi disponibili:
- Nell’ HTTP intestazione, impostate Authorization: Bearer <token> .
- Quando si utilizza l'autenticazione JWT (Service AccountAutenticazione tramite I/O Adobe JWT (Service Account), è necessario fornire l' x-api-key intestazione, che sarà la stessa dell' client_id utente. Puoi ottenere informazioni client_id dalla pagina di integrazione I/O di Adobe.
- Chiama il API metodo richiesto.
Parametri API query opzionali
Impostare i parametri facoltativi disponibili per i metodi che restituiscono tutte le proprietà di un oggetto.
È possibile utilizzare questi parametri facoltativi con API metodi che restituiscono
tutte
le proprietà di un oggetto. Impostate queste opzioni nella stringa di richiesta quando la query viene passata alla API.
Parametro
| Descrizione
|
|---|---|
page
| Restituisce i risultati per numero di pagina. La numerazione inizia da 0.
|
pageSize
| Imposta il numero di risultati della risposta restituiti dalla richiesta (il valore predefinito è 10).
|
sortBy
| Ordina e restituisce i risultati in base alla JSON proprietà specificata.
|
descending
|
Ordina e restituisce 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 si desideri trovare risultati per tutti i modelli con la parola "Test" in uno qualsiasi dei campi di valore per l'elemento. Esempio di richiesta:
GET https://aam.adobe.io/v1/models/?search=Test
. È possibile cercare qualsiasi valore restituito da un metodo "get all".
|
folderId
| Restituisce tutti gli ID per traits l’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:
Specificate più autorizzazioni con coppie chiave-valore separate. Ad esempio, per restituire un elenco di segmenti con
READ
e
WRITE
autorizzazioni, passate in
"permissions":"READ"
,
"permissions":"WRITE"
.
|
includePermissions
|
(Boolean) Impostate questa opzione
true
per restituire le autorizzazioni per il segmento. Il valore predefinito è
false
.
|
Una Nota Sulle Opzioni Pagina
Quando le informazioni sulla pagina non
sono
specificate, la richiesta restituisce JSON risultati semplici in un array. Se
sono
specificate le informazioni sulla pagina, l'elenco restituito viene racchiuso in un JSON oggetto che contiene informazioni sul risultato totale e sulla pagina corrente. La richiesta di esempio con le opzioni di pagina potrebbe essere simile alla 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 è riportata la richiesta URLs utilizzata per trasmettere API le richieste, per metodo.
A seconda del metodo di autenticazione utilizzato, è necessario regolare la richiesta URLs in base alle tabelle riportate di seguito.
Richiesta URLs di JWT autenticazione
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 OAuth autenticazione (obsoleto)
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
Gli Audience Manager strumenti APIconsentono l'accesso a diversi ambienti di lavoro. Questi ambienti consentono di sottoporre a test il codice su database separati senza influire sui dati live di produzione. Nella tabella seguente sono elencati gli API ambienti 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 JWT l'autenticazione
| Nome host per OAuth l'autenticazione
|
|---|---|---|
Produzione
| https://aam.adobe.io/...
| https://api.demdex.com/...
|
Beta
| https://aam-beta.adobe.io/...
| https://api-beta.demdex.com/...
|
L'ambiente Audience Manager beta è una versione autonoma e su scala ridotta dell'ambiente di produzione. Tutti i dati da sottoporre a test devono essere immessi e raccolti in questo ambiente.
Versioni
Le nuove versioni APIvengono rilasciate secondo una pianificazione regolare. Con una nuova versione viene incrementato il numero di API versione. Nella richiesta viene fatto riferimento al numero di versione URL come
v<version number>
illustrato nell’esempio seguente:
https://<host>/v1/...
Codici di risposta definiti
HTTP
i codici di stato e il testo della risposta restituiti dal REST API.
ID codice di risposta
| Testo della 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 per
PUT
e
POST
le richieste.
|
204
| No Content
| La risorsa è stata eliminata. Il corpo della risposta sarà vuoto.
|
400
| Bad Request
| Il server non ha capito la richiesta. Solitamente a causa di sintassi non corretta. Controlla la richiesta e riprova.
|
403
| Forbidden
| Non si dispone dell'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
| Il server ha rilevato un errore imprevisto che gli ha impedito di soddisfare la richiesta.
|