Documentazione Experience Platform Guida ai connettori di origini

[Ultimate]{class="badge positive"}

Creare una connessione di origine Azure Event Hubs utilizzando l'API Flow Service

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:

Creato per:

Sviluppatore

IMPORTANT

L'origine Azure Event Hubs è disponibile nel catalogo delle origini per gli utenti che hanno acquistato Real-time Customer Data Platform Ultimate.

Leggi questo tutorial per scoprire come connettere Azure Event Hubs (di seguito "Event Hubs") all'Experience Platform, utilizzando Flow Service API.

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.

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per connettere correttamente Event Hubs a Platform utilizzando l'API Flow Service.

Raccogli le credenziali richieste

Affinché Flow Service possa connettersi al tuo account Event Hubs, devi fornire i valori per le seguenti proprietà di connessione:

Autenticazione standard

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Credenziali	Descrizione
`sasKeyName`	Il nome della regola di autorizzazione, noto anche come nome della chiave SAS.
`sasKey`	Chiave primaria dello spazio dei nomi Event Hubs. I `sasPolicy` a cui corrisponde `sasKey` devono avere `manage` diritti configurati affinché l'elenco Event Hubs possa essere popolato.
`namespace`	Spazio dei nomi di Event Hub a cui si sta effettuando l'accesso. Uno spazio dei nomi Event Hub fornisce un contenitore di ambito univoco, in cui è possibile creare uno o più Event Hubs.
`connectionSpec.id`	La specifica di connessione restituisce le proprietà del connettore di un'origine, incluse le specifiche di autenticazione relative alla creazione delle connessioni di base e di origine. ID della specifica di connessione Event Hubs: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`.

Autenticazione SAS

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Credenziali	Descrizione
`sasKeyName`	Il nome della regola di autorizzazione, noto anche come nome della chiave SAS.
`sasKey`	Chiave primaria dello spazio dei nomi Event Hubs. I `sasPolicy` a cui corrisponde `sasKey` devono avere `manage` diritti configurati affinché l'elenco Event Hubs possa essere popolato.
`namespace`	Spazio dei nomi di Event Hub a cui si sta effettuando l'accesso. Uno spazio dei nomi Event Hub fornisce un contenitore di ambito univoco, in cui è possibile creare uno o più Event Hubs.
`eventHubName`	Inserisci il nome Azure Event Hub. Per ulteriori informazioni sui nomi di Event Hub, leggere la documentazione di Microsoft.
`connectionSpec.id`	La specifica di connessione restituisce le proprietà del connettore di un'origine, incluse le specifiche di autenticazione relative alla creazione delle connessioni di base e di origine. ID della specifica di connessione Event Hubs: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`.

Per ulteriori informazioni sull'autenticazione delle firme di accesso condiviso per Event Hubs, leggere la Azure guida sull'utilizzo di SAS.

Hub eventi Azure Active Directory Auth

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Credenziali	Descrizione
`tenantId`	ID tenant a cui desideri richiedere l’autorizzazione. L’ID tenant può essere formattato come GUID o come nome descrittivo. Nota: nell'interfaccia Microsoft Azure l'ID tenant viene indicato come "ID directory".
`clientId`	L'ID applicazione assegnato alla tua app. Puoi recuperare questo ID dal portale Microsoft Entra ID in cui hai registrato Azure Active Directory.
`clientSecretValue`	Segreto client utilizzato insieme all’ID client per autenticare l’app. Puoi recuperare il segreto client dal portale Microsoft Entra ID in cui hai registrato Azure Active Directory.
`namespace`	Spazio dei nomi di Event Hub a cui si sta effettuando l'accesso. Uno spazio dei nomi Event Hub fornisce un contenitore di ambito univoco, in cui è possibile creare uno o più Event Hubs.

Per ulteriori informazioni su Azure Active Directory, leggere la Guida di Azure sull'utilizzo di Microsoft Entra ID.

Autenticazione Azure Active Directory con ambito hub eventi

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Credenziali	Descrizione
`tenantId`	ID tenant a cui desideri richiedere l’autorizzazione. L’ID tenant può essere formattato come GUID o come nome descrittivo. Nota: nell'interfaccia Microsoft Azure l'ID tenant viene indicato come "ID directory".
`clientId`	L'ID applicazione assegnato alla tua app. Puoi recuperare questo ID dal portale Microsoft Entra ID in cui hai registrato Azure Active Directory.
`clientSecretValue`	Segreto client utilizzato insieme all’ID client per autenticare l’app. Puoi recuperare il segreto client dal portale Microsoft Entra ID in cui hai registrato Azure Active Directory.
`namespace`	Spazio dei nomi di Event Hub a cui si sta effettuando l'accesso. Uno spazio dei nomi Event Hub fornisce un contenitore di ambito univoco, in cui è possibile creare uno o più Event Hubs.
`eventHubName`	Inserisci il nome Azure Event Hub. Per ulteriori informazioni sui nomi di Event Hub, leggere la documentazione di Microsoft.

Per ulteriori informazioni su questi valori, fare riferimento al documento Hub eventi.

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

TIP

Una volta creata, non è possibile modificare il tipo di autenticazione di una connessione di base Event Hubs. Per modificare il tipo di autenticazione, è necessario creare una nuova connessione di base.

Il primo passaggio nella creazione di una connessione di origine consiste nell'autenticare l'origine Event Hubs e generare un ID connessione di base. Un ID di connessione di base consente di esplorare e navigare tra i file dall’interno dell’origine e identificare elementi specifici da acquisire, incluse 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 Event Hubs come parte dei parametri della richiesta.

Formato API

POST /connections

Autenticazione standard

Per creare un account utilizzando l'autenticazione standard, effettuare una richiesta POST all'endpoint /connections fornendo i valori per sasKeyName, sasKey e namespace.

accordion

Richiesta

code language-shell

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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Azure EventHub authentication credentials",
          "params": {
              "sasKeyName": "{SAS_KEY_NAME}",
              "sasKey": "{SAS_KEY}",
              "namespace": "{NAMESPACE}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Proprietà	Descrizione
`auth.params.sasKeyName`	Il nome della regola di autorizzazione, noto anche come nome della chiave SAS.
`auth.params.sasKey`	Firma di accesso condiviso generata.
`auth.params.namespace`	Spazio dei nomi di Event Hubs a cui si sta effettuando l'accesso.
`connectionSpec.id`	L'ID della specifica di connessione Event Hubs è: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Risposta

In caso di esito positivo, la risposta restituisce i dettagli della connessione di base appena creata, incluso il relativo identificatore univoco (id). Questo ID connessione è richiesto nel passaggio successivo per creare una connessione sorgente.

code language-json
`{ "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe", "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\"" }`

Autenticazione SAS

Per creare un account utilizzando l'autenticazione SAS, eseguire una richiesta POST all'endpoint /connections fornendo i valori per sasKeyName, sasKey,namespace e eventHubName.

accordion

Richiesta

code language-shell

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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Azure EventHub authentication credentials",
          "params": {
              "sasKeyName": "{SAS_KEY_NAME}",
              "sasKey": "{SAS_KEY}",
              "namespace": "{NAMESPACE}",
              "eventHubName": "{EVENT_HUB_NAME}
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Proprietà	Descrizione
`auth.params.sasKeyName`	Il nome della regola di autorizzazione, noto anche come nome della chiave SAS.
`auth.params.sasKey`	Firma di accesso condiviso generata.
`auth.params.namespace`	Spazio dei nomi di Event Hubs a cui si sta effettuando l'accesso.
`params.eventHubName`	Nome dell'origine Event Hubs.
`connectionSpec.id`	L'ID della specifica di connessione Event Hubs è: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Risposta

code language-json
`{ "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe", "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\"" }`

Hub eventi Azure Active Directory Auth

Per creare un account utilizzando Azure Active Directory Auth, eseguire una richiesta POST all'endpoint /connections fornendo i valori per tenantId, clientId,clientSecretValue e namespace.

accordion

Richiesta

code language-shell

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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Event Hub Azure Active Directory Auth",
          "params": {
              "tenantId": "{TENANT_ID}",
              "clientId": "{CLIENT_ID}",
              "clientSecretValue": "{CLIENT_SECRET_VALUE}",
              "namespace": "{NAMESPACE}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Proprietà	Descrizione
`auth.params.tenantId`	ID tenant dell’applicazione. Nota: nell'interfaccia Microsoft Azure l'ID tenant viene indicato come "ID directory".
`auth.params.clientId`	L’ID cliente dell’organizzazione.
`auth.params.clientSecretValue`	Il valore segreto client dell’organizzazione.
`auth.params.namespace`	Spazio dei nomi di Event Hubs a cui si sta effettuando l'accesso.
`connectionSpec.id`	L'ID della specifica di connessione Event Hubs è: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Risposta

code language-json
`{ "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe", "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\"" }`

Autenticazione Azure Active Directory con ambito hub eventi

Per creare un account utilizzando Azure Active Directory Auth, eseguire una richiesta POST all'endpoint /connections fornendo i valori per tenantId, clientId, clientSecretValue, namespace e eventHubName.

accordion

Richiesta

code language-shell

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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Event Hub Scoped Azure Active Directory Auth",
          "params": {
              "tenantId": "{TENANT_ID}",
              "clientId": "{CLIENT_ID}",
              "clientSecretValue": "{CLIENT_SECRET_VALUE}",
              "namespace": "{NAMESPACE}",
              "eventHubName": "{EVENT_HUB_NAME}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2
Proprietà	Descrizione
`auth.params.tenantId`	ID tenant dell’applicazione. Nota: nell'interfaccia Microsoft Azure l'ID tenant viene indicato come "ID directory".
`auth.params.clientId`	L’ID cliente dell’organizzazione.
`auth.params.clientSecretValue`	Il valore segreto client dell’organizzazione.
`auth.params.namespace`	Spazio dei nomi di Event Hubs a cui si sta effettuando l'accesso.
`auth.params.eventHubName`	Nome dell'origine Event Hubs.
`connectionSpec.id`	L'ID della specifica di connessione Event Hubs è: `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Risposta

code language-json
`{ "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe", "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\"" }`

Creare una connessione sorgente

TIP

Un gruppo di consumer Event Hubs può essere utilizzato solo per un singolo flusso alla volta.

Una connessione di origine crea e gestisce la connessione all’origine esterna da cui vengono acquisiti i dati. Una connessione di origine è costituita da informazioni quali origine dati, formato dati e un ID di connessione di origine necessari per creare un flusso di dati. Un'istanza della connessione di origine è specifica di un tenant e di un'organizzazione.

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": "Azure Event Hubs source connection",
      "description": "A source connection for Azure Event Hubs",
      "baseConnectionId": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      },
      "params": {
          "eventHubName": "{EVENT_HUB_NAME}",
          "dataType": "raw",
          "reset": "latest",
          "consumerGroup": "{CONSUMER_GROUP}"
      }
  }'

Proprietà

Descrizione

name

Nome della connessione di origine. Assicurati che il nome della connessione sorgente sia descrittivo, in quanto può essere utilizzato per cercare informazioni sulla connessione sorgente.

description

Valore facoltativo che è possibile fornire per includere ulteriori informazioni sulla connessione di origine.

baseConnectionId

ID di connessione dell'origine Event Hubs generato nel passaggio precedente.

connectionSpec.id

ID della specifica di connessione fissa per Event Hubs. ID: bf9f5905-92b7-48bf-bf20-455bc6b60a4e.

data.format

Formato dei dati Event Hubs che si desidera acquisire. Attualmente, l'unico formato di dati supportato è json.

params.eventHubName

Nome dell'origine Event Hubs.

params.dataType

Questo parametro definisce il tipo di dati che viene acquisito. I tipi di dati supportati sono: raw e xdm.

params.reset

Questo parametro definisce la modalità di lettura dei dati. Utilizza latest per iniziare a leggere dai dati più recenti e earliest per iniziare a leggere dai primi dati disponibili nel flusso. Questo parametro è facoltativo e, se non specificato, viene impostato automaticamente su earliest.

params.consumerGroup

Meccanismo di pubblicazione o sottoscrizione da utilizzare per Event Hubs. Questo parametro è facoltativo e, se non specificato, viene impostato automaticamente su $Default. Per ulteriori informazioni, consulta questa Event Hubs guida sugli eventi consumer. Nota: un gruppo di consumer Event Hubs può essere utilizzato solo per un singolo flusso in un determinato momento.

Passaggi successivi

Seguendo questa esercitazione, è stata creata una connessione di origine Event Hubs utilizzando l'API Flow Service. Puoi utilizzare questo ID connessione di origine nella prossima esercitazione per creare un flusso di dati in streaming utilizzando l' Flow Service API.

recommendation-more-help

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