Guida introduttiva a REST APIs getting-started-with-rest-apis
Informazioni su requisiti generali, autenticazione, parametri di query facoltativi, richiesta URLs e altri riferimenti.
Requisiti API e Recommendations api-requirements-recommendations
Quando si lavora con il codice Audience Manager API, tieni presente quanto segue:
- Parametri di richiesta: tutti i parametri di richiesta sono obbligatori se non specificato diversamente.
- Intestazioni richiesta: quando utilizzi token Adobe Developer, devi fornire l'intestazione
x-api-key
. Puoi ottenere la tua chiave API seguendo le istruzioni riportate nella pagina Integrazione account di servizio. - Tipo di contenuto JSON: Specificare
content-type: application/json
eaccept: application/json
nel codice. - Richieste e risposte: Inviare richieste come oggetto JSON formattato correttamente. Audience Manager risponde con JSON dati formattati. Le risposte del server possono contenere i dati richiesti, un codice di stato o entrambi.
- Accesso: Il consulente Audience Manager ti fornirà un ID client e una chiave che ti consente di effettuare API richieste.
- Esempi di documentazione e codice: Il testo in corsivo rappresenta una variabile fornita o trasmessa quando si creano o si ricevono dati API. Sostituisci il testo in corsivo con il tuo codice, i tuoi parametri o altre informazioni richieste.
Autenticazione authentication
Audience Manager REST APIs supporta tre metodi di autenticazione.
- [Consigliato]{class="badge positive"}Autenticazione server-to-server OAuth tramite Adobe Developer Console. Adobe Developer è l'ecosistema di sviluppatori e la community di Adobe. Include API per tutti i prodotti Adobe. Si tratta del metodo consigliato per impostare e utilizzare Adobe APIs. Per ulteriori informazioni sull'autenticazione server-to-server OAuth, consulta la documentazione per gli sviluppatori di Adobe.
- [Obsoleto]{class="badge negative"}Autenticazione JWT (account di servizio) tramite Adobe Developer Console. Adobe Developer è l'ecosistema di sviluppatori e la community di Adobe. Include API per tutti i prodotti Adobe.
- [Obsoleto]{class="badge negative"}Autenticazione OAuth legacy. Anche se questo metodo è obsoleto, i clienti con integrazioni OAuth esistenti possono continuare a utilizzarlo.
Autenticazione server-to-server OAuth tramite Adobe Developer oauth-adobe-developer
Questa sezione illustra come raccogliere le credenziali necessarie per autenticare le chiamate API Audience Manager, come descritto nel diagramma di flusso seguente. È possibile raccogliere la maggior parte delle credenziali richieste nella configurazione iniziale una tantum. Il token di accesso, tuttavia, deve essere aggiornato ogni 24 ore.
Panoramica di Adobe Developer developer-overview
Adobe Developer è l'ecosistema di sviluppatori e la community di Adobe. Include API per tutti i prodotti Adobe.
Si tratta del metodo consigliato per impostare e utilizzare Adobe APIs.
Prerequisiti prerequisites-server-to-server
Prima di configurare l'autenticazione di OAuth Server-to-Server, verificare di avere accesso a Adobe Developer Console in Adobe Developer. Contatta l’amministratore dell’organizzazione per le richieste di accesso.
Autenticazione oauth
Per configurare l'autenticazione di OAuth Server-to-Server tramite Adobe Developer, attenersi alla procedura seguente:
- Accedi a Adobe Developer Console.
- Segui i passaggi descritti nella Guida all'implementazione delle credenziali server-to-server OAuth.
- Durante il passaggio 2: aggiungi un'API al progetto utilizzando l'autenticazione dell'account di servizio, scegli l'opzione Audience Manager API.
- Provare la connessione effettuando la prima chiamata API in base alle istruzioni del passaggio 3.
Aggiungere l’API Audience Manager a un progetto add-aam-api-to-project
Vai a Adobe Developer Console e accedi con il tuo Adobe ID. Quindi, segui i passaggi descritti nel tutorial su creazione di un progetto vuoto nella documentazione di Adobe Developer Console.
Dopo aver creato un nuovo progetto, selezionare Add API nella schermata Project Overview.
Viene visualizzata la schermata Add an API. Selezionare l'icona del prodotto per Adobe Experience Cloud, quindi scegliere Audience Manager API prima di selezionare Next.
Seleziona il tipo di autenticazione server-to-server OAuth select-oauth-server-to-server
Quindi, seleziona il tipo di autenticazione per generare token di accesso e accedere all’API Audience Manager.
Selezionare i profili di prodotto per l’integrazione select-product-profiles
Nella schermata Configure API, selezionare i profili di prodotto desiderati. L’account di servizio della tua integrazione potrà accedere a funzioni granulari tramite i profili di prodotto selezionati qui.
Selezionare Save configured API quando si è pronti.
Raccogli le credenziali gather-credentials
Una volta aggiunta l'API al progetto, nella pagina Audience Manager API per il progetto vengono visualizzate le credenziali seguenti, necessarie in tutte le chiamate alle API Audience Manager:
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)
Generare un token di accesso generate-access-token
Il passaggio successivo consiste nel generare una credenziale {ACCESS_TOKEN}
da utilizzare nelle chiamate API Audience Manager. A differenza dei valori per {API_KEY}
e {ORG_ID}
, è necessario generare un nuovo token ogni 24 ore per continuare a utilizzare le API Audience Manager. Selezionare Generate access token, come illustrato di seguito.
Testare una chiamata API test-api-call
Dopo aver ottenuto il token Bearer di autenticazione, esegui una chiamata API per verificare che ora puoi accedere alle API Audience Manager.
-
Passa alla documentazione di riferimento API.
-
Selezionare Authorize e incollare il token di accesso ottenuto nel passaggio genera token di accesso.
-
Eseguire una chiamata GET all'endpoint API
/datasources
per recuperare un elenco di tutte le origini dati disponibili a livello globale, come indicato nella documentazione di riferimento API. Selezionare Try it out, seguito da Execute, come illustrato di seguito.
code language-shell |
---|
|
Quando utilizzi un token di accesso funzionante, l’endpoint API restituisce una risposta 200 insieme a un corpo di risposta che include tutte le origini dati globali a cui l’organizzazione ha accesso.
code language-json |
---|
|
[Obsoleto]{class="badge negative"}Autenticazione di JWT (Service Account) tramite Adobe Developer jwt
Panoramica di Adobe Developer adobeio
Adobe Developer è l'ecosistema di sviluppatori e la community di Adobe. Include API per tutti i prodotti Adobe.
Si tratta del metodo consigliato per impostare e utilizzare Adobe APIs.
Prerequisiti prerequisites
Prima di configurare l'autenticazione di JWT, verificare di avere accesso a Adobe Developer Console in Adobe Developer. Contatta l’amministratore dell’organizzazione per le richieste di accesso.
Autenticazione auth
Per configurare l'autenticazione di JWT (Service Account) tramite Adobe Developer, attenersi alla procedura seguente:
- Accedi a Adobe Developer Console.
- Segui i passaggi descritti in Connessione account di servizio.
- Durante il passaggio 2: aggiungi un'API al progetto utilizzando l'autenticazione dell'account di servizio, scegli l'opzione Audience Manager API.
- Provare la connessione effettuando la prima chiamata API in base alle istruzioni del passaggio 3.
note note |
---|
NOTE |
Per configurare e utilizzare Audience Manager REST APIs in modo automatico, è possibile generare JWT a livello di programmazione. Per istruzioni dettagliate, consulta Autenticazione JWT (account di servizio). |
Autorizzazioni RBAC dell’account tecnico
Se l'account Audience Manager utilizza Controllo degli accessi basato sul ruolo, è necessario creare un account utente tecnico Audience Manager e aggiungerlo al gruppo RBAC Audience Manager che effettuerà le chiamate API.
Per creare un account utente tecnico e aggiungerlo a un gruppo RBAC, effettua le seguenti operazioni:
-
Effettuare una chiamata
GET
ahttps://aam.adobe.io/v1/users/self
. La chiamata creerà un account utente tecnico visibile in Admin Console, nella pagina Users. -
Accedi al tuo account Audience Manager e aggiungi l'account utente tecnico al gruppo di utenti che effettuerà le chiamate API.
[Obsoleto]{class="badge negative"}Autenticazione OAuth (obsoleto) oauth-deprecated
note warning |
---|
WARNING |
L'autenticazione e il rinnovo del token Audience Manager REST API tramite OAuth 2.0 sono ora obsoleti. |
Utilizza invece l'autenticazione JWT (account di servizio). |
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 API.
Crea un utente API generico requirements
È consigliabile creare un account utente tecnico separato per l'utilizzo di Audience Manager API. Si tratta di un account generico non associato o associato a un utente specifico dell’organizzazione. Questo tipo di account utente API consente di eseguire 2 operazioni:
- Identifica il servizio che chiama API (ad esempio, chiamate dalle app che utilizzano API o da altri strumenti che effettuano API richieste).
- Fornisci accesso ininterrotto a API. Un account associato a una persona specifica può essere cancellato quando lascia la tua azienda. In questo modo non sarà possibile utilizzare il codice API disponibile. Un account generico non legato a un dipendente specifico consente di evitare questo problema.
Come esempio o caso d'uso per questo tipo di account, supponiamo che si desideri modificare molti segmenti contemporaneamente con i Strumenti di gestione in blocco. Bene, per fare questo, il tuo account utente ha bisogno dell'accesso a API. Anziché aggiungere le autorizzazioni a un utente specifico, creare un account utente API non specifico con credenziali, chiave e segreto appropriati per effettuare chiamate a API. Questa funzione è utile anche se si sviluppano applicazioni personalizzate che utilizzano Audience Manager API.
Rivolgiti al tuo consulente Audience Manager per configurare un account utente generico di API.
Flusso di lavoro di autenticazione password password-authentication-workflow
Autenticazione password accesso sicuro REST API. I passaggi seguenti descrivono il flusso di lavoro per l'autenticazione tramite password da un client JSON nel browser.
note tip |
---|
TIP |
Crittografare i token di accesso e di aggiornamento se vengono memorizzati in un database. |
Passaggio 1: richiesta dell'accesso API
Contatta il tuo Partner Solutions Manager. Ti forniranno un ID client API e un segreto. L'ID e il segreto ti autenticano in API.
Nota: se si desidera ricevere un token di aggiornamento, specificarlo quando si richiede l'accesso API.
Passaggio 2: richiedere il token
Trasmettere una richiesta token con il client JSON preferito. Quando crei la richiesta:
- Utilizzare un metodo
POST
per chiamarehttps://api.demdex.com/oauth/token
. - Converti l’ID client e il segreto in una stringa con codifica base 64. Durante il processo di conversione, separa l’ID e il segreto con due punti. Ad esempio, le credenziali
testId : testSecret
vengono convertite indGVzdElkOnRlc3RTZWNyZXQ=
. - Passa HTTP headers
Authorization:Basic <base-64 clientID:clientSecret>
eContent-Type: application/x-www-form-urlencoded
. Ad esempio, l'intestazione potrebbe essere simile alla 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 di JSON contiene il token di accesso. La risposta deve essere simile alla seguente:
code language-json |
---|
|
La chiave expires_in
rappresenta il numero di secondi rimanenti alla scadenza del token di accesso. Come best practice, utilizza tempi di scadenza brevi per limitare l’esposizione se il token viene mai esposto.
Aggiorna token refresh-token
Aggiorna i token per rinnovare 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, nella risposta riceverai un 401 Status Code
e la seguente intestazione:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
I passaggi seguenti descrivono 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: richiesta del nuovo token
Trasmettere una richiesta di token di aggiornamento con il client JSON preferito. Quando crei la richiesta:
- Utilizzare un metodo
POST
per chiamarehttps://api.demdex.com/oauth/token
. - Converti l’ID client e il segreto in una stringa con codifica base 64. Durante il processo di conversione, separa l’ID e il segreto con due punti. Ad esempio, le credenziali
testId : testSecret
vengono convertite indGVzdElkOnRlc3RTZWNyZXQ=
. - Passa le intestazioni HTTP
Authorization:Basic <base-64 clientID:clientSecret>
eContent-Type: application/x-www-form-urlencoded
. Ad esempio, l'intestazione potrebbe essere simile alla 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 di JSON contiene il nuovo token di accesso. La risposta deve essere simile alla seguente:
code language-json |
---|
|
Codice di autorizzazione e autenticazione implicita authentication-code-implicit
Audience Manager REST API supporta codice di autorizzazione e autenticazione implicita. Per utilizzare questi metodi di accesso, gli utenti devono accedere a https://api.demdex.com/oauth/authorize
per accedere e aggiornare i token.
Effettua API richieste autenticate authenticated-api-requests
Requisiti per la chiamata dei metodi API dopo la ricezione di un token di autenticazione.
Per effettuare chiamate ai metodi API disponibili:
- Nell'intestazione
HTTP
, impostareAuthorization: Bearer <token>
. - Quando si utilizza l'autenticazione JWT (account di servizio), è necessario fornire l'intestazione
x-api-key
, che sarà la stessa diclient_id
. Puoi ottenereclient_id
dalla pagina Integrazione Adobe Developer. - Chiama il metodo API richiesto.
Parametri query API facoltativi optional-api-query-parameters
Impostare i parametri facoltativi disponibili per i metodi che restituiscono tutte le proprietà di un oggetto.
È possibile utilizzare questi parametri facoltativi con i metodi API che restituiscono tutte le proprietà di un oggetto. Impostare queste opzioni nella stringa di richiesta quando si trasmette la query a API.
page
pageSize
sortBy
descending
ascending
è predefinito.search
GET https://aam.adobe.io/v1/models/?search=Test
. È possibile eseguire ricerche in base a qualsiasi valore restituito da un metodo "get all".folderId
permissions
Restituisce un elenco di segmenti in base all’autorizzazione specificata. READ
è predefinito. Le autorizzazioni includono:
READ
: restituisce e visualizza informazioni su un segmento.WRITE
: utilizzarePUT
per aggiornare un segmento.CREATE
: utilizzaPOST
per creare un segmento.DELETE
: elimina un segmento. Richiede l’accesso alle caratteristiche sottostanti, se presenti. Ad esempio, per rimuoverlo, dovrai disporre dei diritti necessari per eliminare le caratteristiche che appartengono a un segmento.
Specificare più autorizzazioni con coppie chiave-valore separate. Ad esempio, per restituire un elenco di segmenti con solo le autorizzazioni READ
e WRITE
, passare in "permissions":"READ"
, "permissions":"WRITE"
.
includePermissions
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 JSON come risultato normale in un array. Se sono state specificate le informazioni di pagina is, l'elenco restituito verrà racchiuso in un oggetto JSON contenente informazioni sul risultato totale e sulla pagina corrente. Un esempio di richiesta tramite le opzioni di pagina potrebbe essere simile al seguente:
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
API URLs api-urls
URLs per richieste, ambienti di staging e produzione e versioni.
Richiedi URLs request-urls
Nella tabella seguente sono elencate le richieste URLs utilizzate per trasmettere API richieste, per metodo.
A seconda del metodo di autenticazione utilizzato, è necessario modificare la richiesta URLs in base alle tabelle seguenti.
Richiedi URLs per [Consigliato]{class="badge positive"}[Obsoleto]{class="badge negative"}Autenticazione di JWT tramite Adobe Developer request-urls-jwt
https://aam.adobe.io/v1/models/
https://aam.adobe.io/v1/datasources/
https://aam.adobe.io/v1/signals/derived/
https://aam.adobe.io/v1/destinations/
https://aam.adobe.io/v1/partner-sites/
https://aam.adobe.io/v1/folders/traits /
Segmenti:
https://aam.adobe.io/v1/folders/segments /
https://aam.adobe.io/v1/schemas/
https://aam.adobe.io/v1/segments/
https://aam.adobe.io/v1/traits/
https://aam.adobe.io/v1/customer-trait-types
https://aam.adobe.io/v1/taxonomies/0/
Richiedi URLs per [Obsoleto]{class="badge negative"}Autenticazione OAuth request-urls-oauth
https://api.demdex.com/v1/models/
https://api.demdex.com/v1/datasources/
https://api.demdex.com/v1/signals/derived/
https://api.demdex.com/v1/destinations/
https://api.demdex.com/v1/partner-sites/
https://api.demdex.com/v1/folders/traits /
Segmenti:
https://api.demdex.com/v1/folders/segments /
https://api.demdex.com/v1/schemas/
https://api.demdex.com/v1/segments/
https://api.demdex.com/v1/traits/
https://api.demdex.com/v1/customer-trait-types
https://api.demdex.com/v1/taxonomies/0/
Ambienti environments
I Audience Manager API forniscono l'accesso a diversi ambienti di lavoro. Questi ambienti consentono di testare il codice su database separati senza influire sui dati live e di produzione. Nella tabella seguente sono elencati gli ambienti API disponibili e i nomi host delle risorse corrispondenti.
A seconda del metodo di autenticazione utilizzato, è necessario modificare l'ambiente URLs in base alla tabella seguente.
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
Versioni versions
Le nuove versioni di questi API vengono rilasciate regolarmente. Una nuova versione incrementa il numero di versione API. Nella richiesta URL viene fatto riferimento al numero di versione come v<version number>
, come illustrato nell'esempio seguente:
https://<host>/v1/...
Codici di risposta definiti response-codes-defined
HTTP
codici di stato e testo di risposta restituiti da Audience Manager REST API.
200
OK
201
Created
PUT
e POST
richieste.204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error