Show Menu
SUJETS×

Envoi de données de parquet à partir d’un système d’enregistrement cloud tiers à l’aide de l’ Flow Service API

Flow Service est utilisée pour collecter et centraliser les données client provenant de diverses sources disparates au sein de l’Adobe Experience Platform. Le service fournit une interface utilisateur et une API RESTful à partir de laquelle toutes les sources prises en charge sont connectables.
Ce didacticiel utilise l’ Flow Service API pour vous guider à travers les étapes d’assimilation des données de parquet provenant d’un système d’enregistrement cloud tiers.

Prise en main

Ce guide exige une compréhension pratique des éléments suivants de l'Adobe Experience Platform :
  • Sources : Experience Platform permet l’assimilation de données à partir de diverses sources tout en vous permettant de structurer, d’étiqueter et d’améliorer les données entrantes à l’aide de Platform services.
  • Sandbox : Experience Platform fournit des sandbox virtuels qui partitionnent une Platform instance unique en environnements virtuels distincts pour aider à développer et développer des applications d'expérience numérique.
Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour pouvoir assimiler avec succès des données de parquet provenant d’un enregistrement de cloud tiers à l’aide de l’ Flow Service API.

Lecture des exemples d’appels d’API

Ce didacticiel fournit des exemples d’appels d’API pour montrer comment formater vos requêtes. Il s’agit notamment des chemins d’accès, des en-têtes requis et des charges de requête correctement formatées. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels d’API, voir la section sur la façon de lire des exemples d’appels d’API dans le guide de Experience Platform dépannage.

Rassembler les valeurs des en-têtes requis

Pour lancer des appels aux Platform API, vous devez d'abord suivre le didacticiel d' authentification. Le didacticiel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’ Experience Platform API, comme indiqué ci-dessous :
  • Autorisation : Porteur {ACCESS_TOKEN}
  • x-api-key : {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Toutes les ressources de Experience Platform, y compris celles appartenant à Flow Service, sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes aux Platform API nécessitent un en-tête spécifiant le nom du sandbox dans lequel l'opération aura lieu :
  • x-sandbox-name : {SANDBOX_NAME}
Toutes les requêtes qui contiennent une charge utile (POST, PUT, PATCH) nécessitent un en-tête de type de support supplémentaire :
  • Content-Type : application/json

Création d’une connexion

Pour importer des données de parquet à l’aide Platform d’API, vous devez posséder une connexion valide pour la source d’enregistrement de cloud tiers à laquelle vous accédez. Si vous n’avez pas encore de connexion pour l’enregistrement que vous souhaitez utiliser, vous pouvez en créer une à l’aide des didacticiels suivants :
Récupérez et stockez l’identifiant unique ( $id ) de la connexion, puis passez à l’étape suivante de ce didacticiel.

Création d’un schéma de cible

Pour que les données source soient utilisées dans Platform, un schéma de cible doit également être créé pour structurer les données source en fonction de vos besoins. Le schéma de cible est ensuite utilisé pour créer un Platform jeu de données dans lequel les données source sont contenues.
Si vous préférez utiliser l’interface utilisateur dans Experience Platform, le didacticiel de l’éditeur de Schémas fournit des instructions détaillées pour exécuter des actions similaires dans l’éditeur de Schéma.
Format d’API
POST /schemaregistry/tenant/schemas

Requête
L'exemple de demande suivant crée un schéma XDM qui étend la Individual Profile classe XDM.
curl -X POST \
    'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
    "type": "object",
    "title": "Sample Demo Profile XDM {{$guid}}",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-subscriptions"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        }
    ],
    "meta:containerId": "tenant",
    "meta:resourceType": "schemas",
    "meta:xdmType": "object",
    "meta:class": "https://ns.adobe.com/xdm/context/profile"
}'

Réponse
Une réponse réussie renvoie les détails du schéma nouvellement créé, y compris son identifiant unique ( $id ). Cet identifiant est requis à l’étape suivante pour créer une connexion source.
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
    "meta:altId": "_{TENANT_ID}.schemas.e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "Sample Demo Profile XDM 8d96a964-aad8-43c5-a73a-c8b9b1ccbfb1",
    "type": "object",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-subscriptions",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/context/profile-subscriptions",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/profile-work-details"
    ],
    "imsOrg": "{IMS_ORG}",
    "meta:extensible": false,
    "meta:abstract": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/context/profile-subscriptions",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/profile-work-details"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1584673864341,
        "repo:lastModifiedDate": 1584673864341,
        "xdm:createdClientId": "{CREATED_CLIENT_ID}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT_ID}",
        "xdm:createdUserId": "{CREATED_USER_ID}",
        "xdm:lastModifiedUserId": "{MODIFIED_USER_ID}",
        "eTag": "fa704f80da907c8f0f66f453ffcac3e52958687edbf55d71231dc5e1522193c4"
    },
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}"
}

Création d’une connexion source

Une fois un schéma XDM de cible créé, une connexion source peut désormais être créée à l’aide d’une requête POST envoyée à l’ Flow Service API. Une connexion source consiste en une connexion pour l'API, un format de données source et une référence au schéma XDM de cible récupéré à l'étape précédente.
Format d’API
POST /sourceConnections

Requête
curl -X POST \
    'http://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Source Connection S3 {{$guid}}",
        "baseConnectionId": "5831c52c-c261-4945-b1c5-2cc261d945b2",
        "connectionSpec": {
            "id": "ecadc60c-7455-4d87-84dc-2a0e293d997b",
            "version": 1
        },
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
                "id": "",
                "version": "application/vnd.adobe.xed-full+json;version=1.0"
            }
        },
        "params": {
            "path": "partners-demo/samples",
            "recursive": "true"
        }
    }'

Propriété
Description
baseConnectionId
Connexion de l’API qui représente votre enregistrement cloud.
data.schema.id
Le ( $id ) si le schéma xdm de cible a été récupéré à l’étape précédente.
params.path
Chemin d’accès du fichier source.
Réponse
Une réponse réussie renvoie l'identifiant unique ( id ) de la connexion source nouvellement créée. Stocker cette valeur comme elle est requise dans les étapes suivantes pour créer une connexion à une cible.
{
    "id": "73bc8911-505a-4e46-bc89-11505a6e466f",
    "etag": "\"c4004435-0000-0200-0000-5e7437d90000\""
}

Créer une connexion de base de jeux de données

Pour importer des données externes dans Platformun jeu de données, une connexion Experience Platform de base de données doit d'abord être acquise.
Pour créer une connexion de base de jeux de données, suivez les étapes décrites dans le didacticiel de connexion de base de jeux de données.
Continuez à suivre les étapes décrites dans le guide du développeur jusqu’à ce que vous ayez créé une connexion de base de jeux de données. Récupérez et stockez l’identifiant unique ( $id ), puis utilisez-le comme identifiant de connexion de base à l’étape suivante pour créer une connexion de cible.

Création d’un jeu de données de cible

Un jeu de données de cible peut être créé en exécutant une requête POST sur l’API catalog.yaml Catalog Service, en fournissant l’ID du schéma de cible dans la charge utile.
Format d’API
POST /catalog/dataSets

Requête
curl -X POST \
    'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Leads Dataset {{$guid}}",
        "schemaRef": {
            "id": ""https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80"",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "fileDescription": {
            "format": "parquet"
        }
    }'

Propriété
Description
schemaRef.id
ID de votre schéma XDM de cible.
Réponse
Une réponse réussie renvoie un tableau contenant l'ID du jeu de données nouvellement créé au format "@/datasets/{DATASET_ID}" . L’ID de jeu de données est une chaîne générée par le système en lecture seule qui est utilisée pour référencer le jeu de données dans les appels d’API. Stockez l’ID du jeu de données de cible tel qu’il est requis dans les étapes suivantes pour créer une connexion à une cible et un flux de données.
[
    "@/dataSets/5e7439b1ad55a618ad4c5102"
]

Création d’une connexion à une cible

Vous disposez maintenant des identifiants uniques pour une connexion de base de jeux de données, un schéma de cible et un jeu de données de cible. A l’aide de ces identifiants, vous pouvez créer une connexion de cible à l’aide de l’ Flow Service API pour spécifier le jeu de données qui contiendra les données source entrantes.
Format d’API
POST /targetConnections

Requête
curl -X POST \
    'http://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "baseConnectionId": "291257e3-c560-4e07-9257-e3c5606e07d1",
        "connectionSpec": {
            "id":"c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        },
        "name": "Target Connection {{$guid}}",
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": ""https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80"",
                "version": "application/vnd.adobe.xed-full+json;version=1.0"
            }
        },
        "params": {
            "dataSetId": "5e7439b1ad55a618ad4c5102"
        }
    }'

Propriété
Description
baseConnectionId
ID de la connexion de base de votre jeu de données.
data.schema.id
Le schéma $id XDM de la cible.
params.dataSetId
ID du jeu de données de cible.
connectionSpec.id
ID de spécification de connexion de votre enregistrement cloud.
Réponse
Une réponse réussie renvoie l'identifiant unique ( id ) de la nouvelle connexion à la cible. Stocker cette valeur comme elle est requise dans les étapes ultérieures.
{
    "id": "9b3abc95-f2e9-47c1-babc-95f2e927c1ec",
    "etag": "\"7501936b-0000-0200-0000-5e743bcc0000\""
}

Création d’un flux de données

La dernière étape vers l'assimilation de données sur le parquet à partir d'un enregistrement Cloud tiers consiste à créer un flux de données. A l’heure actuelle, les valeurs requises suivantes sont préparées :
Un flux de données est responsable de la planification et de la collecte des données d’une source. Vous pouvez créer un flux de données en exécutant une requête POST tout en fournissant les valeurs mentionnées précédemment dans la charge utile.
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: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Demo Parquet Ingestion Flow {{$guid}}",
        "flowSpec": {
            "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "73bc8911-505a-4e46-bc89-11505a6e466f"
        ],
        "targetConnectionIds": [
            "9b3abc95-f2e9-47c1-babc-95f2e927c1ec"
        ],
        "scheduleParams": {
            "startTime": {{$timestamp}},
            "frequency": "minute",
            "interval": 1000,
            "backfill": true
        }
    }'

Propriété
Description
sourceConnectionIds
ID de connexion source récupéré lors d’une étape précédente.
targetConnectionIds
ID de connexion à la cible récupéré lors d’une étape précédente.
Réponse
Une réponse réussie renvoie l'identifiant ( id ) du flux de données nouvellement créé.
{
    "id": "89ff50ef-b082-426e-bf50-efb082d26e78",
    "etag": "\"890070b8-0000-0200-0000-5e743c040000\""
}

Étapes suivantes

En suivant ce didacticiel, vous avez créé un connecteur source pour collecter les données relatives au parquet de votre système d’enregistrement de cloud tiers sur une base planifiée. Les données entrantes peuvent désormais être utilisées par Platform les services en aval tels que Real-time Customer Profile et Data Science Workspace. Pour plus d’informations, voir les documents suivants :