[Ultimate]{class="badge positive"}

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

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

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\""
}
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

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

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\""
}

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