Show Menu
ARGOMENTI×

Guida introduttiva alle API REST

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

Requisiti API e raccomandazioni

Cose che devi e che devi fare quando lavori con Audience Manager APIs.
Tenete presente quanto segue quando lavorate con il codice API di Audience Manager:
  • Parametri di richiesta: Tutti i parametri di richiesta sono obbligatori, se non diversamente specificato.
  • JSON tipo di contenuto: Specificate content-type: application/json e inserite accept: application/json nel codice.
  • Richieste e risposte: Invia le richieste come un 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 fornita o passata durante la creazione o la ricezione di API dati. Sostituite il testo in corsivo con codice, parametri o altre informazioni personali.

Recommendations: Creare un utente API generico

È consigliabile creare un account utente tecnico separato per l'utilizzo con Audience Manager APIs. Si tratta di un account generico che non è associato o associato a un utente specifico nell'organizzazione. Questo tipo di account API utente consente di realizzare 2 operazioni:
  • Identificare il servizio che sta chiamando API (ad esempio, chiamate dalle app che utilizzano i nostri APIe da altri strumenti che effettuano API richieste).
  • Fornire l'accesso ininterrotto agli APIs. Un account legato a una persona specifica può essere eliminato quando esce dalla società. In questo modo non sarà possibile utilizzare il API codice 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 tu voglia cambiare molti segmenti alla volta con gli Strumenti di gestione di massa. Per fare questo, il vostro account utente ha bisogno di API accesso. Invece di aggiungere autorizzazioni a un utente specifico, create un account utente non specifico API con le credenziali, la chiave e il segreto appropriati per effettuare API le chiamate. Questa funzione è utile anche se sviluppate applicazioni personalizzate che utilizzano Audience Manager APIs.
Consultate il vostro consulente Audience Manager per configurare un account utente generico APIsolo.

Autenticazione OAuth

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

Flusso di lavoro di autenticazione della password

Accesso sicuro tramite autenticazione tramite password REST API. I passaggi riportati di seguito descrivono il flusso di lavoro per l'autenticazione tramite password da parte di un JSON client nel browser.
Cifra token di accesso e aggiornamento se li si archivia in un database.

Passaggio 1: Richiedi accesso API

Contatta il tuo Partner Solutions Manager. Forniranno un ID API cliente e un segreto. L’ID e il segreto vi autenticano nel APIsito.
Nota: Se desiderate ricevere un token di aggiornamento, specificatelo quando richiedete API l'accesso.

Passaggio 2: Richiedi token

Passa una richiesta di token con il JSON client preferito. Quando create la richiesta:
  • Utilizza un POST metodo 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 HTTP intestazioni Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Ad esempio, l’intestazione potrebbe essere:
    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 JSON 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 chiave 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

Aggiorna token: API l'accesso viene rinnovato 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 una 401 Status Code e la seguente intestazione:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
La procedura seguente illustra il flusso di lavoro per l’utilizzo di un token di aggiornamento per creare un nuovo token di accesso da un JSON client nel browser.

Passaggio 1: Richiedi il nuovo token

Passa una richiesta di aggiornamento token con il JSON client preferito. Quando create la richiesta:
  • Utilizza un POST metodo 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= .
  • Trasmettere le intestazioni Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Ad esempio, l’intestazione potrebbe essere:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Nel corpo della richiesta, specificate il token di aggiornamento grant_type:refresh_token e trasmettetelo 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 JSON 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

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 per https://api.demdex.com/oauth/authorize ottenere l'accesso e aggiornare i token.

Richieste di autenticazione API

Requisiti per i API metodi di chiamata dopo la ricezione di un token di autenticazione.
Per effettuare chiamate ai API metodi disponibili:
  • Nell’ HTTP intestazione, impostate Authorization: Bearer <token> .
  • Chiama il API metodo richiesto.

Parametri query API opzionali

Impostare i parametri facoltativi disponibili per i metodi che restituiscono tutte le proprietà di un oggetto.
È possibile utilizzare questi parametri facoltativi con API metodi che restituiscono tutte le proprietà di un oggetto. Impostate queste opzioni nella stringa di richiesta quando passate 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 della risposta restituiti dalla richiesta (il valore predefinito è 10).
sortBy
Ordina e restituisce i risultati in base alla JSON proprietà specificata.
decrescente
Ordina e restituisce risultati in ordine decrescente. Ascendente è 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://api.demdex.com/v1/models/?search=Test . È possibile cercare qualsiasi valore restituito da un metodo "get all".
folderId
Restituisce tutti gli ID per le caratteristiche 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 : Utilizzate 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 appartenenti a un segmento se desideri rimuoverlo.
Specificate più autorizzazioni con coppie chiave-valore separate. Ad esempio, per restituire un elenco di segmenti con READ e WRITE autorizzazioni, passate in "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Booleano) Impostate su true per restituire le autorizzazioni per il segmento. Il valore predefinito è false.

Una Nota Sulle Opzioni Pagina

Quando le informazioni sulla pagina non sono specificate, la richiesta restituisce JSON risultati semplici in un array. Se sono specificate le informazioni sulla pagina, l'elenco restituito viene racchiuso in un JSON oggetto 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://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test

URL dell'API

URLs per richieste, ambienti di produzione e staging e versioni.

Richiedi URL

Nella tabella seguente sono elencati gli URL di richiesta utilizzati per trasmettere API le richieste, per metodo.
API Metodi
Richiesta URL
Modellazione algoritmica
https://api.demdex.com/v1/models/
Origine dati
https://api.demdex.com/v1/datasources/
Segnali derivati
https://api.demdex.com/v1/signals/derived/
Destinazioni
https://api.demdex.com/v1/destinations/
Domains (Domini)
https://api.demdex.com/v1/partner-sites/
Cartelle
Caratteristiche: https://api.demdex.com/v1/folders/traits /
Segmenti: https://api.demdex.com/v1/folders/segments /
Schema
https://api.demdex.com/v1/schemas/
Segmenti
https://api.demdex.com/v1/segments/
Caratteristiche
https://api.demdex.com/v1/traits/
Tipi di caratteristiche
https://api.demdex.com/v1/customer-trait-types
Tassonomia
https://api.demdex.com/v1/taxonomies/0/

Ambienti

Gli Audience Manager strumenti APIconsentono 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 API ambienti disponibili e i nomi host delle risorse corrispondenti.
Ambiente
Nome host
Produzione
https://api.demdex.com/...
Beta
https://api-beta.demdex.com/...
L’ambiente beta di Audience Manager è 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 APIvengono rilasciate secondo una pianificazione regolare. Con una nuova versione viene incrementato il numero di API versione. Nell’URL della richiesta viene fatto riferimento al numero di versione, come v<version number> illustrato nell’esempio seguente:
https://<host>/v1/...

Codici di risposta definiti

HTTP codici di stato e testo della risposta restituiti da 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
Creato
La risorsa è stata creata. Restituisce per PUT e POST le richieste.
204
Nessun contenuto
La risorsa è stata eliminata. Il corpo della risposta sarà vuoto.
400
Richiesta non valida
Il server non ha capito la richiesta. Solitamente a causa di sintassi non corretta. Controlla la richiesta e riprova.
403
Vietato
Non si dispone dell'accesso alla risorsa.
404
Non trovato
Impossibile trovare la risorsa per il percorso specificato.
409
Conflitto
Impossibile completare la richiesta a causa di un conflitto con lo stato della risorsa.
500
Errore server
Il server ha rilevato un errore imprevisto che gli ha impedito di soddisfare la richiesta.