Guida introduttiva REST APIs

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

Raccomandazioni e requisiti per l’utilizzo delle API

Cose che devi e devi fare quando lavori con il Audience Manager APIs.

Quando si lavora con , tieni presente quanto segue API Audience Manager codice:

• Parametri di richiesta: tutti i parametri di richiesta sono richiesti, salvo diversa indicazione.
• Intestazioni di richiesta: quando utilizzi Adobe Developer token, devi fornire x-api-key intestazione. Potete ottenere il vostro API seguendo le istruzioni contenute in Integrazione dell'account di servizio pagina.
• JSONtipo di contenuto: Specifica content-type: application/json e accept: application/json nel codice.
• Richieste e risposte: Invia richieste come formattate correttamente JSON oggetto. Audience Manager risponde con JSON dati formattati. Le risposte del server possono contenere dati richiesti, un codice di stato o entrambi.
• Accesso: Le Audience Manager il consulente ti fornirà un ID cliente e una chiave che ti consentono di creare API richieste.
• Documentazione ed esempi di codice: Testo in corsivo rappresenta una variabile fornita o passata durante la creazione o la ricezione API dati. Sostituisci corsivo testo con codice, parametri o altre informazioni richieste.

Autenticazione

La Audience Manager REST APIs supportano due metodi di autenticazione.

• Autenticazione JWT (account di servizio) utilizzo Adobe Developer. Adobe Developer è l'ecosistema e la comunità di sviluppatori di Adobe. Include API per tutti i prodotti Adobe. Questo è il modo consigliato per configurare e utilizzare Adobe APIs.
• Autenticazione OAuth (obsoleta). Anche se questo metodo è obsoleto, i clienti con OAuth le integrazioni possono continuare a utilizzare questo metodo.

JWT (Service Account) Autenticazione tramite Adobe Developer

Panoramica di Adobe Developer

Adobe Developer è l'ecosistema e la comunità di sviluppatori di Adobe. Include API per tutti i prodotti Adobe.

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

Prerequisiti

Prima di configurare JWT autenticazione, assicurati di avere accesso al Console Adobe Developer in Adobe Developer. Per le richieste di accesso, contatta l’amministratore dell’organizzazione.

Autenticazione

Segui i passaggi seguenti per configurare JWT (Service Account) autenticazione tramite Adobe Developer:

1. Accedi a Console Adobe Developer.
2. Segui i passaggi descritti in Connessione account di servizio.
   • Periodo Passaggio 2: Aggiungere un’API al progetto utilizzando l’autenticazione dell’account di servizio, scegli Audience Manager API opzione .
3. Prova la connessione facendo il tuo primo API in base alle istruzioni fornite da Passaggio 3.

Autorizzazioni RBAC dell'account tecnico

Se il tuo account di Audience Manager utilizza Controllo degli accessi basato sul ruolo, devi creare un account utente tecnico di 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. Crea un GET chiamare a https://aam.adobe.io/v1/users/self. La chiamata crea un account utente tecnico visibile nella Admin Console, nella Users pagina.

   

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

OAuth Autenticazione (obsoleta)

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

Creare un generico API Utente

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

• Identifica il servizio che chiama il API (ad esempio, chiamate dalle tue app che utilizzano il nostro APIs o da altri strumenti API richieste).
• Fornire un accesso ininterrotto ai APIs. Un account associato a una persona specifica può essere cancellato quando lascia la tua azienda. In questo modo non sarà più possibile utilizzare le API codice. Un account generico non legato a un particolare dipendente ti aiuta a evitare questo problema.

Ad esempio, per questo tipo di account, supponiamo che desideri cambiare un sacco di segmenti contemporaneamente con il 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 API account utente con le credenziali, la chiave e il segreto appropriati da creare API chiamate. Questa funzione è utile anche se si sviluppano applicazioni personalizzate che utilizzano Audience Manager APIs.

Lavora con il tuo Audience Manager consulente per la creazione di un generico, API- solo account utente.

Flusso di lavoro di autenticazione della password

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

Passaggio 1: Richiesta API Accesso

Contatta il tuo Partner Solutions Manager. Ti forniranno un API ID client e segreto. L’ID e il segreto dell’autenticazione ti consentono di API.

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

Passaggio 2: Richiedere il token

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

• Utilizza un POST metodo di chiamata 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 convertire in dGVzdElkOnRlc3RTZWNyZXQ=.
• Passa la 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 JSON La 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 key 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

Rinnova token API accesso dopo la scadenza del token originale. Se richiesto, la risposta JSON nel flusso di lavoro 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 JSON nel browser.

Passaggio 1: Richiedere il nuovo token

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

• Utilizza un POST metodo di chiamata 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 convertire 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 il grant_type:refresh_token e passare 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 JSON La 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

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

Rendi autenticato API Richieste

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

Per effettuare chiamate contro disponibili API metodi:

• In HTTP header, set Authorization: Bearer <token>.
• Quando utilizzi Autenticazione JWT (account di servizio), devi fornire x-api-key intestazione, che sarà la stessa del tuo client_id. Potete ottenere il vostro client_id dal Integrazione Adobe Developer pagina.
• Richiama API metodo .

Facoltativo API Parametri query

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

Puoi utilizzare questi parametri facoltativi con API metodi che restituiscono tutto proprietà di un oggetto. Imposta queste opzioni nella stringa di richiesta quando trasmetti la query al API.

Nota sulle opzioni di pagina

Quando le informazioni sulla pagina non specificato, la richiesta restituisce normale JSON restituisce un array. Se le informazioni sulla pagina è specificato, l’elenco restituito viene racchiuso in un JSON oggetto 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 usato per passare API richieste, per metodo.

A seconda del metodo di autenticazione utilizzato, è necessario regolare la richiesta URLs secondo le tabelle seguenti.

Richiesta URLs per JWT Autenticazione

Richiesta URLs per OAuth Autenticazione (obsoleta)

Ambienti

La 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 i API ambienti e nomi host delle risorse corrispondenti.

A seconda del metodo di autenticazione utilizzato, è necessario regolare l’ambiente URLs secondo la tabella seguente.

Versioni

Nuove versioni di questi APIvengono rilasciati regolarmente. Una nuova versione incrementa il API numero di versione. Nella richiesta viene fatto riferimento al numero di versione URL come v<version number> come mostrato nell’esempio seguente:

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

Codici di risposta definiti

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

Risorse Business.Adobe.com

Third Party Integrations Third Party Data Customer Journey Analytics Mobile Analytics Audience Segmentation General Data Protection Regulation