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 Sviluppatore Adobe 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.

IMPORTANTE

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 Account) Autenticazione tramite Adobe Developer

Panoramica per gli sviluppatori di Adobe

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 per sviluppatori di Adobe in Sviluppatore Adobe. 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 per sviluppatori di Adobe.
  2. Segui i passaggi descritti in Connessione account di servizio.
  3. Prova la connessione facendo il tuo primo API in base alle istruzioni fornite da Passaggio 3.
NOTA

Per configurare e utilizzare Audience Manager REST APIs in modo automatizzato, puoi generare il JWT programmaticamente. Vedi Autenticazione JWT (account di servizio) per istruzioni dettagliate.

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.

    conto tecnico

  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)

AVVERTENZA

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

Utilizzare Autenticazione JWT (account di servizio) invece.

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.

SUGGERIMENTO

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

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:

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.

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 al valore specificato JSON proprietà.
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 "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 : Utilizzo PUT per aggiornare un segmento.
  • CREATE : Utilizzo 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 con READ e WRITE solo autorizzazioni, passare "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 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

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 per OAuth Autenticazione (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

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.

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

La Audience Manager l’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

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.

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 per PUT e POST richieste.
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