Documentation Experience Platform Guide des connecteurs sources

[Version bêta]{class="badge informative"}

Créez une connexion source et un flux de données pour Pendo à l’aide de l’API Flow Service

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

Rubriques :

Créé pour :

Développeur

NOTE

La source Pendo est en version Beta. Veuillez lire la présentation des sources pour plus d’informations sur l’utilisation de sources étiquetées bêta.

Le tutoriel suivant vous guide tout au long des étapes nécessaires à la création d’une connexion source et d’un flux de données pour importer des données d’événement Pendo vers Adobe Experience Platform à l’aide de l’ Flow Service API.

Prise en main getting-started

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

Sources : Experience Platform permet d’ingérer des données provenant de diverses sources tout en vous permettant 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 de plateforme unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.

Connectez Pendo à Platform à l’aide de l’API Flow Service connect-platform-to-flow-api

Les étapes suivantes décrivent les étapes à suivre pour créer une connexion source et un flux de données afin d’importer vos données d’événements Pendo dans Experience Platform.

Créer une connexion source source-connection

Créez une connexion source en adressant une requête de POST à l’API Flow Service, tout en fournissant l’identifiant de spécification de connexion de votre source, des détails tels que le nom et la description, et le format de vos données.

Format d’API

POST /sourceConnections

Requête

La requête suivante crée une connexion source pour Pendo :

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": "Streaming Source Connection for Pendo",
      "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
      "description": "Streaming Source Connection for Pendo",
      "connectionSpec": {
          "id": "6ff5654f-19d5-427d-bd3e-c0ebc802389a",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      }
    }'

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 inclure pour fournir plus d’informations sur votre connexion source.

connectionSpec.id

Identifiant de spécification de connexion correspondant à votre source.

data.format

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

Réponse

Une réponse réussie renvoie l’identifiant unique (id) de la nouvelle connexion source. Cet identifiant est requis lors d’une étape ultérieure pour créer un flux de données.

{
    "id": "76b968ff-3ff0-4e98-98bb-f3205d4d370c",
    "etag": "\"0301c198-0000-0200-0000-63f32ba50000\""
}

Créer un schéma XDM cible target-schema

Pour que les données sources soient utilisées dans Platform, un schéma cible doit être créé pour structurer les données sources en fonction de vos besoins. Le schéma cible est ensuite utilisé pour créer un jeu de données Platform contenant les données sources.

Un schéma XDM cible peut être créé en adressant une requête POST à l’API Schema Registry.

Pour obtenir des instructions détaillées sur la création d’un schéma XDM cible, suivez le tutoriel sur la création d’un schéma à l’aide de l’API.

Créer un jeu de données cible target-dataset

Un jeu de données cible peut être créé en adressant une requête POST à l’API Catalog Service et en fournissant l’identifiant du schéma cible dans la payload.

Pour obtenir des instructions détaillées sur la création d’un jeu de données cible, suivez le tutoriel sur la création d’un jeu de données à l’aide de l’API.

Créer une connexion cible target-connection

Une connexion cible représente la connexion à la destination vers laquelle les données ingérées doivent être stockées. Pour créer une connexion cible, vous devez fournir l’identifiant de spécification de connexion fixe qui correspond au lac de données. Cet identifiant est c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Vous disposez désormais des identifiants uniques d’un schéma cible d’un jeu de données cible et de l’identifiant de spécification de connexion au lac de données. À lʼaide de ces identifiants, vous pouvez créer une connexion cible à l’aide de l’API Flow Service pour spécifier le jeu de données qui contiendra les données source entrantes.

Format d’API

POST /targetConnections

Requête

La requête suivante crée une connexion cible pour Pendo :

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": "Streaming Target Connection for Pendo",
      "description": "Streaming Target Connection for Pendo",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "json",
          "schema": {
              "id": "https://ns.adobe.com/extconndev/schemas/b48de0b204046e65a4c50232e7946401946b4c519fd7c172",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "63dca52231a6031c07280614"
      }
  }'

Propriété

Description

name

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

description

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

connectionSpec.id

L’identifiant de spécification de connexion qui correspond au lac de données. Cet ID fixe est c604ff05-7f1a-43c0-8e18-33bf874cb11c.

data.format

Format des données Pendo à ingérer.

params.dataSetId

Identifiant du jeu de données cible récupéré lors d’une étape précédente.

Réponse

Une réponse réussie renvoie l’identifiant unique de la nouvelle connexion cible (id). Cet identifiant est requis aux étapes suivantes.

{
    "id": "c63978c1-df7e-4611-aa32-3657eab5704b",
    "etag": "\"7f0045f1-0000-0200-0000-63f32c9d0000\""
}

Créer un mappage mapping

Pour que les données sources soient ingérées dans un jeu de données cible, elles doivent d’abord être mappées au schéma cible auquel le jeu de données cible se rattache. Pour ce faire, effectuez une requête de POST vers Data Prep API avec des mappages de données définis dans le payload de la requête.

Format d’API

POST /conversion/mappingSets

Requête

curl -X POST \
  'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
  -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 '{
      "outputSchema": {
          "schemaRef": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
              "contentType": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
    "mappings": [
        {
            "destinationXdmPath": "_extconndev.accountid",
            "sourceAttribute": "accountId",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.uniqueid",
            "sourceAttribute": "uniqueId",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.name1",
            "sourceAttribute": "properties.guideProperties.name",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.timestamp1",
            "sourceAttribute": "timestamp",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.visitorid",
            "sourceAttribute": "visitorId",
            "identity": false,
            "version": 0
        }
    ]
  }'

Propriété

Description

outputSchema.schemaRef.id

Identifiant du schéma XDM cible généré lors d’une étape précédente.

mappings.sourceType

Type d’attribut source en cours de mappage.

mappings.source

Attribut source qui doit être mappé à un chemin XDM de destination.

mappings.destination

Chemin XDM de destination vers lequel l’attribut source est mappé.

Réponse

Une réponse réussie renvoie les détails du mappage nouvellement créé, y compris son identifiant unique (id). Cette valeur est requise lors d’une étape ultérieure pour créer un flux de données.

{
    "id": "a126ae1a1d134c4b82bd00c2d01a039e",
    "version": 0,
    "createdDate": 1676881164541,
    "modifiedDate": 1676881164541,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

Créer un flux flow

La dernière étape pour apporter des données de Pendo à Platform consiste à créer un flux de données. Vous disposez à présent des valeurs requises suivantes :

ID de connexion source
ID de connexion cible
Identifiant de mappage

Un flux de données est chargé de planifier et de collecter les données provenant d’une source. Vous pouvez créer un flux de données en exécutant une requête POST et en fournissant les valeurs mentionnées précédemment dans la payload.

Format d’API

POST /flows

Requête

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": "Streaming Dataflow for Pendo",
      "description": "Streaming Dataflow for Pendo",
      "flowSpec": {
          "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "339d60a5-9ff6-4eba-8197-e8887eeb3c08"
      ],
      "targetConnectionIds": [
          "df7c660e-3484-463b-b01a-1835e9b04ac9"
      ],
      "transformations": [
      {
        "name": "Mapping",
        "params": {
          "mappingId": "bae11501021646e58cecc1182451af22",
          "mappingVersion": 0
        }
      }
    ]
  }'

Propriété

Description

name

Nom du flux de données. Assurez-vous que le nom de votre flux de données est explicite, car vous pouvez l’utiliser pour rechercher des informations sur votre flux de données.

description

Une valeur facultative que vous pouvez inclure pour fournir plus d’informations sur votre flux de données.

flowSpec.id

Identifiant de spécification de flux requis pour créer un flux de données. Cet ID fixe est e77fde5a-22a8-11ed-861d-0242ac120002.

flowSpec.version

Version correspondante de l’identifiant de spécification de flux. Cette valeur est définie par défaut sur 1.0.

sourceConnectionIds

L’identifiant de connexion source généré lors d’une étape précédente.

targetConnectionIds

Identifiant de connexion cible généré lors d’une étape précédente.

transformations

Cette propriété contient les différentes transformations qui doivent être appliquées à vos données. Cette propriété est requise lors de l’importation de données non conformes à XDM dans Platform.

transformations.name

Nom attribué à la transformation.

transformations.params.mappingId

Identifiant de mappage généré lors d’une étape précédente.

transformations.params.mappingVersion

Version correspondante de l’identifiant de mappage. Ce paramètre est défini par défaut sur 0.

Réponse

Une réponse réussie renvoie l’identifiant (id) du flux de données nouvellement créé. Vous pouvez utiliser cet identifiant pour surveiller, mettre à jour ou supprimer votre flux de données.

{
    "id": "c341617b-e143-43d5-aff1-da02b3e028b6",
    "etag": "\"9c01173c-0000-0200-0000-63f32d7c0000\""
}

Obtention de l’URL de votre point de terminaison de diffusion get-streaming-url

Une fois votre flux de données créé, vous pouvez désormais récupérer l’URL de votre point de terminaison de diffusion en continu. Vous utiliserez cette URL de point de terminaison pour abonner votre source à un webhook, ce qui vous permettra de communiquer avec votre Experience Platform.

Pour récupérer l’URL de votre point de terminaison de diffusion en continu, envoyez une requête GET au point de terminaison /flows et fournissez l’identifiant de votre flux de données.

Format d’API

GET /flows/{FLOW_ID}

Requête

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/4982698b-e6b3-48c2-8dcf-040e20121fd2' \
  -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}'

Réponse

Une réponse réussie renvoie des informations sur votre flux de données, y compris votre URL de point d’entrée, marquée comme inletUrl. Consultez la page Setup Webhook pour obtenir la valeur requise.

{
    "items": [
        {
            "id": "d947e6a9-ea53-42c4-985c-c9379265491f",
            "createdAt": 1676875325841,
            "updatedAt": 1676875331938,
            "createdBy": "acme@AdobeID",
            "updatedBy": "acme@AdobeID",
            "createdClient": "{CREATED_CLIENT}",
            "updatedClient": "{UPDATED_CLIENT}",
            "sandboxId": "{SANDBOX_ID}",
            "sandboxName": "{SANDBOX_NAME}",
            "imsOrgId": "{ORG_ID}",
            "name": "Streaming Dataflow for Pendo",
            "description": "Streaming Dataflow for Pendo",
            "flowSpec": {
                "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
                "version": "1.0"
            },
            "state": "enabled",
            "version": "\"9801a366-0000-0200-0000-63f2f92c0000\"",
            "etag": "\"9801a366-0000-0200-0000-63f2f92c0000\"",
            "sourceConnectionIds": [
                "339d60a5-9ff6-4eba-8197-e8887eeb3c08"
            ],
            "targetConnectionIds": [
                "df7c660e-3484-463b-b01a-1835e9b04ac9"
            ],
            "inheritedAttributes": {
                "properties": {
                    "isSourceFlow": true
                },
                "sourceConnections": [
                    {
                        "id": "339d60a5-9ff6-4eba-8197-e8887eeb3c08",
                        "connectionSpec": {
                            "id": "6ff5654f-19d5-427d-bd3e-c0ebc802389a",
                            "version": "1.0"
                        }
                    }
                ],
                "targetConnections": [
                    {
                        "id": "df7c660e-3484-463b-b01a-1835e9b04ac9",
                        "connectionSpec": {
                            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
                            "version": "1.0"
                        }
                    }
                ]
            },
            "options": {
                "inletUrl": "https://dcs.adobedc.net/collection/e389c18dbc7f5de8b95df07b1b89d76ddd9b1e88d5423abc71b6ac9161491373"
            },
            "transformations": [
                {
                    "name": "Mapping",
                    "params": {
                        "mappingId": "bae11501021646e58cecc1182451af22",
                        "mappingVersion": 0
                    }
                }
            ],
            "runs": "/runs?property=flowId==4d90b316-1c9b-469d-935f-5a27d5deefdf",
            "providerRefId": "19d9fb14-9cb9-42a5-bb8b-23dc545e766a",
            "lastOperation": {
                "started": 0,
                "updated": 0,
                "operation": "enable"
            },
            "lastRunDetails": {
                "id": "d6972216-2332-41f6-8ed3-2ac82e6550b7",
                "state": "partialSuccess",
                "startedAtUTC": 1676862000000,
                "completedAtUTC": 1676867880000
            }
        }
    ]
}

Annexe appendix

La section suivante fournit des informations sur les étapes de surveillance, de mise à jour et de suppression de votre flux de données.

Surveiller votre flux de données monitor-dataflow

Une fois votre flux de données créé, vous pouvez surveiller les données ingérées pour afficher des informations sur les exécutions du flux, le statut d’achèvement et les erreurs. Pour obtenir des exemples complets d’API, consultez le guide sur la surveillance des flux de données de sources à l’aide de l’API.

Mettre à jour votre flux de données update-dataflow

Mettez à jour les détails de votre flux de données, tels que son nom et sa description, ainsi que son planning d’exécution et les ensembles de mappages associés, en envoyant une requête de PATCH au point de terminaison /flows de l’API Flow Service, tout en fournissant l’identifiant de votre flux de données. Lors de l’exécution d’une requête de PATCH, vous devez fournir l’unique etag de votre flux de données dans l’en-tête If-Match. Pour consulter des exemples complets d’API, consultez le guide sur la mise à jour des flux de données de sources à l’aide de l’API

Mettre à jour votre compte update-account

Mettez à jour le nom, la description et les informations d’identification de votre compte source en adressant une requête de PATCH à l’API Flow Service tout en fournissant votre identifiant de connexion de base en tant que paramètre de requête. Lors de l’exécution d’une requête de PATCH, vous devez fournir l’unique etag de votre compte source dans l’en-tête If-Match. Pour obtenir des exemples complets d’API, lisez le guide sur la mise à jour de votre compte source à l’aide de l’API.

Supprimer le flux de données delete-dataflow

Supprimez votre flux de données en adressant une requête de DELETE à l’API Flow Service tout en fournissant l’identifiant du flux de données que vous souhaitez supprimer dans le cadre du paramètre de requête . Pour obtenir des exemples complets d’API, lisez le guide sur la suppression de vos flux de données à l’aide de l’API.

Suppression de votre compte delete-account

Supprimez votre compte en adressant une requête de DELETE à l’API Flow Service tout en fournissant l’identifiant de connexion de base du compte que vous souhaitez supprimer. Pour obtenir des exemples complets d’API, lisez le guide sur la suppression de votre compte source à l’aide de l’API.

recommendation-more-help

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