[Ultimate]{class="badge positive"}
Connessione API HTTP
Panoramica overview
La destinazione API HTTP è una destinazione di streaming Adobe Experience Platform che consente di inviare i dati del profilo agli endpoint HTTP di terze parti.
Per inviare i dati del profilo agli endpoint HTTP, devi prima connetterti alla destinazione in Adobe Experience Platform.
Casi d’uso use-cases
La destinazione API HTTP consente di esportare i dati di profilo XDM e i tipi di pubblico in endpoint HTTP generici. A questo punto puoi eseguire analisi personalizzate o eseguire qualsiasi altra operazione necessaria sui dati del profilo esportati da Experience Platform.
Gli endpoint HTTP possono essere sistemi propri del cliente o soluzioni di terze parti.
Tipi di pubblico supportati supported-audiences
Questa sezione descrive quali tipi di pubblico puoi esportare in questa destinazione.
Tipo e frequenza di esportazione export-type-frequency
Per informazioni sul tipo e sulla frequenza di esportazione della destinazione, consulta la tabella seguente.
Prerequisiti prerequisites
Per utilizzare la destinazione API HTTP per esportare dati da Experience Platform, è necessario soddisfare i seguenti prerequisiti:
- È necessario disporre di un endpoint HTTP che supporti l’API REST.
- L'endpoint HTTP deve supportare lo schema del profilo di Experience Platform. Nella destinazione API HTTP non è supportata alcuna trasformazione in uno schema di payload di terze parti. Consulta la sezione dati esportati per un esempio dello schema di output di Experience Platform.
- L'endpoint HTTP deve supportare le intestazioni.
- L’endpoint HTTP deve rispondere entro 2 secondi per garantire la corretta elaborazione dei dati ed evitare errori di timeout.
- Se prevedi di utilizzare mTLS: l’endpoint di ricezione dei dati deve avere TLS disabilitato e solo mTLS abilitato. mTLS non è supportato se l'endpoint richiede l'autenticazione tramite password OAuth 2 o credenziali client.
Supporto e certificato del protocollo mTLS mtls-protocol-support
È possibile utilizzare Mutual Transport Layer Security (mTLS) per garantire una maggiore sicurezza nelle connessioni in uscita alle connessioni di destinazione API HTTP.
mTLS è un protocollo di autenticazione reciproca che garantisce che entrambe le parti che condividono le informazioni siano quelle che dichiarano di essere prima che i dati vengano condivisi. mTLS include un passaggio aggiuntivo rispetto allo standard TLS, in cui il server richiede e verifica anche il certificato del client, mentre il client verifica il certificato del server.
Considerazioni su mTLS mtls-considerations
Il supporto mTLS per le destinazioni API HTTP si applica solo all'endpoint di ricezione dei dati in cui vengono inviate le esportazioni dei profili (il campo HTTP Endpoint in dettagli destinazione).
mTLS non è supportato se l'endpoint richiede l'autenticazione tramite password OAuth 2 o credenziali client.
Configurazione di mTLS per l’esportazione dei dati configuring-mtls
Per utilizzare mTLS con HTTP API destinazioni, HTTP Endpoint (endpoint di ricezione dati) configurato nella pagina dettagli destinazione deve avere TLS protocolli disabilitati e solo mTLS abilitati. Se il protocollo TLS 1.2 è ancora abilitato sull'endpoint, non verrà inviato alcun certificato per l'autenticazione client. Ciò significa che per utilizzare mTLS con la destinazione HTTP API, l'endpoint del server che riceve i dati deve essere un endpoint di connessione abilitato solo per mTLS.
Recupera e controlla i dettagli del certificato certificate
Se desideri esaminare i dettagli del certificato come Common Name (CN) e Subject Alternative Names (SAN) per un'ulteriore convalida di terze parti, utilizza l'API per recuperare il certificato ed estrarre tali campi dalla risposta.
Per ulteriori informazioni, consulta la documentazione dell'endpoint del certificato pubblico.
Indirizzo IP inserisco nell'elenco Consentiti ip-address-allowlist
Per soddisfare i requisiti di sicurezza e conformità dei clienti, Experience Platform inserire nell'elenco Consentiti fornisce un elenco di IP statici che puoi per la destinazione API HTTP. Per l'elenco completo degli indirizzi IP da inserire nell'elenco Consentiti, consulta il inserisco nell'elenco Consentiti di degli indirizzi IP per le destinazioni di streaming.
Tipi di autenticazione supportati supported-authentication-types
La destinazione API HTTP supporta diversi tipi di autenticazione per l’endpoint HTTP:
- Endpoint HTTP senza autenticazione;
- Autenticazione token Bearer;
- Autenticazione di credenziali client OAuth 2.0 con il form del corpo, con client ID, client secret e grant type nel corpo della richiesta HTTP, come illustrato nell'esempio seguente.
curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
- Credenziali client OAuth 2.0 con autorizzazione di base, con un'intestazione di autorizzazione che contiene client ID e client secret codificati in URL.
curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'
Connettersi alla destinazione connect-destination
Per connettersi a questa destinazione, seguire i passaggi descritti nell'esercitazione sulla configurazione della destinazione. Quando ti connetti a questa destinazione, devi fornire le seguenti informazioni:
Informazioni di autenticazione authentication-information
Autenticazione token Bearer bearer-token-authentication
Se si seleziona il tipo di autenticazione Bearer token per la connessione all'endpoint HTTP, immettere i campi seguenti e selezionare Connect to destination:
- Bearer token: inserire il token Bearer per l'autenticazione nel percorso HTTP.
Nessuna autenticazione no-authentication
Se si seleziona il tipo di autenticazione None per la connessione all'endpoint HTTP:
Quando si seleziona questa autenticazione aperta, è necessario selezionare solo Connect to destination e la connessione all'endpoint è stata stabilita.
Autenticazione password OAuth 2 oauth-2-password-authentication
Se si seleziona il tipo di autenticazione OAuth 2 Password per la connessione all'endpoint HTTP, immettere i campi seguenti e selezionare Connect to destination:
- Access Token URL: l'URL sul tuo lato che emette i token di accesso e, facoltativamente, i token di aggiornamento.
- Client ID: client ID assegnato dal sistema a Adobe Experience Platform.
- Client Secret: client secret assegnato dal sistema a Adobe Experience Platform.
- Username: nome utente per accedere all'endpoint HTTP.
- Password: password per accedere all'endpoint HTTP.
Autenticazione credenziali client OAuth 2 oauth-2-client-credentials-authentication
Se si seleziona il tipo di autenticazione OAuth 2 Client Credentials per la connessione all'endpoint HTTP, immettere i campi seguenti e selezionare Connect to destination:
-
Access Token URL: l'URL sul tuo lato che emette i token di accesso e, facoltativamente, i token di aggiornamento.
-
Client ID: client ID assegnato dal sistema a Adobe Experience Platform.
-
Client Secret: client secret assegnato dal sistema a Adobe Experience Platform.
-
Client Credentials Type: selezionare il tipo di concessione di credenziali client OAuth2 supportata dall'endpoint:
- Body Form Encoded: In questo caso, client ID e client secret sono inclusi nel corpo della richiesta inviata alla tua destinazione. Ad esempio, consulta la sezione Tipi di autenticazione supportati.
- Basic Authorization: in questo caso, client ID e client secret sono inclusi in un'intestazione
Authorizationdopo essere stati codificati in base64 e inviati alla destinazione. Ad esempio, consulta la sezione Tipi di autenticazione supportati.
Inserire i dettagli della destinazione destination-details
Per configurare i dettagli per la destinazione, compila i campi obbligatori e facoltativi seguenti. Un asterisco accanto a un campo nell’interfaccia utente indica che il campo è obbligatorio.
- Name: immettere un nome con cui riconoscere questa destinazione in futuro.
- Description: immettere una descrizione che consentirà di identificare questa destinazione in futuro.
- Headers: immettere le intestazioni personalizzate che si desidera includere nelle chiamate di destinazione, nel seguente formato:
header1:value1,header2:value2,...headerN:valueN. - HTTP Endpoint: URL dell'endpoint HTTP a cui si desidera inviare i dati del profilo. Questo è l’endpoint di ricezione dei dati. Se utilizzi mTLS, l’endpoint deve avere TLS disabilitato e solo mTLS abilitato.
- Query parameters: facoltativamente, è possibile aggiungere parametri di query all'URL dell'endpoint HTTP. I parametri di query che vuoi utilizzare devono essere nel formato seguente:
parameter1=value¶meter2=value. - Include Segment Names: attivare/disattivare se si desidera che l'esportazione dei dati includa i nomi dei tipi di pubblico che si stanno esportando. Nota: i nomi dei segmenti sono inclusi solo per i segmenti mappati alla destinazione. I segmenti non mappati visualizzati nell'esportazione non includono il campo
name. Per un esempio di esportazione di dati con questa opzione selezionata, consulta la sezione Dati esportati più avanti. - Include Segment Timestamps: attivare se si desidera che l'esportazione dei dati includa la marca temporale UNIX quando i tipi di pubblico sono stati creati e aggiornati, nonché la marca temporale UNIX quando i tipi di pubblico sono stati mappati alla destinazione per l'attivazione. Per un esempio di esportazione di dati con questa opzione selezionata, consulta la sezione Dati esportati più avanti.
Abilita avvisi enable-alerts
Puoi abilitare gli avvisi per ricevere notifiche sullo stato del flusso di dati verso la tua destinazione. Seleziona un avviso dall’elenco per abbonarti e ricevere notifiche sullo stato del flusso di dati. Per ulteriori informazioni sugli avvisi, consulta la guida su abbonamento a destinazioni avvisi tramite l'interfaccia utente.
Dopo aver fornito i dettagli della connessione di destinazione, selezionare Next.
Attivare tipi di pubblico in questa destinazione activate
- Per attivare i dati, sono necessarie le View Destinations, Activate Destinations, View Profiles e View Segments autorizzazioni di controllo di accesso. Leggi la panoramica sul controllo degli accessi o contatta l'amministratore del prodotto per ottenere le autorizzazioni necessarie.
- La valutazione dei criteri di consenso non è attualmente supportata nelle esportazioni nella destinazione API HTTP. Ulteriori informazioni.
Per istruzioni sull'attivazione dei tipi di pubblico in questa destinazione, consulta Attiva dati pubblico nelle destinazioni di esportazione del profilo di streaming.
Attributi di destinazione attributes
Nel passaggio Select attributes, Adobe consiglia di selezionare un identificatore univoco dallo schema di unione. Seleziona l’identificatore univoco e tutti gli altri campi XDM da esportare nella destinazione.
Comportamento di esportazione del profilo profile-export-behavior
Experience Platform ottimizza il comportamento di esportazione del profilo nella destinazione API HTTP per esportare i dati nell’endpoint API solo quando si sono verificati aggiornamenti rilevanti a un profilo in seguito alla qualifica del pubblico o ad altri eventi significativi. I profili vengono esportati nella destinazione nelle seguenti situazioni:
- L’aggiornamento del profilo è stato determinato da una modifica nell’appartenenza al pubblico per almeno uno dei tipi di pubblico mappati alla destinazione. Ad esempio, il profilo è idoneo per uno dei tipi di pubblico mappati sulla destinazione o è uscito da uno dei tipi di pubblico mappati sulla destinazione.
- L'aggiornamento del profilo è stato determinato da una modifica nella mappa identità. Ad esempio, a un profilo che si era già qualificato per uno dei tipi di pubblico mappati sulla destinazione è stata aggiunta una nuova identità nell’attributo identity map.
- L’aggiornamento del profilo è stato determinato da una modifica degli attributi per almeno uno degli attributi mappati alla destinazione. Ad esempio, uno degli attributi mappati sulla destinazione nel passaggio di mappatura viene aggiunto a un profilo.
In tutti i casi descritti sopra, solo i profili in cui si sono verificati aggiornamenti rilevanti vengono esportati nella destinazione. Ad esempio, se un pubblico mappato al flusso di destinazione ha un centinaio di membri e cinque nuovi profili sono idonei per il segmento, l’esportazione nella destinazione è incrementale e include solo i cinque nuovi profili.
Tieni presente che tutti gli attributi mappati vengono esportati per un profilo, indipendentemente da dove si trovano le modifiche. Quindi, nell’esempio precedente, tutti gli attributi mappati per questi cinque nuovi profili verranno esportati anche se gli attributi stessi non sono stati modificati.
Che cosa determina un’esportazione di dati e cosa è incluso nell’esportazione what-determines-export-what-is-included
Per quanto riguarda i dati esportati per un determinato profilo, è importante comprendere i due diversi concetti di che determinano un'esportazione di dati nella destinazione API HTTP e quali dati sono inclusi nell'esportazione.
- Gli attributi e i segmenti mappati fungono da spunto per un’esportazione di destinazione. Ciò significa che se lo stato
segmentMembershipdi un profilo cambia inrealizedoexitingo se vengono aggiornati eventuali attributi mappati, viene avviata un'esportazione di destinazione. - Poiché al momento non è possibile mappare le identità sulle destinazioni API HTTP, anche le modifiche apportate a un’identità in un determinato profilo determinano le esportazioni delle destinazioni.
- Per modifica di un attributo si intende qualsiasi aggiornamento dell'attributo, indipendentemente dal fatto che si tratti o meno dello stesso valore. Ciò significa che una sovrascrittura su un attributo è considerata una modifica anche se il valore stesso non è cambiato.
- L'oggetto
segmentMembershipinclude il segmento mappato nel flusso di dati di attivazione, per il quale lo stato del profilo è cambiato a seguito di un evento di qualificazione o uscita da un segmento. Tieni presente che altri segmenti non mappati per i quali il profilo si è qualificato possono far parte dell'esportazione di destinazione, se tali segmenti appartengono allo stesso criterio di unione del segmento mappato nel flusso di dati di attivazione.
Importante: quando l'opzione Include Segment Names è abilitata, i nomi dei segmenti vengono inclusi solo per i segmenti mappati alla destinazione. I segmenti non mappati visualizzati nell'esportazione non includeranno il camponame, anche se l'opzione è abilitata. - Sono incluse anche tutte le identità nell'oggetto
identityMap(attualmente Experience Platform non supporta la mappatura identità nella destinazione API HTTP). - Nell’esportazione della destinazione sono inclusi solo gli attributi mappati.
Ad esempio, considera questo flusso di dati come una destinazione HTTP in cui tre tipi di pubblico vengono selezionati nel flusso di dati e quattro attributi vengono mappati sulla destinazione.
Un'esportazione di profilo nella destinazione può essere determinata da un profilo idoneo o in uscita da uno dei tre segmenti mappati. Tuttavia, nell'esportazione dei dati, nell'oggetto segmentMembership (vedi la sezione Dati esportati di seguito), potrebbero essere visualizzati altri tipi di pubblico non mappati, se quel particolare profilo è un membro di essi e se questi condividono lo stesso criterio di unione del pubblico che ha attivato l'esportazione. Se un profilo è idoneo per il segmento Cliente con auto DeLorean ma è anche membro dei segmenti Guardato "Ritorno al futuro" filmato e Fantascienza, anche questi altri due tipi di pubblico saranno presenti nell'oggetto segmentMembership dell'esportazione dati, anche se non sono mappati nel flusso di dati, se condividono lo stesso criterio di unione con il segmento Cliente con auto DeLorean.
Dal punto di vista degli attributi di profilo, eventuali modifiche ai quattro attributi mappati in precedenza determineranno un’esportazione di destinazione e uno qualsiasi dei quattro attributi mappati presenti nel profilo sarà presente nell’esportazione di dati.
Recupero dati storici historical-data-backfill
Quando aggiungi un nuovo pubblico a una destinazione esistente o crei una nuova destinazione e mappi i tipi di pubblico a essa, Experience Platform esporta i dati storici di qualificazione del pubblico nella destinazione. I profili qualificati per il pubblico prima che il pubblico sia stato aggiunto alla destinazione vengono esportati nella destinazione entro circa un'ora.
Dati esportati exported-data
I dati di Experience Platform esportati arrivano nella destinazione di HTTP in formato JSON. Ad esempio, l’esportazione seguente contiene un profilo idoneo per un determinato segmento, è membro di altri due segmenti ed è uscito da un altro segmento. L’esportazione include anche l’attributo del profilo nome, cognome, data di nascita e indirizzo e-mail personale. Le identità per questo profilo sono ECID e e-mail.
{
"person": {
"birthDate": "YYYY-MM-DD",
"name": {
"firstName": "John",
"lastName": "Doe"
}
},
"personalEmail": {
"address": "john.doe@acme.com"
},
"segmentMembership": {
"ups":{
"7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
"lastQualificationTime":"2022-01-11T21:24:39Z",
"status":"exited"
},
"59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
"lastQualificationTime":"2022-01-02T23:37:33Z",
"status":"realized"
},
"947c1c46-008d-40b0-92ec-3af86eaf41c1":{
"lastQualificationTime":"2021-08-25T23:37:33Z",
"status":"realized"
},
"5114d758-ce71-43ba-b53e-e2a91d67b67f":{
"lastQualificationTime":"2022-01-11T23:37:33Z",
"status":"realized"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
Di seguito sono riportati ulteriori esempi di dati esportati, a seconda delle impostazioni dell'interfaccia utente selezionate nel flusso di destinazione di connessione per le opzioni Include Segment Names e Include Segment Timestamps:
segmentMembership| code language-json |
|---|
|
Nota: in questo esempio, il primo segmento (5b998cb9-9488-4ec3-8d95-fa8338ced490) è mappato alla destinazione e include il campo name. Il secondo segmento (354e086f-2e11-49a2-9e39-e5d9a76be683) non è mappato alla destinazione e non include il campo name, anche se l'opzione Include Segment Names è abilitata.
segmentMembership| code language-json |
|---|
|
Limiti e criteri per nuovi tentativi limits-retry-policy
Nel 95% dei casi, Experience Platform tenta di offrire una latenza di velocità effettiva inferiore a 10 minuti per i messaggi inviati con successo, con una frequenza inferiore a 10.000 richieste al secondo per ogni flusso di dati verso una destinazione HTTP.
In caso di richieste non riuscite alla destinazione API HTTP, Experience Platform memorizza le richieste non riuscite e tenta di inviarle all’endpoint due volte.
Risoluzione dei problemi troubleshooting
Per garantire una distribuzione affidabile dei dati ed evitare problemi di timeout, assicurati che l'endpoint HTTP risponda entro 2 secondi alle richieste di Experience Platform, come specificato nella sezione prerequisiti. Le risposte che richiedono più tempo genereranno errori di timeout.