[Ultimate]{class="badge positive"}

Connessione API HTTP

Panoramica overview

La destinazione API HTTP è una destinazione di streaming di 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 Experience Platform.

Casi d’uso use-cases

Utilizza la destinazione API HTTP per 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.

Tipi di pubblico supportati per tipo di dati sul pubblico:

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:

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 chi affermano di essere prima che i dati vengano condivisi. mTLS include un ulteriore passaggio rispetto a TLS standard, 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).

Configurazione di mTLS per l’esportazione dei dati configuring-mtls

Per utilizzare mTLS con le destinazioni API HTTP, l'endpoint HTTP Endpoint (endpoint di ricezione dati) configurato nella pagina dettagli destinazione deve avere protocolli TLS disabilitati e solo mTLS abilitato. Se il protocollo TLS 1.2 è ancora abilitato sull’endpoint, non viene inviato alcun certificato per l’autenticazione client. Ciò significa che per utilizzare mTLS con la destinazione API HTTP, 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 Nome comune (CN) e Nome alternativo soggetto (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 fornisce un elenco di IP statici che puoi per la destinazione API HTTP. Per l'elenco completo degli IP da inserire nell'elenco Consentiti, vedere Indirizzo IP da 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:

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>'

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 le informazioni seguenti e selezionare Connect to destination:

Nessuna autenticazione no-authentication

Se si seleziona il tipo di autenticazione None per la connessione all'endpoint HTTP:

Quando selezioni questa opzione di autenticazione, devi 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 le informazioni seguenti e selezionare Connect to destination:

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 le informazioni seguenti e selezionare Connect to destination:

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.

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 agli avvisi di destinazione tramite l'interfaccia utente.

Dopo aver fornito i dettagli della connessione di destinazione, selezionare Next.

Attivare tipi di pubblico in questa destinazione activate

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:

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 pubblico, l’esportazione nella destinazione è incrementale e include solo i cinque nuovi profili.

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.

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 profili nella destinazione viene attivata quando un profilo si qualifica per uno dei tre tipi di pubblico mappati o ne esce. Nell'esportazione dei dati, l'oggetto segmentMembership (vedi Dati esportati di seguito) può includere anche tipi di pubblico non mappati, se tale profilo è un membro di essi e condividono lo stesso criterio di unione del pubblico che ha attivato l'esportazione. Ad esempio, se un profilo è idoneo per il pubblico Cliente con auto DeLorean ma è anche membro del pubblico Guarda il film "Ritorno al futuro" e Fantascienza, anche questi due tipi di pubblico vengono visualizzati nell'oggetto segmentMembership, purché condividano lo stesso criterio di unione con il pubblico 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 Experience Platform esportati vengono consegnati alla destinazione HTTP in formato JSON. Ad esempio, l’esportazione seguente contiene un profilo idoneo per un determinato pubblico, è membro di altri due tipi di pubblico ed è uscito da un altro pubblico. 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": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000
          }
        }
      }

Limiti e criteri per nuovi tentativi limits-retry-policy

Per il 95% del tempo, Experience Platform tenta di offrire una latenza di velocità effettiva inferiore a 10 minuti per i messaggi inviati correttamente con una frequenza inferiore a 10.000 richieste al secondo per ogni flusso di dati verso una destinazione HTTP.

Quando le richieste alla destinazione API HTTP non vanno a buon fine, Experience Platform le archivia e riprova 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.