Point d’entrée des groupes de champs de schéma
Les groupes de champs de schéma sont des composants réutilisables qui définissent un ou plusieurs champs représentant un concept particulier, comme une personne, une adresse postale ou un environnement de navigateur web. Les groupes de champs sont destinés à être inclus dans le cadre d’un schéma qui implémente une classe compatible, en fonction du comportement des données qu’ils représentent (enregistrement ou série temporelle). Le point d’entrée /fieldgroups de l’API Schema Registry vous permet de gérer par programmation les groupes de champs de votre application d’expérience.
Prise en main
Le point d’entrée utilisé dans ce guide fait partie de l’API 🔗. Schema Registry Avant de continuer, consultez le guide de prise en main pour obtenir des liens vers la documentation associée, un guide de lecture des exemples d’appels API dans ce document et des informations importantes sur les en-têtes requis pour réussir des appels vers n’importe quelle API d’Experience Platform.
Récupération d’une liste de groupes de champs list
Vous pouvez répertorier tous les groupes de champs sous le conteneur global ou tenant en effectuant une requête GET à /global/fieldgroups ou /tenant/fieldgroups, respectivement.
Format d’API
GET /{CONTAINER_ID}/fieldgroups?{QUERY_PARAMS}
{CONTAINER_ID}global pour les groupes de champs créés par Adobe ou tenant pour les groupes de champs appartenant à votre organisation.{QUERY_PARAMS}Requête
La requête suivante récupère une liste de groupes de champs du conteneur de tenant à l’aide d’un paramètre de requête orderby pour trier les groupes de champs en fonction de leur attribut title.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups?orderby=title \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-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}'
Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Les en-têtes Accept suivants sont disponibles pour répertorier les groupes de champs :
Acceptapplication/vnd.adobe.xed-id+jsonapplication/vnd.adobe.xed+json$ref et allOf d’origine inclus. (Limite : 300)Réponse
La requête ci-dessus a utilisé l’en-tête application/vnd.adobe.xed-id+json Accept. Par conséquent, la réponse inclut uniquement les attributs title, $id, meta:altId et version pour chaque groupe de champs. L’utilisation de l’autre en-tête de Accept (application/vnd.adobe.xed+json) renvoie tous les attributs de chaque groupe de champs. Sélectionnez l’en-tête de Accept approprié en fonction des informations dont vous avez besoin dans votre réponse.
{
"results": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/6ece98e9842907c78c651f5b249d9f09",
"meta:altId": "_{TENANT_ID}.mixins.6ece98e9842907c78c651f5b249d9f09",
"version": "1.0",
"title": "CRM Data"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/6386ee478a30914964c6e676ad55603c",
"meta:altId": "_{TENANT_ID}.mixins.6386ee478a30914964c6e676ad55603c",
"version": "1.9",
"title": "Loyalty Member Details"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/67626b2830db3d3ea6c8f9d007aa5797",
"meta:altId": "_{TENANT_ID}.mixins.67626b2830db3d3ea6c8f9d007aa5797",
"version": "1.0",
"title": "Restaurant"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/2583b25b613fec704da6ef70cf527688",
"meta:altId": "_{TENANT_ID}.mixins.2583b25b613fec704da6ef70cf527688",
"version": "1.1",
"title": "Retail Customer Preferences"
},
],
"_page": {
"orderby": "title",
"next": null,
"count": 3
},
"_links": {
"next": null,
"global_schemas": {
"href": "https://platform.adobe.io/data/foundation/schemaregistry/global/fieldgroups"
}
}
}
Recherche d’un groupe de champs lookup
Vous pouvez rechercher un groupe de champs spécifique en incluant l’identifiant du groupe de champs dans le chemin d’accès d’une requête GET.
Format d’API
GET /{CONTAINER_ID}/fieldgroups/{FIELD_GROUP_ID}
{CONTAINER_ID}global pour un groupe de champs créé par Adobe ou tenant pour un groupe de champs appartenant à votre organisation.{FIELD_GROUP_ID}$id meta:altId ou encodée en URL du groupe de champs que vous souhaitez rechercher.Requête
La requête suivante récupère un groupe de champs en fonction de sa valeur meta:altId fournie dans le chemin d’accès .
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups/_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
-H 'Accept: application/vnd.adobe.xed+json' \
-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}'
Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Toutes les requêtes de recherche nécessitent qu’un version soit inclus dans l’en-tête Accept. Les en-têtes Accept suivants sont disponibles :
Acceptapplication/vnd.adobe.xed+json; version={MAJOR_VERSION}$ref et allOf, contient des titres et des descriptions.application/vnd.adobe.xed-full+json; version={MAJOR_VERSION}$ref et allOf résolus, contient des titres et des descriptions.application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION}$ref et allOf, ne contient aucun titre ni aucune description.application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION}$ref et allOf résolus, ne contient aucun titre ni aucune description.application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION}$ref et allOf résolus, contient des descripteurs.Réponse
Une réponse réussie renvoie les détails du groupe de champs. Les champs renvoyés dépendent de l’en-tête Accept envoyé dans la requête. Testez différents en-têtes Accept pour comparer les réponses et déterminer l’en-tête le mieux adapté à votre cas d’utilisation.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:altId": "_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:resourceType": "mixins",
"version": "1.2",
"title": "Favorite Hotel",
"type": "object",
"description": "",
"definitions": {
"customFields": {
"type": "object",
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"favoriteHotel": {
"title": "Favorite Hotel",
"description": "Reference field for hotel schema.",
"type": "string",
"isRequired": false,
"meta:xdmType": "string"
}
},
"meta:xdmType": "object"
}
},
"meta:xdmType": "object"
}
},
"allOf": [
{
"$ref": "#/definitions/customFields",
"type": "object",
"meta:xdmType": "object"
}
],
"imsOrg": "{ORG_ID}",
"meta:extensible": true,
"meta:abstract": true,
"meta:intendedToExtend": [
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1594941263588,
"repo:lastModifiedDate": 1594941538433,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:lastModifiedClientId": "{CLIENT_ID}",
"xdm:createdUserId": "{USER_ID}",
"xdm:lastModifiedUserId": "{USER_ID}",
"eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
"meta:globalLibVersion": "1.15.4"
},
"meta:containerId": "tenant",
"meta:tenantNamespace": "_{TENANT_ID}"
}
Créer un groupe de champs create
Vous pouvez définir un groupe de champs personnalisé sous le conteneur tenant en effectuant une requête POST.
Format d’API
POST /tenant/fieldgroups
Requête
Lors de la définition d’un nouveau groupe de champs, il doit inclure un attribut meta:intendedToExtend répertoriant les $id des classes avec lesquelles le groupe de champs est compatible. Dans cet exemple, le groupe de champs est compatible avec une classe Property définie précédemment. Les champs personnalisés doivent être imbriqués sous _{TENANT_ID} (comme illustré dans l’exemple) pour éviter tout conflit avec des champs similaires fournis par des classes et d’autres groupes de champs.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups \
-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 '{
"title":"Property Details",
"description":"Detailed information related to the properties owned and operated by the company.",
"type":"object",
"meta:intendedToExtend":["https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"],
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type":"object",
"properties": {
"propertyName": {
"type": "string",
"title": "Property Name",
"description": "Name of the property"
},
"propertyCity": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"description": "Primary phone number for the property.",
"type": "string"
},
"propertyType": {
"type": "string",
"title": "Property Type",
"description": "Type and primary use of property.",
"enum": [
"retail",
"yoga",
"fitness"
],
"meta:enum": {
"retail": "Retail Store",
"yoga": "Yoga Studio",
"fitness": "Fitness Center"
}
},
"propertyConstruction": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
}
}
}
}
}
},
"allOf": [
{
"$ref": "#/definitions/property"
}
]
}'
Réponse
Une réponse réussie renvoie un état HTTP 201 (Created) et une payload contenant les détails du groupe de champs nouvellement créé, y compris les $id, meta:altId et version. Ces valeurs sont en lecture seule et sont attribuées par le Schema Registry.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:altId": "_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:resourceType": "mixins",
"version": "1.2",
"title": "Property Details",
"type": "object",
"description": "Detailed information related to the properties owned and operated by the company.",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type":"object",
"properties": {
"propertyName": {
"type": "string",
"title": "Property Name",
"description": "Name of the property"
},
"propertyCity": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"description": "Primary phone number for the property.",
"type": "string"
},
"propertyType": {
"type": "string",
"title": "Property Type",
"description": "Type and primary use of property.",
"enum": [
"retail",
"yoga",
"fitness"
],
"meta:enum": {
"retail": "Retail Store",
"yoga": "Yoga Studio",
"fitness": "Fitness Center"
}
},
"propertyConstruction": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
}
}
}
}
}
},
"allOf": [
{
"$ref": "#/definitions/customFields",
"type": "object",
"meta:xdmType": "object"
}
],
"imsOrg": "{ORG_ID}",
"meta:extensible": true,
"meta:abstract": true,
"meta:intendedToExtend": [
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1594941263588,
"repo:lastModifiedDate": 1594941538433,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:lastModifiedClientId": "{CLIENT_ID}",
"xdm:createdUserId": "{USER_ID}",
"xdm:lastModifiedUserId": "{USER_ID}",
"eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
"meta:globalLibVersion": "1.15.4"
},
"meta:containerId": "tenant",
"meta:tenantNamespace": "_{TENANT_ID}"
}
L’exécution d’une requête GET pour répertorier tous les groupes de champs dans le conteneur du client inclut désormais le groupe de champs Détails de la propriété. Vous pouvez également effectuer une requête de recherche (GET) à l’aide de l’URI de $id codé par URL pour afficher directement le nouveau groupe de champs.
Mettre à jour un groupe de champs put
Vous pouvez remplacer un groupe de champs entier par une opération PUT, ce qui revient essentiellement à réécrire la ressource. Lors de la mise à jour d’un groupe de champs par le biais d’une requête PUT, le corps doit inclure tous les champs qui seraient requis lors de la création d’un nouveau groupe de champs dans une requête POST.
Format d’API
PUT /tenant/fieldgroups/{FIELD_GROUP_ID}
{FIELD_GROUP_ID}$id codée en meta:altId ou en URL du groupe de champs que vous souhaitez réécrire.Requête
La requête suivante réécrit un groupe de champs existant, en ajoutant un nouveau champ propertyCountry.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups/_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
-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 '{
"title": "Property Details",
"description": "Detailed information related to the properties owned and operated by the company.",
"type": "object",
"meta:intendedToExtend": ["https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"],
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type":"object",
"properties": {
"propertyName": {
"type": "string",
"title": "Property Name",
"description": "Name of the property"
},
"propertyCity": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
},
"propertyCountry": {
"title": "Property Country",
"description": "Country where the property is located.",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"description": "Primary phone number for the property.",
"type": "string"
},
"propertyType": {
"type": "string",
"title": "Property Type",
"description": "Type and primary use of property.",
"enum": [
"retail",
"yoga",
"fitness"
],
"meta:enum": {
"retail": "Retail Store",
"yoga": "Yoga Studio",
"fitness": "Fitness Center"
}
},
"propertyConstruction": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
}
}
}
}
}
},
"allOf": [
{
"$ref": "#/definitions/property"
}
]
}'
Réponse
Une réponse réussie renvoie les détails du groupe de champs mis à jour.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:altId": "_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:resourceType": "mixins",
"version": "1.2",
"title": "Property Details",
"type": "object",
"description": "Detailed information related to the properties owned and operated by the company.",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type":"object",
"properties": {
"propertyName": {
"type": "string",
"title": "Property Name",
"description": "Name of the property"
},
"propertyCity": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
},
"propertyCountry": {
"title": "Property Country",
"description": "Country where the property is located.",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"description": "Primary phone number for the property.",
"type": "string"
},
"propertyType": {
"type": "string",
"title": "Property Type",
"description": "Type and primary use of property.",
"enum": [
"retail",
"yoga",
"fitness"
],
"meta:enum": {
"retail": "Retail Store",
"yoga": "Yoga Studio",
"fitness": "Fitness Center"
}
},
"propertyConstruction": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
}
}
}
}
}
},
"allOf": [
{
"$ref": "#/definitions/customFields",
"type": "object",
"meta:xdmType": "object"
}
],
"imsOrg": "{ORG_ID}",
"meta:extensible": true,
"meta:abstract": true,
"meta:intendedToExtend": [
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1594941263588,
"repo:lastModifiedDate": 1594941538433,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:lastModifiedClientId": "{CLIENT_ID}",
"xdm:createdUserId": "{USER_ID}",
"xdm:lastModifiedUserId": "{USER_ID}",
"eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
"meta:globalLibVersion": "1.15.4"
},
"meta:containerId": "tenant",
"meta:tenantNamespace": "_{TENANT_ID}"
}
Mettre à jour une partie d’un groupe de champs patch
Vous pouvez mettre à jour une partie d’un groupe de champs à l’aide d’une requête PATCH. Le Schema Registry prend en charge toutes les opérations standard JSON Patch, notamment add, remove et replace. Pour plus d’informations sur le correctif JSON, voir Guide de base des API.
Format d’API
PATCH /tenant/fieldgroups/{FIELD_GROUP_ID}
{FIELD_GROUP_ID}$id codé URL ou le meta:altId du groupe de champs que vous souhaitez mettre à jour.Requête
L’exemple de requête ci-dessous met à jour la description d’un groupe de champs existant et ajoute un nouveau champ de propertyCity.
Le corps de la requête se présente sous la forme d’un tableau, où chaque objet répertorié représente une modification spécifique apportée à un champ individuel. Chaque objet inclut l’opération à effectuer (op), le champ sur lequel l’opération doit être effectuée (path) et les informations à inclure dans cette opération (value).
curl -X PATCH \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups/_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
-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 '[
{
"op": "replace",
"path": "/description",
"value": "Details relating to a property operated by the company."
},
{
"op": "add",
"path": "/definitions/property/properties/_{TENANT_ID}/properties/propertyCity",
"value": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
}
}
]'
Réponse
La réponse montre que les deux opérations ont été réalisées avec succès. Le description a été mis à jour et propertyCountry a été ajouté sous definitions.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/mixins/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:altId": "_{TENANT_ID}.mixins.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
"meta:resourceType": "mixins",
"version": "1.2",
"title": "Property Details",
"type": "object",
"description": "Details relating to a property operated by the company.",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type":"object",
"properties": {
"propertyName": {
"type": "string",
"title": "Property Name",
"description": "Name of the property"
},
"propertyCity": {
"title": "Property City",
"description": "City where the property is located.",
"type": "string"
},
"propertyCountry": {
"title": "Property Country",
"description": "Country where the property is located.",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"description": "Primary phone number for the property.",
"type": "string"
},
"propertyType": {
"type": "string",
"title": "Property Type",
"description": "Type and primary use of property.",
"enum": [
"retail",
"yoga",
"fitness"
],
"meta:enum": {
"retail": "Retail Store",
"yoga": "Yoga Studio",
"fitness": "Fitness Center"
}
},
"propertyConstruction": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
}
}
}
}
}
},
"allOf": [
{
"$ref": "#/definitions/customFields",
"type": "object",
"meta:xdmType": "object"
}
],
"imsOrg": "{ORG_ID}",
"meta:extensible": true,
"meta:abstract": true,
"meta:intendedToExtend": [
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1594941263588,
"repo:lastModifiedDate": 1594941538433,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:lastModifiedClientId": "{CLIENT_ID}",
"xdm:createdUserId": "{USER_ID}",
"xdm:lastModifiedUserId": "{USER_ID}",
"eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
"meta:globalLibVersion": "1.15.4"
},
"meta:containerId": "tenant",
"meta:tenantNamespace": "_{TENANT_ID}"
}
Suppression d’un groupe de champs delete
Il peut parfois être nécessaire de supprimer un groupe de champs du registre des schémas. Pour ce faire, il suffit d’effectuer une requête DELETE avec l’identifiant de groupe de champs fourni dans le chemin d’accès .
Format d’API
DELETE /tenant/fieldgroups/{FIELD_GROUP_ID}
{FIELD_GROUP_ID}$id encodé URL ou le meta:altId du groupe de champs que vous souhaitez supprimer.Requête
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups/_{TENANT_ID}.mixins.d5cc04eb8d50190001287e4c869ebe67 \
-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 un statut HTTP 204 (Pas de contenu) et un corps vide.
Vous pouvez confirmer la suppression en tentant d’adresser une requête de recherche (GET) au groupe de champs . Vous devez inclure un en-tête Accept dans la requête, mais vous devriez recevoir le statut HTTP 404 (Not Found), car le groupe de champs a été supprimé du registre des schémas.