Guida introduttiva di REST APIs

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

Raccomandazioni e requisiti per l’utilizzo delle API

Cose che è necessario e che è necessario fare quando si utilizzano gli Audience Manager APIs.

Tenete presente quanto segue quando lavorate con il codice API Audience Manager:

  • Parametri della richiesta: tutti i parametri della richiesta sono obbligatori, se non diversamente specificato.
  • Intestazioni richieste: quando utilizzate I/ Otokens Adobe, dovete fornire l’ x-api-key intestazione. È possibile ottenere la chiave API seguendo le istruzioni riportate nella pagina Integrazione dell'account di servizio.
  • JSONtipo di contenuto: specifica content-type: application/json ** accept: application/json e specifica il codice.
  • Richieste e risposte: invia le richieste come 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 che puoi fornire o trasmettere quando crei o ricevi API dati. Sostituire il testo in corsivo con codice, parametri o altre informazioni necessarie.

Autenticazione

Audience Manager REST APIs supporta due metodi di autenticazione.

IMPORTANTE

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

JWT (Service AccountAutenticazione tramite Adobe I/O

Panoramica Adobe I/O

Adobe I/O è Adobe ecosistema e comunità di sviluppatori. Include gli strumenti per sviluppatori di Adobi I/O e le API e API per tutti i prodotti Adobe.

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

Prerequisiti

Prima di poter configurare l'autenticazione JWT, assicurarsi di avere accesso alla Developer Console del Adobe in Adobe I/O. Contattate l’amministratore dell’organizzazione per le richieste di accesso.

Autenticazione

Seguite i passaggi indicati di seguito per configurare l'autenticazione JWT (Service Account) utilizzando Adobe I/O:

  1. Accedete alla Adobe Developer Console.
  2. Seguire i passaggi descritti in Connessione account di servizio.
  3. Prova la connessione effettuando la tua prima API chiamata in base alle istruzioni fornite dal Passaggio 3.
NOTA

Per configurare e utilizzare il Audience Manager REST APIs in modo automatico, è possibile generare il JWT a livello di programmazione. Per istruzioni dettagliate, vedere JWT (Service Account) Authentication.

OAuth Autenticazione (obsoleta)

AVVERTENZA

Audience Manager REST API l'autenticazione token e il rinnovo tramite OAuth 2.0 è ora obsoleto.

Utilizzare invece l'autenticazione JWT (Service Account).

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

Creare un utente API generico

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

  • Identificare quale servizio sta chiamando le API (ad esempio, chiamate dalle vostre app che utilizzano i nostri APIs o da altri strumenti che effettuano richieste API).
  • Fornire l'accesso ininterrotto alle APIs. Un account legato a una persona specifica può essere eliminato quando esce dalla società. In questo modo non sarà possibile utilizzare il codice API 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 si desideri cambiare un sacco di segmenti contemporaneamente con gli Strumenti di gestione di massa. Beh, per fare questo, il tuo account utente ha bisogno di API accesso. Invece di aggiungere autorizzazioni a un utente specifico, create un account utente API non specifico con le credenziali, la chiave e il segreto appropriati per effettuare chiamate API. Questo è utile anche se si sviluppano applicazioni personalizzate che utilizzano i Audience Manager APIs.

Consultate il vostro consulente Audience Manager per impostare un account utente generico, solo API.

Flusso di lavoro di autenticazione della password

Accesso protetto tramite autenticazione tramite password REST API. I passaggi riportati di seguito descrivono il flusso di lavoro per l'autenticazione tramite password da un client JSON nel browser.

SUGGERIMENTO

Cifra i token di accesso e di aggiornamento se li si archivia in un database.

Passaggio 1: Richiedi accessoAPI

Contatta il tuo Partner Solutions Manager. Forniranno un ID client API e un segreto. L'ID e il segreto vi autenticano nel percorso API.

Nota: Se desiderate ricevere un token di aggiornamento, specificatelo quando richiedete l'accesso a API.

Passaggio 2: Richiedi il token

Passa una richiesta di token con il client JSON preferito. Al momento della creazione della 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. Separate l’ID e il segreto con due punti durante il processo di conversione. Ad esempio, le credenziali testId : testSecret vengono convertite in dGVzdElkOnRlc3RTZWNyZXQ=.
  • Passare in HTTP headers 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
  • 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 risposta JSON 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 chiave expires_in 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

I token di aggiornamento rinnovano 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 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 un 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 client JSON nel browser.

Passaggio 1: Richiedi il nuovo token

Passa una richiesta di aggiornamento token con il client JSON preferito. Al momento della creazione della 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. 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 le intestazioni HTTP 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 grant_type:refresh_token e passate 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: Ricevi il nuovo token

La risposta JSON 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 REST API supporta il codice di autorizzazione e l'autenticazione implicita. Per utilizzare questi metodi di accesso, gli utenti devono accedere a https://api.demdex.com/oauth/authorize per ottenere l'accesso e aggiornare i token.

Richieste autenticate API

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

Per effettuare chiamate ai metodi API disponibili:

  • Nell'intestazione HTTP, impostare Authorization: Bearer <token>.
  • Quando si utilizza l'autenticazione JWT (Service Account), è necessario fornire l'intestazione x-api-key, che sarà uguale al client_id. È possibile ottenere il client_id dalla pagina integrazione Adobe I/O.
  • Chiama il metodo API richiesto.

Parametri di query API facoltativi

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

È possibile utilizzare questi parametri facoltativi con metodi API che restituiscono le proprietà all per un oggetto. Impostate queste opzioni nella stringa di richiesta quando passate la query in 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 proprietà JSON 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 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 : Utilizzare PUT per aggiornare un segmento.
  • CREATE : Utilizzare POST per creare un segmento.
  • DELETE : Elimina un segmento. Richiede l’accesso alle caratteristiche sottostanti, se presenti. Ad esempio, avrai bisogno di diritti per eliminare le caratteristiche che appartengono a un segmento se desideri rimuoverlo.

Specificate più autorizzazioni con coppie chiave-valore separate. Ad esempio, per restituire un elenco di segmenti con autorizzazioni solo READ e WRITE, passare "permissions":"READ", "permissions":"WRITE" .
includePermissions (Boolean) Impostare su true per restituire le autorizzazioni per il segmento. Il valore predefinito è false.

Una Nota Sulle Opzioni Pagina

Quando le informazioni di pagina non sono specificate, la richiesta restituisce un valore normale JSON restituisce un array. Se le informazioni di pagina è specificate, l'elenco restituito viene racchiuso in un oggetto JSON 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 è riportato l'elenco della richiesta URLs utilizzata per trasmettere le richieste API per metodo.

A seconda del metodo di autenticazione utilizzato, è necessario regolare la richiesta URLs in base alle tabelle riportate di seguito.

Richiesta di URLs autenticazione JWT

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 di URLs autenticazione OAuth (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

I Audience Manager APIs consentono 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 ambienti API 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 l'autenticazione JWT Nome host per l'autenticazione OAuth
Produzione https://aam.adobe.io/... https://api.demdex.com/...
Beta https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
NOTA

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 di questi APIs vengono rilasciate secondo una pianificazione regolare. Una nuova versione incrementa il numero di versione API. Il numero di versione è indicato nella richiesta URL come v<version number>, come illustrato nell'esempio seguente:

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

Codici di risposta definiti

HTTP i codici di stato e il testo della risposta restituiti dal Audience Manager 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 le richieste PUT e POST.
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.

In questa pagina

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now