Documentazione Experience Platform Guida ai connettori di origini

[Beta]{class="badge informative"} [Ultimate]{class="badge positive"}

Trasmetti i dati Snowflake all'Experience Platform utilizzando l'API Flow Service

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:

Creato per:

Sviluppatore

IMPORTANT

L'origine di streaming Snowflake è in versione beta. Per ulteriori informazioni sull'utilizzo di origini con etichetta beta, leggere la Panoramica origini.
L'origine di streaming Snowflake è disponibile nell'API per gli utenti che hanno acquistato Real-time Customer Data Platform Ultimate.

Questo tutorial illustra i passaggi necessari per collegare e inviare dati dall'account Snowflake a Adobe Experience Platform utilizzando l'[Flow Service API] (https://www.adobe.io/experience-platform-apis/references/flow-service/).

Introduzione

Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:

Origini: Experience Platform consente l'acquisizione di dati da varie origini e consente di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi Platform.
Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza di Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Per la configurazione dei prerequisiti e informazioni sull'origine di streaming Snowflake. Leggere la Snowflake panoramica origine streaming.

Utilizzo delle API di Platform

Per informazioni su come effettuare correttamente chiamate alle API di Platform, consulta la guida in guida introduttiva alle API di Platform.

Creare una connessione di base create-a-base-connection

Una connessione di base mantiene le informazioni tra l’origine e Platform, incluse le credenziali di autenticazione dell’origine, lo stato corrente della connessione e l’ID univoco della connessione di base. L’ID della connessione di base consente di esplorare e navigare tra i file dall’interno dell’origine e identificare gli elementi specifici che desideri acquisire, comprese le informazioni relative ai tipi di dati e ai formati.

Per creare un ID di connessione di base, effettuare una richiesta POST all'endpoint /connections fornendo le credenziali di autenticazione Snowflake come parte del corpo della richiesta.

Formato API

POST /connections

Richiesta

La richiesta seguente crea una connessione di base per Snowflake:

TIP

Il valore auth.specName deve essere immesso esattamente come nell'esempio seguente, inclusi gli spazi vuoti.

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": "Snowflake base connection",
      "description": "Snowflake base connection",
      "auth": {
          "specName": "Basic Authentication for Snowflake",
          "params": {
              "account": "wixnnnd-ui60793.snowflakecomputing.com",
              "database": "ACME_DB",
              "warehouse": "ACME_WH",
              "username": "nikola15",
              "schema": "PUBLIC",
              "password": "xxxx",
              "role": "ACCOUNTADMIN"
          }
      },
      "connectionSpec": {
          "id": "51ae16c2-bdad-42fd-9fce-8d5dfddaf140",
          "version": "1.0"
      }
  }'

Proprietà

Descrizione

auth.params.account

Nome dell'account di streaming Snowflake.

auth.params.database

Il nome del database Snowflake da cui verranno estratti i dati.

auth.params.warehouse

Nome del data warehouse Snowflake. Il data warehouse Snowflake gestisce il processo di esecuzione delle query per l'applicazione. Ogni data warehouse è indipendente l’uno dall’altro e deve essere accessibile singolarmente quando si trasferiscono i dati su Platform.

auth.params.username

Nome utente per l'account di streaming Snowflake.

auth.params.schema

(Facoltativo) Lo schema di database associato all'account di streaming Snowflake.

auth.params.password

Password per l'account di streaming Snowflake.

auth.params.role

(Facoltativo) Ruolo dell'utente per questa connessione Snowflake. Se non specificato, il valore predefinito è public.

connectionSpec.id

ID della specifica di connessione Snowflake: 51ae16c2-bdad-42fd-9fce-8d5dfddaf140.

Risposta

In caso di esito positivo, la risposta restituisce la connessione di base appena creata e il tag corrispondente.

{
    "id": "1b614dc0-b76e-41e1-b25f-09f4a9d3f111",
    "etag": "\"d300cf4e-0000-0200-0000-6447a7750000\""
}

Esplora le tabelle di dati explore-your-data-tables

Utilizzare quindi l'ID connessione di base per esplorare e spostarsi tra le tabelle dati dell'origine effettuando una richiesta di GET all'endpoint /connections/{BASE_CONNECTION_ID}/explore?objectType=root e fornendo l'ID connessione di base come parametro.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=root

Parametro

Descrizione

{BASE_CONNECTION_ID}

ID connessione di base dell'origine di streaming Snowflake.

Richiesta

La richiesta seguente recupera la struttura e il contenuto dell'account di streaming Snowflake.

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/1b614dc0-b76e-41e1-b25f-09f4a9d3f111/explore?objectType=root' \
  -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 la struttura e il contenuto dei dati dell’origine a livello di radice.

{
    "items": [
        {
            "type": "table",
            "name": "ACME"
        }
    ]
}

Proprietà

Descrizione

items.type

Tipo della tabella.

items.names

Nome della tabella.

Creare una connessione sorgente create-a-source-connection

Una connessione di origine crea e gestisce la connessione all’origine esterna da cui vengono acquisiti i dati.

Per creare una connessione di origine, effettuare una richiesta POST all'endpoint /sourceConnections dell'API Flow Service.

Formato API

POST /sourceConnections

Richiesta

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -H 'authorization: Bearer {ACCESS_TOKEN}' \
  -H 'content-type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
      "name": "Snowflake Streaming Source Connection",
      "description": "A source connection for Snowflake Streaming data",
      "baseConnectionId": "1b614dc0-b76e-41e1-b25f-09f4a9d3f111",
      "connectionSpec": {
          "id": "51ae16c2-bdad-42fd-9fce-8d5dfddaf140",
          "version": "1.0"
      },
      "params": {
          "tableName": "ACME",
          "timestampColumn": "dOb",
          "backfill": "true",
          "timezoneValue": "PST"
      }
  }'

Proprietà

Descrizione

baseConnectionId

ID di connessione di base autenticato per l'origine di streaming Snowflake. Questo ID è stato generato in un passaggio precedente.

connectionSpec.id

ID della specifica di connessione per l'origine di streaming Snowflake.

params.tableName

Nome della tabella nel database Snowflake che si desidera portare in Platform.

params.timestampColumn

Nome della colonna timestamp che verrà utilizzata per recuperare i valori incrementali.

params.backfill

Flag booleano che determina se i dati vengono recuperati dall’inizio (0 epoca) o dal momento in cui viene avviata l’origine. Per ulteriori informazioni su questo valore, leggere la Snowflake panoramica origine streaming.

params.timezoneValue

Il valore del fuso orario indica l'ora corrente del fuso orario da recuperare durante la query sul database Snowflake. Questo parametro deve essere fornito se la colonna timestamp nella configurazione è impostata su TIMESTAMP_NTZ. Se non specificato, per impostazione predefinita timezoneValue viene utilizzato il valore UTC.

Risposta

In caso di esito positivo, la risposta restituisce l’ID della connessione sorgente e l’eTag corrispondente. L’ID della connessione di origine verrà utilizzato in un passaggio successivo per creare un flusso di dati.

{
    "id": "61c0c5f1-bfe5-40f7-8f8c-a4dc175ddac6",
    "etag": "\"d300cf4e-0000-0200-0000-6447a7750000\""
}

Creare un flusso di dati

Per creare un flusso di dati per inviare dati dall'account tour Snowflake a Platform, è necessario effettuare una richiesta POST all'endpoint /flows fornendo i seguenti valori:

TIP

Segui i collegamenti riportati di seguito per guide dettagliate su come recuperare i seguenti ID.

Formato API

POST /flows

Richiesta

La richiesta seguente crea un flusso di dati in streaming per il tuo account Snowflake.

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": "Snowflake Streaming Dataflow",
      "description": "A dataflow for Snowflake streaming data",
      "sourceConnectionIds": [
        "61c0c5f1-bfe5-40f7-8f8c-a4dc175ddac6"
      ],
      "targetConnectionIds": [
        "78f41c31-3652-4a5e-b264-74331226dcf3"
      ],
      "flowSpec": {
        "id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
        "version": "1.0"
      },
      "transformations": [
        {
          "name": "Mapping",
          "params": {
            "mappingId": "44d42ed27c46499a80eb0c0705c38cbd",
            "mappingVersion": 0
          }
        }
      ]
    }'

Proprietà

Descrizione

sourceConnectionIds

ID della connessione di origine per l'origine di streaming Snowflake.

targetConnectionIds

ID della connessione di destinazione per l'origine di streaming Snowflake.

flowSpec.id

ID della specifica di flusso per creare un flusso di dati per un'origine di flusso Snowflake. Questo ID della specifica di flusso consente di creare un flusso di dati in streaming con le trasformazioni di mappatura. L'ID è corretto ed è: c1a19761-d2c7-4702-b9fa-fe91f0613e81.

transformations.params.mappingId

ID di mappatura per il flusso di dati.

Risposta

In caso di esito positivo, la risposta restituisce l’ID di flusso e l’eTag corrispondente.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}

Passaggi successivi

Seguendo questa esercitazione, hai creato un flusso di dati in streaming per i tuoi dati Snowflake utilizzando l'API Flow Service. Per ulteriori informazioni sulle origini di Adobe Experience Platform, consulta la seguente documentazione:

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089