Documentation Experience Platform Guide des connecteurs sources

[Ultimate]{class="badge positive"}

Créez une connexion source Azure Event Hubs à l’aide de l’API Flow Service

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

Rubriques :

Créé pour :

Développeur

IMPORTANT

La source Azure Event Hubs est disponible dans le catalogue des sources pour les utilisateurs qui ont acheté Real-Time Customer Data Platform Ultimate.

Lisez ce tutoriel pour apprendre à connecter Azure Event Hubs (ci-après appelé "Event Hubs") à l’Experience Platform à l’aide de l’Flow Service API.

Prise en main

Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :

Sources : Experience Platform permet d’ingérer des données provenant de diverses sources tout en vous offrant la possibilité de structurer, d’étiqueter et d’améliorer les données entrantes à l’aide des services Platform.
Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.

Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour réussir à connecter Event Hubs à Platform à l’aide de l’API Flow Service.

Collecter les informations d’identification requises

Pour que Flow Service se connecte à votre compte Event Hubs, vous devez fournir des valeurs pour les propriétés de connexion suivantes :

Authentification standard

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Informations d’identification	Description
`sasKeyName`	Nom de la règle d’autorisation, également connu sous le nom de clé SAS.
`sasKey`	Clé primaire de l’espace de noms Event Hubs. Les droits `sasPolicy` auxquels correspond `sasKey` doivent être `manage` configurés pour que la liste Event Hubs soit renseignée.
`namespace`	L’espace de noms du Event Hub auquel vous accédez. Un espace de noms Event Hub fournit un conteneur d’étendue unique, dans lequel vous pouvez créer un ou plusieurs Event Hubs.
`connectionSpec.id`	La spécification de connexion renvoie les propriétés du connecteur d’une source, y compris les spécifications d’authentification liées à la création des connexions de base et source. L’identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`.

Authentification SAS

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Informations d’identification	Description
`sasKeyName`	Nom de la règle d’autorisation, également connu sous le nom de clé SAS.
`sasKey`	Clé primaire de l’espace de noms Event Hubs. Les droits `sasPolicy` auxquels correspond `sasKey` doivent être `manage` configurés pour que la liste Event Hubs soit renseignée.
`namespace`	L’espace de noms du Event Hub auquel vous accédez. Un espace de noms Event Hub fournit un conteneur d’étendue unique, dans lequel vous pouvez créer un ou plusieurs Event Hubs.
`eventHubName`	Renseignez votre nom Azure Event Hub. Lisez la documentation Microsoft pour plus d’informations sur les Event Hub noms.
`connectionSpec.id`	La spécification de connexion renvoie les propriétés du connecteur d’une source, y compris les spécifications d’authentification liées à la création des connexions de base et source. L’identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`.

Pour plus d'informations sur l'authentification SAS (Shared Access Signatures) pour Event Hubs, consultez le Azure guide sur l'utilisation de SAS.

Event Hub Azure Active Directory Auth

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Informations d’identification	Description
`tenantId`	Identifiant du tenant auprès duquel vous souhaitez demander une autorisation. Votre ID de tenant peut être formaté sous la forme d’un GUID ou d’un nom convivial. Remarque : L’ID de client est appelé "ID de répertoire" dans l’interface Microsoft Azure.
`clientId`	ID d’application affecté à votre application. Vous pouvez récupérer cet ID à partir du portail Microsoft Entra ID sur lequel vous avez enregistré votre Azure Active Directory.
`clientSecretValue`	Le secret client utilisé avec l’ID client pour authentifier votre application. Vous pouvez récupérer votre secret client à partir du portail Microsoft Entra ID sur lequel vous avez enregistré votre Azure Active Directory.
`namespace`	L’espace de noms du Event Hub auquel vous accédez. Un espace de noms Event Hub fournit un conteneur d’étendue unique, dans lequel vous pouvez créer un ou plusieurs Event Hubs.

Pour plus d’informations sur Azure Active Directory, consultez le guide Azure sur l’utilisation de l’ID d’entrée Microsoft.

Event Hub Portée Azure Active Directory Auth

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Informations d’identification	Description
`tenantId`	Identifiant du tenant auprès duquel vous souhaitez demander une autorisation. Votre ID de tenant peut être formaté sous la forme d’un GUID ou d’un nom convivial. Remarque : L’ID de client est appelé "ID de répertoire" dans l’interface Microsoft Azure.
`clientId`	ID d’application affecté à votre application. Vous pouvez récupérer cet ID à partir du portail Microsoft Entra ID sur lequel vous avez enregistré votre Azure Active Directory.
`clientSecretValue`	Le secret client utilisé avec l’ID client pour authentifier votre application. Vous pouvez récupérer votre secret client à partir du portail Microsoft Entra ID sur lequel vous avez enregistré votre Azure Active Directory.
`namespace`	L’espace de noms du Event Hub auquel vous accédez. Un espace de noms Event Hub fournit un conteneur d’étendue unique, dans lequel vous pouvez créer un ou plusieurs Event Hubs.
`eventHubName`	Renseignez votre nom Azure Event Hub. Lisez la documentation Microsoft pour plus d’informations sur les Event Hub noms.

Pour plus d’informations sur ces valeurs, reportez-vous à ce document Event Hubs.

Utiliser les API Platform

Pour plus d’informations sur la manière d’effectuer avec succès des appels vers les API Platform, consultez le guide sur la Prise en main des API Platform.

Créer une connexion de base

TIP

Une fois créé, vous ne pouvez pas modifier le type d'authentification d'une connexion de base Event Hubs. Pour modifier le type d'authentification, vous devez créer une nouvelle connexion de base.

La première étape de création d’une connexion source consiste à authentifier votre source Event Hubs et à générer un identifiant de connexion de base. Un identifiant de connexion de base vous permet d’explorer et de parcourir les fichiers de votre source et d’identifier les éléments spécifiques à ingérer, y compris des informations concernant leurs types et formats de données.

Pour créer un identifiant de connexion de base, envoyez une requête POST au point d’entrée /connections lors de la fourniture des informations d’identification d’authentification Event Hubs dans le cadre des paramètres de requête.

Format d’API

POST /connections

Authentification standard

Pour créer un compte à l’aide de l’authentification standard, envoyez une requête de POST au point de terminaison /connections tout en fournissant des valeurs pour vos sasKeyName, sasKey et namespace.

accordion

Requête

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
Propriété	Description
`auth.params.sasKeyName`	Nom de la règle d’autorisation, également connu sous le nom de clé SAS.
`auth.params.sasKey`	Signature d’accès partagé générée.
`auth.params.namespace`	L’espace de noms du Event Hubs auquel vous accédez.
`connectionSpec.id`	L'identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Réponse

Une réponse réussie renvoie les détails de la connexion de base que vous venez de créer, y compris son identifiant unique (id). Cet identifiant de connexion est requis à l’étape suivante pour créer une connexion source.

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

Authentification SAS

Pour créer un compte à l’aide de l’authentification SAS, envoyez une requête de POST au point de terminaison /connections tout en fournissant des valeurs pour vos sasKeyName, sasKey, namespace et eventHubName.

accordion

Requête

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
Propriété	Description
`auth.params.sasKeyName`	Nom de la règle d’autorisation, également connu sous le nom de clé SAS.
`auth.params.sasKey`	Signature d’accès partagé générée.
`auth.params.namespace`	L’espace de noms du Event Hubs auquel vous accédez.
`params.eventHubName`	Nom de la source Event Hubs.
`connectionSpec.id`	L'identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Réponse

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

Event Hub Azure Active Directory Auth

Pour créer un compte à l’aide de l’authentification Azure Active Directory, envoyez une requête de POST au point de terminaison /connections tout en fournissant des valeurs pour vos tenantId, clientId, clientSecretValue et namespace.

accordion

Requête

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
Propriété	Description
`auth.params.tenantId`	Identifiant du tenant de votre application. Remarque : L’ID de client est appelé "ID de répertoire" dans l’interface Microsoft Azure.
`auth.params.clientId`	ID client de votre organisation.
`auth.params.clientSecretValue`	La valeur du secret client de votre organisation.
`auth.params.namespace`	L’espace de noms du Event Hubs auquel vous accédez.
`connectionSpec.id`	L'identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Réponse

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

Event Hub Portée Azure Active Directory Auth

accordion

Requête

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
Propriété	Description
`auth.params.tenantId`	Identifiant du tenant de votre application. Remarque : L’ID de client est appelé "ID de répertoire" dans l’interface Microsoft Azure.
`auth.params.clientId`	ID client de votre organisation.
`auth.params.clientSecretValue`	La valeur du secret client de votre organisation.
`auth.params.namespace`	L’espace de noms du Event Hubs auquel vous accédez.
`auth.params.eventHubName`	Nom de la source Event Hubs.
`connectionSpec.id`	L'identifiant de spécification de connexion Event Hubs est : `bf9f5905-92b7-48bf-bf20-455bc6b60a4e`

accordion

Réponse

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

Créer une connexion source

TIP

Un groupe de consommateurs Event Hubs ne peut être utilisé que pour un seul flux à la fois.

Une connexion source crée et gère la connexion à la source externe à partir de laquelle les données sont ingérées. Une connexion source se compose d’informations telles que la source de données, le format de données et un identifiant de connexion source nécessaires à la création d’un flux de données. Une instance de connexion source est spécifique à un client et à une organisation.

Pour créer une connexion source, envoyez une requête POST au point d’entrée /sourceConnections de l’API Flow Service.

Format d’API

POST /sourceConnections

Requête

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

Propriété

Description

name

Nom de votre connexion source. Assurez-vous que le nom de votre connexion source est descriptif, car vous pouvez l’utiliser pour rechercher des informations sur votre connexion source.

description

Valeur facultative que vous pouvez fournir pour inclure plus d’informations sur votre connexion source.

baseConnectionId

L’identifiant de connexion de la source Event Hubs qui a été généré à l’étape précédente.

connectionSpec.id

Identifiant de spécification de connexion fixe pour Event Hubs. Cet identifiant est bf9f5905-92b7-48bf-bf20-455bc6b60a4e.

data.format

Format des données Event Hubs que vous souhaitez ingérer. Actuellement, le format de données json est le seul à être pris en charge.

params.eventHubName

Nom de la source Event Hubs.

params.dataType

Ce paramètre définit le type des données ingérées. Les types de données pris en charge sont les suivants : raw et xdm.

params.reset

Ce paramètre définit la manière dont les données seront lues. Utilisez latest pour commencer la lecture à partir des données les plus récentes et earliest pour commencer la lecture à partir des premières données disponibles dans le flux. Ce paramètre est facultatif et la valeur par défaut est earliest s’il n’est pas fourni.

params.consumerGroup

Mécanisme de publication ou d’abonnement à utiliser pour Event Hubs. Ce paramètre est facultatif et la valeur par défaut est $Default s’il n’est pas fourni. Pour plus d’informations, consultez ce Event Hubs guide sur les consommateurs d’événements . Remarque : Un groupe de consommateurs Event Hubs ne peut être utilisé que pour un seul flux à la fois.

Étapes suivantes

En suivant ce tutoriel, vous avez créé une connexion source Event Hubs à l’aide de l’API Flow Service. Vous pouvez utiliser cet ID de connexion source dans le tutoriel suivant pour créer un flux de données en continu à l’aide de l’API Flow Service.

recommendation-more-help

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