Guida introduttiva a REST APIs

Ultimo aggiornamento: 2024-02-08
  • Argomenti:
  • API
    Visualizza ulteriori informazioni su questo argomento

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

Requisiti API e Recommendations

Quando si lavora con API AUDIENCI MANAGER codice:

  • Parametri di richiesta: tutti i parametri di richiesta sono obbligatori se non diversamente specificato.
  • Intestazioni di richiesta: quando si utilizza Adobe Developer token, devi fornire x-api-key intestazione. Puoi ottenere il tuo API seguendo le istruzioni della sezione Integrazione dell’account del servizio pagina.
  • JSONtipo di contenuto: Specifica content-type: application/json e accept: application/json nel codice.
  • Richieste e risposte: Inviare richieste come formattate correttamente JSON oggetto. Audience Manager risponde con JSON dati formattati. Le risposte del server possono contenere i dati richiesti, un codice di stato o entrambi.
  • Accesso: Il tuo Audience Manager il consulente ti fornirà un ID cliente e una chiave che ti consentano di API richieste.
  • Documentazione ed esempi di codice: Testo in corsivo rappresenta una variabile fornita o trasmessa quando si crea o si riceve API dati. Sostituisci corsivo testo con codice, parametri o altre informazioni obbligatorie.

Autenticazione

Il Audience Manager REST APIs supporta tre metodi di autenticazione.

IMPORTANTE

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

Autenticazione server-to-server OAuth tramite Adobe Developer

Questa sezione illustra come raccogliere le credenziali necessarie per autenticare le chiamate API Audienci 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 di diagramma del flusso di autenticazione.

Panoramica di Adobe Developer

Adobe Developer è l’ecosistema e la comunità di sviluppatori di Adobe. Include API per tutti i prodotti Adobe.

Si tratta del metodo consigliato per impostare e utilizzare Adobe APIs.

Prerequisiti

Prima di configurare OAuth Server-to-Server autenticazione, assicurati di avere accesso al Console Adobe Developer in Adobe Developer. Contatta l’amministratore dell’organizzazione per le richieste di accesso.

Autenticazione

Segui i passaggi seguenti per configurare OAuth Server-to-Server autenticazione tramite Adobe Developer:

  1. Accedi a Console Adobe Developer.
  2. Segui i passaggi descritti in Guida all'implementazione delle credenziali server-to-server di OAuth.
  3. Prova la connessione effettuando la prima API effettua una chiamata in base alle istruzioni Passaggio 3.
NOTA

Per configurare e utilizzare Audience Manager REST APIs in modo automatico, puoi ruotare i segreti client a livello di programmazione. Consulta la documentazione per gli sviluppatori per istruzioni dettagliate.

Aggiungere l’API Audienci Manager a un progetto

Vai a Console Adobe Developer e accedi con il tuo Adobe ID. Quindi, segui i passaggi descritti nel tutorial su creazione di un progetto vuoto nella documentazione della console Adobe Developer.

Dopo aver creato un nuovo progetto, seleziona Add API il Project Overview schermo.

SUGGERIMENTO

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

Nella schermata Console sviluppatori è evidenziata l’opzione Aggiungi API.

Il Add an API viene visualizzata la schermata. Seleziona l’icona del prodotto per Adobe Experience Cloud, quindi scegli Audience Manager API prima di selezionare Next.

Seleziona Audienci Manager API.

SUGGERIMENTO

Seleziona la View docs per passare in una finestra del browser separata al Documentazione di riferimento dell’API Audienci Manager.

Seleziona il tipo di autenticazione server-to-server OAuth

Quindi, seleziona il tipo di autenticazione per generare token di accesso e accedere all’API Audienci Manager.

IMPORTANTE

Seleziona la OAuth Server-to-Server poiché questo sarà l’unico metodo supportato per andare avanti. Il 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 il metodo di autenticazione OAuth.

Selezionare i profili di prodotto per l’integrazione

In Configure API , seleziona 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.

Seleziona Save configured API quando sei pronto.

Raccogli le credenziali

Una volta aggiunta l’API al progetto, la Audience Manager API Nella pagina del progetto vengono visualizzate le seguenti credenziali necessarie in tutte le chiamate alle API Audienci Manager:

Informazioni sull’integrazione dopo l’aggiunta di un’API in Console sviluppatori.

  • {API_KEY} (Client ID)
  • {ORG_ID} (Organization ID)

Generare un token di accesso

Il passaggio successivo consiste nel generare un {ACCESS_TOKEN} credenziali da utilizzare nelle chiamate API Audienci Manager. A differenza dei valori per {API_KEY} e {ORG_ID}, per continuare a utilizzare le API Audienci Manager, è necessario generare un nuovo token ogni 24 ore. Seleziona Generate access token, come illustrato di seguito.

Mostra come generare il token di accesso

Testare una chiamata API

Dopo aver ottenuto il token Bearer di autenticazione, esegui una chiamata API per verificare che ora puoi accedere alle API Audienci Manager.

  1. Accedi a Documentazione di riferimento API.

  2. Seleziona Authorize e incolla il token di accesso ottenuto in genera token di accesso passaggio.

    Autorizzare le chiamate API

  3. Effettuare una chiamata di GET al /datasources Endpoint API per recuperare un elenco di tutte le origini dati disponibili a livello globale, come indicato nella Documentazione di riferimento API. Seleziona Try it out, seguito da Execute, come illustrato di seguito.

    Eseguire chiamate API

curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'

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.

[
  {
    "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"
    ],

    [...]

ObsoletoJWT (Service Accounta) Autenticazione tramite Adobe Developer

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

Panoramica di Adobe Developer

Adobe Developer è l’ecosistema e la comunità di sviluppatori di Adobe. Include API per tutti i prodotti Adobe.

Si tratta del metodo consigliato per impostare e utilizzare Adobe APIs.

Prerequisiti

Prima di configurare JWT autenticazione, assicurati di avere accesso al Console Adobe Developer in Adobe Developer. Contatta l’amministratore dell’organizzazione per le richieste di accesso.

Autenticazione

Segui i passaggi seguenti per configurare JWT (Service Account) autenticazione tramite Adobe Developer:

  1. Accedi a Console Adobe Developer.
  2. Segui i passaggi descritti in Connessione account di servizio.
  3. Prova la connessione effettuando la prima API effettua una chiamata in base alle istruzioni Passaggio 3.
NOTA

Per configurare e utilizzare Audience Manager REST APIs in modo automatico, puoi generare il JWT a livello di programmazione. Consulta 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 Audienci Manager e aggiungerlo al gruppo RBAC Audienci Manager che effettuerà le chiamate API.

Per creare un account utente tecnico e aggiungerlo a un gruppo RBAC, effettua le seguenti operazioni:

  1. Crea un GET chiama a https://aam.adobe.io/v1/users/self. La chiamata creerà un account utente tecnico che potrai visualizzare nella Admin Console, nella Users pagina.

    account tecnico

  2. Accedi al tuo account Audienci Manager e aggiungere l’account utente tecnico al gruppo di utenti che effettuerà le chiamate API.

ObsoletoOAuth Autenticazione (obsoleto)

 Visualizza informazioni sulla versione precedente obsoleta OAuth Metodo di autenticazione per ottenere i token di autenticazione.
AVVERTENZA

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

Utilizza Autenticazione JWT (account di servizio) invece.

Il 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 utilizzare APIs.

Crea un generico API Utente

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

  • Identifica il servizio che chiama API (ad esempio, chiamate dalle app che utilizzano il nostro APIs o da altri strumenti che API richieste).
  • Fornire accesso ininterrotto al APIs. Un account associato a una persona specifica può essere cancellato quando lascia la tua azienda. Questo ti impedirà di lavorare con i API codice. 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 tu voglia modificare molti segmenti contemporaneamente con Strumenti di gestione in blocco. Bene, per fare questo, il tuo account utente ha bisogno di API accesso. Invece di aggiungere le autorizzazioni a un utente specifico, crea un’ API account utente con credenziali, chiave e segreto appropriati API chiamate. Questa funzione è utile anche per sviluppare applicazioni personalizzate che utilizzano Audience Manager APIs.

Utilizzare Audience Manager consulente per la creazione di un generico, APIaccount utente di sola lettura.

Flusso di lavoro di autenticazione password

Autenticazione tramite password accesso sicuro REST API. I passaggi seguenti descrivono il flusso di lavoro per l’autenticazione tramite password da un JSON nel browser.

SUGGERIMENTO

Crittografare i token di accesso e di aggiornamento se vengono memorizzati 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 ti autenticano nel API.

Nota: se desideri ricevere un token di aggiornamento, specificalo 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. Durante il processo di conversione, separa l’ID e il segreto con due punti. Ad esempio, le credenziali testId : testSecret convertire in dGVzdElkOnRlc3RTZWNyZXQ=.
  • Passa il 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

Il JSON la risposta contiene il token di accesso. La risposta deve 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"
}

Il expires_in key 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

Aggiorna token di rinnovo API dopo la scadenza del token originale. Se richiesto, la risposta JSON nel flusso di lavoro della password è incluso 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, viene visualizzato un messaggio 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 descrivono 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: richiesta del nuovo token

Trasmettere una richiesta di token di aggiornamento con il token 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. Durante il processo di conversione, separa l’ID e il segreto con due punti. 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 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

Il JSON la risposta contiene il nuovo token di accesso. La risposta deve 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 accedere e aggiornare i token.

Rendi autenticato API Richieste

Requisiti per il servizio di chiamata API metodi dopo aver ricevuto un token di autenticazione.

Per effettuare chiamate rispetto alla disponibilità API metodi:

Facoltativo API Parametri di query

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

Questi parametri facoltativi possono essere utilizzati 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 è il valore predefinito).
sortBy Ordina e restituisce i risultati in base al JSON proprietà.
descending Ordina e restituisce i risultati in ordine decrescente. ascending è l'impostazione predefinita.
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. Puoi eseguire ricerche in base a qualsiasi valore restituito da un "get allmetodo ".
folderId Restituisce tutti gli ID per traits nella cartella specificata. Non disponibile per tutti i metodi.
permissions Restituisce un elenco di segmenti in base all’autorizzazione specificata. READ è l’impostazione predefinita. 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, per rimuoverlo, dovrai disporre dei diritti necessari 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) Impostate su true per restituire le autorizzazioni per il segmento. Il valore predefinito è false.

Nota Sulle Opzioni Di Pagina

Quando le informazioni della pagina non è specificata, la richiesta restituisce solo JSON restituisce un array. Se le informazioni della pagina è specificato, l'elenco restituito viene racchiuso in un JSON oggetto che contiene 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

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

Richiesta URLs

Nella tabella seguente sono elencate le richieste URLs utilizzato per trasmettere API richieste, per metodo.

A seconda del metodo di autenticazione utilizzato, è necessario modificare la richiesta URLs secondo le tabelle che seguono.

Richiesta URLs per ConsigliatoObsoletoJWT Autenticazione tramite Adobe Developer

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 ObsoletoOAuth Autenticazione

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

Il Audience Manager APIfornisce 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 elencate le opzioni API e i nomi host delle risorse corrispondenti.

A seconda del metodo di autenticazione utilizzato, è necessario modificare 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

Il Audience Manager l’ambiente beta è una versione standalone dell’ambiente di produzione su scala ridotta. Tutti i dati che desideri verificare 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 as v<version number> come mostrato nell'esempio seguente:

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

Codici di risposta definiti

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.

In questa pagina