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 e accept: 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.

IMPORTANT
A seconda del metodo di autenticazione utilizzato, è necessario modificare di conseguenza la richiesta URLs. Consulta la sezione Ambienti per informazioni dettagliate sui nomi host da utilizzare.

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.

Audience Manager diagramma del flusso di autenticazione.

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:

  1. Accedi a Adobe Developer Console.
  2. Segui i passaggi descritti nella Guida all'implementazione delle credenziali server-to-server OAuth.
  3. Provare la connessione effettuando la prima chiamata API in base alle istruzioni del passaggio 3.
NOTE
Per configurare e utilizzare Audience Manager REST APIs in modo automatico, è possibile ruotare i segreti client a livello di programmazione. Per istruzioni dettagliate, consulta la documentazione per gli sviluppatori.

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.

TIP
Se disponi del provisioning per più organizzazioni, utilizza il selettore organizzazione nell’angolo superiore destro dell’interfaccia per assicurarti di essere nell’organizzazione necessaria.

Schermata Developer Console con lopzione Aggiungi API evidenziata.

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 API Audience Manager.

TIP
Seleziona l'opzione View docs per passare in una finestra del browser separata alla documentazione di riferimento dell'API Audience Manager completa.

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.

IMPORTANT
Selezionare il metodo OAuth Server-to-Server in quanto questo sarà l'unico metodo supportato per gli spostamenti in avanti. Metodo Service Account (JWT) obsoleto. Anche se le integrazioni che utilizzano il metodo di autenticazione JWT continueranno a funzionare fino al 1° gennaio 2025, Adobe consiglia vivamente di migrare le integrazioni esistenti al nuovo metodo server-to-server OAuth prima di tale data.

Seleziona metodo di autenticazione OAuth.

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.

Seleziona i profili di prodotto per la tua integrazione.

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:

Informazioni sullintegrazione dopo laggiunta di unAPI in Developer Console.

  • {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.

Mostra come generare il token di accesso

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.

  1. Passa alla documentazione di riferimento API.

  2. Selezionare Authorize e incollare il token di accesso ottenuto nel passaggio genera token di accesso.

    Autorizza chiamate API

  3. 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.

    Esecuzione chiamate API

recommendation-more-help
Richiesta API
code language-shell
curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'
Risposta API in caso di utilizzo del token Bearer corretto

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
[
  {
    "pid": 1794,
    "name": "testdatasource1",
    "description": "Test data source",
    "status": "ACTIVE",
    "integrationCode": "test_ds1",
    "dataExportRestrictions": [],
    "updateTime": 1595340792000,
    "crUID": 0,
    "upUID": 15910,
    "linkNamespace": false,
    "type": "GENERAL",
    "subIdType": "CROSS_DEVICE_PERSON",
    "inboundS2S": true,
    "outboundS2S": true,
    "useAudienceManagerVisitorID": false,
    "allowDataSharing": true,
    "masterDataSourceIdProvider": true,
    "uniqueTraitIntegrationCodes": false,
    "uniqueSegmentIntegrationCodes": false,
    "marketingCloudVisitorIdVersion": 0,
    "idType": "CROSS_DEVICE",
    "samplingEndTime": 1596550392825,
    "allowDeviceGraphSharing": false,
    "supportsAuthenticatedProfile": true,
    "deviceGraph": false,
    "authenticatedProfileName": "testdatasource1",
    "deviceGraphName": "",
    "customNamespaceId": 29769,
    "customNamespaceCode": "silviu_ds1",
    "customerProfileDataRetention": 62208000,
    "samplingStartTime": 1595340792825,
    "dataSourceId": 29769,
    "containerIds": [],
    "samplingEnabled": false
  },
  {
    "pid": 1794,
    "name": "AAM Test Company Audiences",
    "description": "Automatically generated trait data source",
    "status": "ACTIVE",
    "integrationCode": "adobe-provided",
    "dataExportRestrictions": [
      "PII"
    ],

    [...]

[Obsoleto]{class="badge negative"}Autenticazione di JWT (Service Account) tramite Adobe Developer jwt

Visualizza informazioni sul metodo JWT (Service Account) obsoleto per ottenere i token di autenticazione.

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:

  1. Accedi a Adobe Developer Console.
  2. Segui i passaggi descritti in Connessione account di servizio.
  3. 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:

  1. Effettuare una chiamata GET a https://aam.adobe.io/v1/users/self. La chiamata creerà un account utente tecnico visibile in Admin Console, nella pagina Users.

    account tecnico

  2. 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

Visualizza informazioni sul metodo di autenticazione legacy OAuth obsoleto per ottenere i token di autenticazione.
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 chiamare https://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 in dGVzdElkOnRlc3RTZWNyZXQ=.
  • Passa HTTP headers Authorization:Basic <base-64 clientID:clientSecret> e Content-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
{
    "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 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 chiamare https://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 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 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
{
    "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 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, impostare Authorization: Bearer <token>.
  • Quando si utilizza l'autenticazione JWT (account di servizio), è necessario fornire l'intestazione x-api-key, che sarà la stessa di client_id. Puoi ottenere client_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.

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 è il valore predefinito).
sortBy
Ordina e restituisce i risultati in base alla proprietà JSON specificata.
descending
Ordina e restituisce i risultati in ordine decrescente. ascending è predefinito.
search
Restituisce risultati in base alla stringa specificata che si desidera utilizzare come parametro di ricerca. Ad esempio, supponiamo che si desideri trovare i risultati per tutti i modelli che hanno 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. È possibile eseguire ricerche in base a qualsiasi valore restituito da un metodo "get all".
folderId
Restituisce tutti gli ID per traits all'interno della cartella specificata. Non disponibile per tutti i metodi.
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: utilizzare 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, 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
(Boolean) Impostare 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 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

Metodi API
Richiedi 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/

Richiedi URLs per [Obsoleto]{class="badge negative"}Autenticazione OAuth request-urls-oauth

Metodi API
Richiedi 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 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.

Ambiente
Nome host per autenticazione JWT
Nome host per autenticazione OAuth
Produzione
https://aam.adobe.io/...
https://api.demdex.com/...
Beta
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
NOTE
L'ambiente beta Audience Manager è una versione standalone su scala ridotta dell'ambiente di produzione. Tutti i dati che desideri verificare devono essere immessi e raccolti in questo ambiente.

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.

ID codice di risposta
Testo di risposta
Definizione
200
OK
Richiesta elaborata correttamente. Se necessario, restituirà il contenuto o i dati previsti.
201
Created
La risorsa è stata creata. Restituisce per PUT e POST richieste.
204
No Content
Risorsa eliminata. Il corpo della risposta sarà vuoto.
400
Bad Request
Il server non ha compreso la richiesta. Di solito a causa di sintassi non valida. Verifica 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
Il server ha rilevato un errore imprevisto che ha impedito di soddisfare la richiesta.
de293fbf-b489-49b0-8daa-51ed303af695