Configuration des schémas de partenaire

Experience Platform utilise des schémas pour décrire la structure des données de manière cohérente et réutilisable. Quand des données sont ingérées dans Platform, elles sont structurées en fonction d’un schéma XDM. Pour plus d’informations sur le modèle de composition de schémas, notamment sur les principes de conception et les bonnes pratiques, consultez les bases de la composition de schémas.

Pendant la création d’une destination avec Destination SDK, vous pouvez définir votre propre schéma de partenaire à utiliser par votre plateforme de destination. Cela permet aux utilisateurs de mapper les attributs de profil de Platform à des champs spécifiques reconnus par votre plateforme de destination, le tout dans l’interface utilisateur de Platform.

Pendant la configuration du schéma de partenaire pour la destination, vous pouvez affiner le mappage des champs pris en charge par votre plateforme de destination, par exemple :

  • Autoriser les utilisateurs à mapper un attribut XDM phoneNumber à un attribut phone pris en charge par votre plateforme de destination.
  • Créer des schémas de partenaire dynamique qu’Experience Platform peut appeler dynamiquement pour récupérer une liste de tous les attributs pris en charge dans la destination.
  • Définir les mappages de champs obligatoires par votre plateforme de destination.

Pour comprendre où ce composant entre dans une intégration créée avec Destination SDK, reportez-vous au diagramme de la documentation options de configuration ou consultez le guide sur la manière d’utiliser la Destination SDK pour configurer une destination basée sur des fichiers.

Vous pouvez configurer vos paramètres de schéma via le point d’entrée /authoring/destinations. Pour obtenir des exemples d’appels API détaillés dans lesquels vous pouvez configurer les composants affichés sur cette page, consultez les pages de référence de l’API suivantes.

Cet article décrit toutes les options de configuration de schéma prises en charge que vous pouvez utiliser pour la destination et montre ce que la clientèle verra dans l’interface utilisateur de Platform.

IMPORTANT
Tous les noms et toutes les valeurs de paramètre pris en charge par Destination SDK sont sensibles à la casse. Pour éviter les erreurs de respect de la casse, utilisez les noms et valeurs des paramètres exactement comme indiqué dans la documentation.

Types d’intégration pris en charge supported-integration-types

Pour en savoir plus sur les types d’intégration qui prennent en charge les fonctionnalités décrites sur cette page, consultez le tableau ci-dessous.

Type d’intégration
Fonctionnalité de prise en charge
Intégrations en temps réel (streaming)
Oui
Intégrations basées sur des fichiers (par lots)
Oui

Configuration de schéma prise en charge supported-schema-types

Destination SDK prend en charge plusieurs configurations de schéma :

  • Les schémas statiques sont définis depuis le tableau profileFields de la section schemaConfig. Dans un schéma statique, vous définissez chaque attribut cible qui doit s’afficher dans l’interface utilisateur d’Experience Platform dans le tableau profileFields. Si vous devez mettre à jour votre schéma, vous devez procéder à une mise à jour de la configuration de destination.
  • Les schémas dynamiques utilisent un type de serveur de destination supplémentaire, appelé serveur de schéma dynamique, afin de récupérer dynamiquement les attributs cibles pris en charge et générer des schémas en fonction de votre propre API. Les schémas dynamiques n’utilisent pas le tableau profileFields. Si vous devez mettre à jour votre schéma, vous n’êtes pas obligé de procéder à une mise à jour de la configuration de destination. Au lieu de cela, le serveur de schéma dynamique récupère le schéma mis à jour de votre API.
  • Dans la configuration du schéma, vous avez la possibilité d’ajouter des mappages obligatoires (ou prédéfinis). Il s’agit de mappages que les utilisateurs peuvent afficher dans l’interface utilisateur de Platform, mais qu’ils ne peuvent pas modifier pendant la configuration d’une connexion à la destination. Vous pouvez, par exemple, appliquer le champ de l’adresse e-mail pour qu’il soit toujours envoyé à la destination.

schemaConfig utilise plusieurs paramètres de configuration, en fonction du type de schéma dont vous avez besoin, comme indiqué dans les sections ci-dessous.

Création d’un schéma statique attributes-schema

Pour créer un schéma statique avec des attributs de profil, définissez les attributs de la cible dans profileFields comme illustré ci-dessous.

"schemaConfig":{
      "profileFields":[
           {
              "name":"phoneNo",
              "title":"phoneNo",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the mobilePhone.number value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"firstName",
              "title":"firstName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.firstName value in Experience Platform could be firstName on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"lastName",
              "title":"lastName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.lastName value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           }
        ],
      "useCustomerSchemaForAttributeMapping":false,
      "profileRequired":true,
      "segmentRequired":true,
      "identityRequired":true,
      "segmentNamespaceAllowList": ["someNamespace"],
      "segmentNamespaceDenyList": ["someOtherNamespace"]

}
Paramètre
Type
Obligatoire / Facultatif
Description
profileFields
Tableau
Facultatif
Définit le tableau des attributs de cible acceptés par votre plateforme de destination vers lequel la clientèle peut mapper ses attributs de profil. Pendant l’utilisation d’un tableau profileFields, vous pouvez entièrement omettre le paramètre useCustomerSchemaForAttributeMapping.
useCustomerSchemaForAttributeMapping
Booléen
Facultatif

Active ou désactive le mappage des attributs du schéma client aux attributs que vous définissez dans le tableau profileFields.

  • Si le paramètre est défini sur true, les utilisateurs ne voient que la colonne source dans le champ de mappage. profileFields ne sont pas applicables dans ce cas.
  • Si le paramètre est défini sur false, les utilisateurs peuvent mapper les attributs sources de leur schéma aux attributs que vous avez définis dans le tableau profileFields.

La valeur par défaut est false.

profileRequired
Booléen
Facultatif
Utilisez true si les utilisateurs doivent être en mesure de mapper les attributs de profil d’Experience Platform aux attributs personnalisés du côté de votre plateforme de destination.
segmentRequired
Booléen
Obligatoire
Ce paramètre est demandé par Destination SDK et doit toujours être défini sur true.
identityRequired
Booléen
Obligatoire
Définissez-le sur true si les utilisateurs doivent être en mesure de mapper les types d’identité d’Experience Platform aux attributs que vous avez définis dans le tableau profileFields.
segmentNamespaceAllowList
Tableau
Facultatif
Définit des espaces de noms d’audience spécifiques à partir desquels les personnes peuvent mapper des audiences à la destination. Utilisez ce paramètre pour empêcher les personnes utilisant Platform d’exporter des audiences à partir des espaces de noms d’audience que vous définissez dans le tableau. Ce paramètre ne peut pas être utilisé avec segmentNamespaceDenyList.

Exemple : "segmentNamespaceAllowList": ["AudienceManager"] permet de mapper uniquement les audiences depuis l’espace de noms AudienceManager sur cette destination.

Pour autoriser l’export de n’importe quelle audience vers votre destination, vous pouvez ignorer ce paramètre.

Si segmentNamespaceAllowList et segmentNamespaceDenyList ne sont pas présents dans votre configuration, les personnes pourront uniquement exporter des audiences provenant de Segmentation Service.
segmentNamespaceDenyList
Tableau
Facultatif
Limite la capacité de mapper des audiences sur la destination, à partir des espaces de noms d’audience définis dans le tableau. Ne peut pas être utilisé avec segmentNamespaceAllowed.

Exemple : "segmentNamespaceDenyList": ["AudienceManager"] empêche de mapper les audiences depuis l’espace de noms AudienceManager sur cette destination.

Pour autoriser l’export de n’importe quelle audience sur votre destination, vous pouvez ignorer ce paramètre.

Si segmentNamespaceAllowed et segmentNamespaceDenyList ne sont pas présents dans votre configuration, les personnes pourront uniquement exporter des audiences provenant de Segmentation Service.

Pour autoriser l’export de toutes les audiences, quelle que soit leur origine, définissez "segmentNamespaceDenyList":[].

L’expérience de l’interface utilisateur qui en résulte est affichée dans les images ci-dessous.

Quand les utilisateurs sélectionnent le mapping de ciblage, ils peuvent voir les champs définis dans le tableau profileFields.

Image de l’interface utilisateur affichant l’écran des attributs de la cible.

Après avoir sélectionné les attributs, les utilisateurs peuvent les voir dans la colonne du champ cible.

Image de l’interface utilisateur présentant un schéma cible statique avec des attributs

Création d’un schéma dynamique dynamic-schema-configuration

Destination SDK prend en charge la création de schémas de partenaire dynamiques. Contrairement à un schéma statique, un schéma dynamique n’utilise pas de tableau profileFields, mais un serveur de schéma dynamique qui se connecte à votre propre API à partir de laquelle il récupère la configuration du schéma.

IMPORTANT
Avant de créer un schéma dynamique, vous devez procéder à la création d’un serveur de schéma dynamique.

Dans une configuration de schéma dynamique, le tableau profileFields est remplacé par dynamicSchemaConfig, comme illustré ci-dessous.

"schemaConfig":{
   "dynamicSchemaConfig":{
      "dynamicEnum": {
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"DYNAMIC_SCHEMA_SERVER_ID",
         "value": "Schema Name",
         "responseFormat": "SCHEMA"
      }
   },
   "profileRequired":true,
   "segmentRequired":true,
   "identityRequired":true
}
Paramètre
Type
Obligatoire / Facultatif
Description
dynamicEnum.authenticationRule
Chaîne
Obligatoire

Indique comment la clientèle Platform se connecte à votre destination. Les valeurs acceptées sont les suivantes : CUSTOMER_AUTHENTICATION, PLATFORM_AUTHENTICATION, NONE.

  • Utilisez CUSTOMER_AUTHENTICATION si la clientèle Platform se connecte à votre système via l’une des méthodes d’authentification décrites ici.
  • Utilisez PLATFORM_AUTHENTICATION s’il existe un système d’authentification global entre Adobe et votre destination et que la clientèle Platform n’a pas besoin de fournir d’informations d’authentification pour se connecter à votre destination. Dans ce cas, vous devez procéder à la création d’un objet d’informations d’identification à l’aide de l’API d’informations d’identification.
  • Utilisez NONE si aucune authentification n’est requise pour envoyer des données à votre plateforme de destination.
dynamicEnum.destinationServerId
Chaîne
Obligatoire
instanceId de votre serveur de schéma dynamique. Ce serveur de destination inclut le point d’entrée de l’API qu’Experience Platform appellera pour récupérer le schéma dynamique.
dynamicEnum.value
Chaîne
Obligatoire
Nom du schéma dynamique, tel que défini dans la configuration du serveur de schéma dynamique.
dynamicEnum.responseFormat
Chaîne
Obligatoire
Toujours définie sur SCHEMA pendant la définition d’un schéma dynamique.
profileRequired
Booléen
Facultatif
Utilisez true si les utilisateurs doivent être en mesure de mapper les attributs de profil d’Experience Platform aux attributs personnalisés du côté de votre plateforme de destination.
segmentRequired
Booléen
Obligatoire
Ce paramètre est demandé par Destination SDK et doit toujours être défini sur true.
identityRequired
Booléen
Obligatoire
Définissez-le sur true si les utilisateurs doivent être en mesure de mapper les types d’identité d’Experience Platform aux attributs que vous avez définis dans le tableau profileFields.

Mappages obligatoires required-mappings

Dans la configuration du schéma, en plus de votre schéma statique ou dynamique, vous avez la possibilité d’ajouter des mappages obligatoires (ou prédéfinis). Il s’agit de mappages que les utilisateurs peuvent afficher dans l’interface utilisateur de Platform, mais qu’ils ne peuvent pas modifier pendant la configuration d’une connexion à la destination.

Vous pouvez, par exemple, appliquer le champ de l’adresse e-mail pour qu’il soit toujours envoyé à la destination.

NOTE
Les combinaisons suivantes de mappages obligatoires sont actuellement prises en charge :
  • Vous pouvez configurer un champ source et un champ de destination obligatoires. Dans ce cas, les utilisateurs ne peuvent pas modifier ni sélectionner l’un des deux champs et peuvent uniquement afficher la sélection.
  • Vous ne pouvez configurer qu’un champ de destination obligatoire. Dans ce cas, les utilisateurs seront autorisés à sélectionner un champ source à mapper à la destination.
La configuration d’un champ source obligatoire n’est pas prise en charge pour l’instant.

Vous trouverez ci-dessous deux exemples de configuration de schéma avec les mappages obligatoires et ce à quoi ils ressemblent dans l’étape de mappage du flux de travail d’activation des données vers les destinations des lots.

Mappages source et de destination obligatoire

L’exemple ci-dessous montre les mappages source et de destination obligatoires. Quand les champs source et de destination sont spécifiés comme des mappages obligatoires, les utilisateurs ne peuvent pas sélectionner ni modifier l’un des deux champs et peuvent uniquement afficher la sélection prédéfinie.

code language-json
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "sourceType": "text/x.schema-path",
        "source": "personalEmail.address",
        "destination": "personalEmail.address"
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
Paramètre Type Obligatoire / Facultatif Description
requiredMappingsOnly Booléen Facultatif Quand cette valeur est définie sur « true », les utilisateurs ne peuvent pas mapper d’autres attributs et identités dans le flux d’activation, à l’exception des mappages obligatoires que vous définissez dans le tableau requiredMappings.
requiredMappings.sourceType Chaîne Obligatoire

Indique le type du champ source. Valeurs prises en charge :

  • text/x.schema-path : utilisez cette valeur quand le champ source est l’attribut de profil d’un schéma XDM.
  • text/x.aep-xl : utilisez cette valeur quand votre champ source est défini par une expression régulière. Exemple : iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\")
  • text/plain : utilisez cette valeur quand votre champ source est défini par un modèle de macro. Actuellement, le seul modèle de macro pris en charge est metadata.segment.alias.
requiredMappings.source Chaîne Obligatoire

Indique la valeur du champ source. Types de valeur pris en charge :

  • Attributs de profil XDM. Exemple : personalEmail.address. Quand votre attribut source est un attribut de profil XDM, définissez le paramètre sourceType sur text/x.schema-path.
  • Expressions régulières. Exemple : iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\"). Quand votre attribut source est une expression régulière, définissez le paramètre sourceType sur text/x.aep-xl.
  • Modèles de macro. Exemple : metadata.segment.alias. Quand votre attribut source est un modèle de macro, définissez le paramètre sourceType sur text/plain. Actuellement, le seul modèle de macro pris en charge est metadata.segment.alias.
requiredMappings.destination Chaîne Obligatoire Indique la valeur du champ cible. Quand les champs source et de destination sont spécifiés comme des mappages obligatoires les utilisateurs ne peuvent pas sélectionner ni modifier l’un des deux champs et peuvent uniquement afficher la sélection.

Ainsi, les sections Champ source et Champ cible de l’interface utilisateur de Platform sont grisés.

Image des mappages obligatoires dans le flux d’activation de l’interface utilisateur.

Mappage de destination obligatoire

L’exemple ci-dessous montre un mappage de destination obligatoire. Si seul le champ de destination est spécifié, les utilisateurs peuvent sélectionner le champ source à mapper.

code language-json
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "destination": "identityMap.ExamplePartner_ID",
        "mandatoryRequired": true,
        "primaryKeyRequired": true
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
Paramètre Type Obligatoire / Facultatif Description
requiredMappingsOnly Booléen Facultatif Quand cette valeur est définie sur « true », les utilisateurs ne peuvent pas mapper d’autres attributs et identités dans le flux d’activation, à l’exception des mappages obligatoires que vous définissez dans le tableau requiredMappings.
requiredMappings.destination Chaîne Obligatoire Indique la valeur du champ cible. Quand seul le champ de destination est spécifié, les utilisateurs peuvent sélectionner un champ source à mapper vers la destination.
mandatoryRequired Booléen Facultatif Indique si le mappage doit être marqué comme un attribut obligatoire.
primaryKeyRequired Booléen Facultatif Indique si le mappage doit être marqué comme une clé de déduplication.

Ainsi, la section Champ cible dans l’interface utilisateur de Platform est grisée, tandis que la section Champ source est active et les utilisateurs peuvent interagir avec celle-ci. Les options clé obligatoire et clé de déduplication sont actives et les utilisateurs ne peuvent pas les modifier.

Image des mappages obligatoires dans le flux d’activation de l’interface utilisateur.

Configuration de la prise en charge des audiences externes external-audiences

Pour configurer votre destination afin de prendre en charge l’activation des audiences générées de l’extérieur, insérez le fragment de code ci-dessous dans la section schemaConfig .

"schemaConfig": {
  "segmentNamespaceDenyList": [],
  ...
}

Pour en savoir plus sur la fonctionnalité segmentNamespaceDenyList, voir les descriptions des propriétés dans la table ci-dessus sur cette page.

Étapes suivantes next-steps

Vous êtes arrivé au bout de cet article. À présent, vous devriez mieux comprendre quels types de schémas sont pris en charge par Destination SDK et comment le configurer.

Pour en savoir plus sur les autres composants de destination, consultez les articles suivants :

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6