[Beta]{class="badge informative"}
Acquisisci i dati dei pagamenti dal tuo Stripe Experience Platform dell’account tramite API
Leggi il seguente tutorial per scoprire come acquisire i dati di pagamento da Stripe a Adobe Experience Platform utilizzando Flow Service API.
Introduzione
Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:
- Sorgenti: un Experience Platform consente di acquisire dati da varie origini, consentendoti allo stesso tempo di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi di Platform.
- Sandbox: Experienci Platform fornisce sandbox virtuali che permettono di suddividere una singola istanza Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.
Autenticazione
Leggi le Stripe panoramica per informazioni su come recuperare le credenziali di autenticazione.
Utilizzo delle API di Platform
Per informazioni su come effettuare correttamente chiamate alle API di Platform, consulta la guida su introduzione alle API di Platform.
Connetti Stripe all'Experience Platform
Segui la guida riportata di seguito per scoprire come autenticare il Stripe origine, crea una connessione di origine e crea un flusso di dati per portare a Experience Platform i dati dei pagamenti.
Creare una connessione di base base-connection
Una connessione di base mantiene le informazioni tra l'origine e l'Experience Platform, incluse le credenziali di autenticazione dell'origine, lo stato corrente della connessione e l'ID univoco della connessione di base. Puoi esplorare e navigare nei file dall’interno della tua origine utilizzando l’ID connessione di base. Inoltre, puoi identificare gli elementi specifici che desideri acquisire, compresi i dettagli sui tipi di dati e i formati di tali elementi.
Per creare un ID di connessione di base, effettua una richiesta POST al /connections
endpoint durante la fornitura del Stripe credenziali di autenticazione come parte del corpo della richiesta.
Formato API
POST /connections
Richiesta
La richiesta seguente crea una connessione di base per Stripe:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Stripe base connection",
"description": "Authenticated base connection for Stripe",
"connectionSpec": {
"id": "cc2c31d6-7b8c-4581-b49f-5c8698aa3ab3",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"accessToken": "{ACCESS_TOKEN}",
}
}
}'
name
description
connectionSpec.id
cc2c31d6-7b8c-4581-b49f-5c8698aa3ab3
, e questo ID viene corretto.auth.specName
auth.params.accessToken
Risposta
In caso di esito positivo, la risposta restituisce la connessione di base appena creata, incluso il relativo identificatore univoco di connessione (id
). Questo ID è necessario per esplorare la struttura e il contenuto del file sorgente nel passaggio successivo.
{
"id": "a9950001-a386-4642-a0cd-5eaac6db5556",
"etag": "\"dc01244d-0000-0200-0000-65ea4e500000\""
}
Esplora l’origine explore
Una volta ottenuto l’ID di connessione di base, ora puoi esplorare il contenuto e la struttura dei dati sorgente eseguendo una richiesta GET al /connections
mentre fornisci l’ID connessione di base come parametro di query.
Formato API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Richiesta
Quando si eseguono richieste di GET per esplorare la struttura e il contenuto dei file dell’origine, è necessario includere i parametri di query elencati nella tabella seguente:
{BASE_CONNECTION_ID}
objectType=rest
rest
.{OBJECT}
json
.fileType=json
json
è l’unico tipo di file supportato.{PREVIEW}
{SOURCE_PARAMS}
A Base64-stringa codificata che punta al percorso della risorsa da esplorare. Il percorso della risorsa deve essere codificato in Base64 per ottenere il formato approvato per {SOURCE_PARAMS}
. Ad esempio: {"resourcePath":"charges"}
è codificato come eyJyZXNvdXJjZVBhdGgiOiJjaGFyZ2VzIn0%3D
. L’elenco dei percorsi delle risorse disponibili include:
charges
subscriptions
refunds
balance_transactions
customers
prices
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/a9950001-a386-4642-a0cd-5eaac6db5556/explore?objectType=rest&object=json&fileType=json&preview=false&sourceParams=eyJyZXNvdXJjZVBhdGgiOiJjaGFyZ2VzIn0%3D' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce una struttura JSON come segue:
code language-json |
---|
|
Creare una connessione sorgente source-connection
Puoi creare una connessione sorgente effettuando una richiesta POST al /sourceConnections
endpoint del Flow Service API. Una connessione di origine è costituita da un ID di connessione, un percorso del file di dati di origine e un ID della specifica di connessione.
Formato API
POST /sourceConnections
Richiesta
La richiesta seguente crea una connessione sorgente per Stripe.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Stripe Source Connection For Charges Data",
"description": "Stripe source connection for charges data",
"baseConnectionId": "a9950001-a386-4642-a0cd-5eaac6db5556",
"connectionSpec": {
"id": "cc2c31d6-7b8c-4581-b49f-5c8698aa3ab3",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"resourcePath": "charges"
},
}'
name
description
baseConnectionId
connectionSpec.id
data.format
json
.In caso di esito positivo, la risposta restituisce l’identificatore univoco (id
) della connessione sorgente appena creata. Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "abbfac4e-202c-4e04-902d-6f73e9041068",
"etag": "\"0a033818-0000-0200-0000-65ea5a770000\""
}
Creare uno schema XDM di destinazione target-schema
Per utilizzare i dati di origine in Experienci Platform, è necessario creare uno schema di destinazione per strutturare i dati di origine in base alle tue esigenze. Lo schema di destinazione viene quindi utilizzato per creare un set di dati di Platform in cui sono contenuti i dati di origine.
È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST al API del registro dello schema.
Per i passaggi dettagliati su come creare uno schema XDM di destinazione, consulta l’esercitazione su creazione di uno schema tramite l’API.
Creare un set di dati di destinazione target-dataset
È possibile creare un set di dati di destinazione eseguendo una richiesta POST al API Catalog Service, che fornisce l’ID dello schema di destinazione all’interno del payload.
Per i passaggi dettagliati su come creare un set di dati di destinazione, consulta l’esercitazione su creazione di un set di dati tramite l’API.
Creare una connessione di destinazione target-connection
Una connessione di destinazione rappresenta la connessione alla destinazione in cui devono essere memorizzati i dati acquisiti. Per creare una connessione di destinazione, devi fornire l’ID della specifica di connessione fissa che corrisponde al data lake. Questo ID è: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Ora disponi degli identificatori univoci, di uno schema di destinazione, di un set di dati di destinazione e dell’ID della specifica di connessione al data lake. Utilizzando questi identificatori, puoi creare una connessione di destinazione utilizzando Flow Service API per specificare il set di dati che conterrà i dati di origine in entrata.
Formato API
POST /targetConnections
Richiesta
La richiesta seguente crea una connessione di destinazione per Stripe:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Stripe Target Connection For Charges Data",
"description": "Stripe target connection for charges data",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{ORG_ID}/schemas/5f76be8c4e4b847fdac13ca42aa6b596a89a5b91dea48b16",
"version": "application/vnd.adobe.xed-full+json;version=1.3"
}
},
"params": {
"dataSetId": "65e622315f78042c9e8166e8"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.data.format
params.dataSetId
Risposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco della nuova connessione di destinazione (id
). Questo ID è richiesto nei passaggi successivi.
{
"id": "69879751-ba43-48df-8cd0-39d2bb76a5b8",
"etag": "\"4b02ef5b-0000-0200-0000-65ea5f730000\""
}
Creare una mappatura mapping
Per poter acquisire i dati di origine in un set di dati di destinazione, è necessario prima mapparli sullo schema di destinazione a cui il set di dati di destinazione aderisce. Ciò si ottiene eseguendo una richiesta POST al Data Prep API con mappature di dati definite nel payload della richiesta.
Formato API
POST /conversion/mappingSets
La richiesta seguente crea una mappatura per Stripe.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Proprietà | Descrizione |
xdmSchema |
ID dello schema XDM di destinazione. Questo ID viene generato creando un schema XDM di destinazione. |
destinationXdmPath |
Il campo XDM a cui viene mappato l’attributo di origine. |
sourceAttribute |
Il campo dati di origine che viene mappato. |
identity |
Valore booleano che definisce se il campo verrà mantenuto in Servizio identità. |
version |
Versione di mappatura in uso. |
Risposta
In caso di esito positivo, la risposta restituisce i dettagli della mappatura appena creata, compreso l’identificatore univoco (id
). Questo valore è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "f4aad280fdec4770b7e33066945919d8",
"version": 0,
"createdDate": 1709860257007,
"modifiedDate": 1709860257007,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Creare un flusso flow
L’ultimo passaggio per importare dati da Stripe In Platform è necessario creare un flusso di dati. A questo punto sono stati preparati i seguenti valori obbligatori:
Un flusso di dati è responsabile della pianificazione e della raccolta di dati da un’origine. Puoi creare un flusso di dati eseguendo una richiesta POST e fornendo i valori precedentemente menzionati all’interno del payload.
Formato API
POST /flows
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Stripe Connector Flow Generic Rest",
"description": "Stripe Connector Description Flow Generic Rest",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"abbfac4e-202c-4e04-902d-6f73e9041068"
],
"targetConnectionIds": [
"69879751-ba43-48df-8cd0-39d2bb76a5b8"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "f4aad280fdec4770b7e33066945919d8",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1710267858",
"frequency": "minute",
"interval": {{interval}}
}
}'
name
description
flowSpec.id
6499120c-0b15-42dc-936e-847ea3c24d72
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.scheduleParams.startTime
scheduleParams.frequency
La frequenza con cui il flusso di dati raccoglierà i dati. Puoi configurare la frequenza di acquisizione in modo da:
- Una volta: imposta la frequenza su
once
per creare un’acquisizione unica. Le configurazioni di intervallo e backfill non sono disponibili quando crei un flusso di dati di acquisizione una tantum. Per impostazione predefinita, la frequenza di pianificazione è impostata su una volta. - Minuto: imposta la frequenza su
minute
per pianificare il flusso di dati per acquisire i dati al minuto. - Hour:Imposta la frequenza su
hour
per pianificare il flusso di dati per acquisire i dati su base oraria. - Giorno: imposta la frequenza su
day
pianificare il flusso di dati per acquisire i dati su base giornaliera. - Settimana: imposta la frequenza su
week
per pianificare il flusso di dati per acquisire i dati settimanalmente.
scheduleParams.interval
Risposta
In caso di esito positivo, la risposta restituisce l’ID (id
) del flusso di dati appena creato. Puoi usare questo ID per monitorare, aggiornare o eliminare il flusso di dati.
{
"id": "84c64142-1741-4b0b-95a9-65644eba0cf6",
"etag": "\"3901770b-0000-0200-0000-655708970000\""
}
Appendice
La sezione seguente fornisce informazioni sui passaggi da eseguire per monitorare, aggiornare ed eliminare il flusso di dati.
Monitorare il flusso di dati
Una volta creato il flusso di dati, puoi monitorare i dati che vengono acquisiti tramite di esso per visualizzare informazioni sulle esecuzioni del flusso, sullo stato di completamento e sugli errori. Per esempi API completi, consulta la guida su monitoraggio dei flussi di dati di origine tramite l’API.
Aggiornare il flusso di dati
Aggiorna i dettagli del flusso di dati, ad esempio il nome e la descrizione, nonché la pianificazione di esecuzione e i set di mappatura associati, effettuando una richiesta PATCH all’endpoint /flows del Flow Service fornendo l’ID del flusso di dati. Quando effettui una richiesta PATCH, devi fornire il codice univoco del flusso di dati etag
nel If-Match
intestazione. Per esempi API completi, consulta la guida su aggiornamento dei flussi di dati di origine tramite l’API.
Aggiornare l’account
Aggiorna il nome, la descrizione e le credenziali dell’account di origine eseguendo una richiesta PATCH al Flow Service fornendo l’ID connessione di base come parametro di query. Quando effettui una richiesta PATCH, devi fornire il codice univoco dell’account sorgente etag
nel If-Match
intestazione. Per esempi API completi, consulta la guida su aggiornamento dell’account sorgente tramite l’API.
Eliminare il flusso di dati
Elimina il flusso di dati eseguendo una richiesta DELETE al Flow Service fornendo l’ID del flusso di dati che desideri eliminare come parte del parametro di query. Per esempi API completi, consulta la guida su eliminazione dei flussi di dati tramite API.
Elimina l’account
Elimina l’account eseguendo una richiesta DELETE al Flow Service fornendo l’ID della connessione di base dell’account da eliminare. Per esempi API completi, consulta la guida su eliminazione dell’account sorgente tramite l’API.