Endpoint dei tipi di dati

I tipi di dati vengono utilizzati come campi di tipo riferimento nelle classi o nei mixin allo stesso modo dei campi letterali di base, con la differenza chiave che i tipi di dati possono definire più sottocampi. Anche se simili ai mixin in quanto consentono l'uso coerente di una struttura multi-campo, i tipi di dati sono più flessibili perché possono essere inclusi ovunque nella struttura dello schema, mentre i mixin possono essere aggiunti solo a livello principale. L'endpoint /datatypes nell'API Schema Registry consente di gestire i tipi di dati a livello di programmazione all'interno dell'applicazione dell'esperienza.

Introduzione

L'endpoint utilizzato in questa guida fa parte dell' Schema Registry API. Prima di continuare, consultare la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e informazioni importanti sulle intestazioni richieste necessarie per eseguire correttamente chiamate a qualsiasi API Experience Platform.

Recupera un elenco di tipi di dati

È possibile elencare tutti i tipi di dati sotto il contenitore global o tenant, effettuando una richiesta di GET rispettivamente a /global/datatypes o /tenant/datatypes.

NOTA

Quando si elencano le risorse, il Registro di sistema dello schema limita i set di risultati a 300 elementi. Per restituire risorse oltre questo limite, è necessario utilizzare i parametri di paging. È inoltre consigliabile utilizzare parametri di query aggiuntivi per filtrare i risultati e ridurre il numero di risorse restituite. Per ulteriori informazioni, vedere la sezione relativa ai parametri di query nel documento dell'appendice.

Formato API

GET /{CONTAINER_ID}/datatypes?{QUERY_PARAMS}
Parametro Descrizione
{CONTAINER_ID} Il contenitore da cui si desidera recuperare i tipi di dati: global per tipi di dati creati dal Adobe o tenant per i tipi di dati di proprietà dell'organizzazione.
{QUERY_PARAMS} Parametri di query facoltativi per filtrare i risultati per. Per un elenco dei parametri disponibili, vedere il documento dell'appendice.

Richiesta

La richiesta seguente recupera un elenco di tipi di dati dal contenitore tenant, utilizzando un parametro di query orderby per ordinare i tipi di dati in base all'attributo title.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes?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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Le seguenti intestazioni Accept sono disponibili per elencare i tipi di dati:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per elencare le risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce il tipo di dati JSON completo per ogni risorsa, con $ref originale e allOf inclusi. (Limite: 300)

Risposta

La richiesta precedente ha utilizzato l'intestazione application/vnd.adobe.xed-id+json Accept, pertanto la risposta include solo gli attributi title, $id, meta:altId e version per ciascun tipo di dati. Utilizzando l'altra intestazione Accept (application/vnd.adobe.xed+json) vengono restituiti tutti gli attributi di ciascun tipo di dati. Selezionate l'intestazione Accept appropriata a seconda delle informazioni richieste nella risposta.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
      "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
      "version": "1.0",
      "title": "Loyalty"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/4b0329b5573cbb7cb757db667d7fdf66",
      "meta:altId": "_{TENANT_ID}.datatypes.4b0329b5573cbb7cb757db667d7fdf66",
      "version": "1.0",
      "title": "Property Details"
    }
  ],
  "_page": {
    "orderby": "title",
    "next": null,
    "count": 2
  },
  "_links": {
    "next": null,
    "global_schemas": {
      "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/datatypes?orderby=title"
    }
  }
}

Cerca un tipo di dati

Puoi cercare un tipo di dati specifico includendo l'ID del tipo di dati nel percorso di una richiesta di GET.

Formato API

GET /{CONTAINER_ID}/datatypes/{DATA_TYPE_ID}
Parametro Descrizione
{CONTAINER_ID} Contenitore che contiene il tipo di dati da recuperare: global per un tipo di dati creato Adobe o tenant per un tipo di dati di proprietà dell'organizzazione.
{DATA_TYPE_ID} Il meta:altId o l'URL-encoded $id del tipo di dati che si desidera cercare.

Richiesta

La richiesta seguente recupera un tipo di dati in base al valore meta:altId fornito nel percorso.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44 \
  -H 'Accept: application/vnd.adobe.xed+json' \
  -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}'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Tutte le richieste di ricerca richiedono l'inclusione di un elemento version nell'intestazione Accept. Sono disponibili le seguenti intestazioni Accept:

Accept header Descrizione
application/vnd.adobe.xed+json; version={MAJOR_VERSION} Raw con $ref e allOf, ha titoli e descrizioni.
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref e allOf risolto, con titoli e descrizioni.
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} Raw con $ref e allOf, senza titoli o descrizioni.
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref e allOf risolto, nessun titolo o descrizione.
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $ref e allOf risolti, descrittori inclusi.

Risposta

Una risposta corretta restituisce i dettagli del tipo di dati. I campi restituiti dipendono dall'intestazione Accept inviata nella richiesta. Sperimentate con diverse intestazioni Accept per confrontare le risposte e determinare quale intestazione è più adatta all'uso da parte dell'utente.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
  "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Loyalty",
  "type": "object",
  "description": "Loyalty object containing loyalty-specific fields.",
  "definitions": {
    "customFields": {
      "properties": {
        "loyaltyId": {
          "title": "Loyalty ID",
          "description": "Unique loyalty program member ID. Should be in the format of an email address.",
          "type": "string",
          "meta:xdmType": "string"
        },
        "memberSince": {
          "title": "Member Since",
          "description": "Date person joined loyalty program.",
          "type": "string",
          "format": "date",
          "meta:xdmType": "date"
        },
        "points": {
          "title": "Points",
          "description": "Accumulated loyalty points",
          "type": "integer",
          "meta:xdmType": "int"
        },
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "The current loyalty program level to which the individual member belongs.",
          "type": "string",
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ],
          "meta:enum": {
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          },
          "meta:xdmType": "string"
        }
      },
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields"
    }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1557529442681,
    "repo:lastModifiedDate": 1557529442681,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "50b8008b588e911314f9685240dd4c23a247f37179a6d9ff6ba3877dc11ca504",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Creare un tipo di dati

È possibile definire un tipo di dati personalizzato sotto il contenitore tenant effettuando una richiesta di POST.

Formato API

POST /tenant/datatypes

Richiesta

La definizione di un tipo di dati non richiede i campi meta:extends o meta:intendedToExtend, né i campi devono essere nidificati per evitare conflitti.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Property Construction",
        "description":"Information related to the property construction",
        "type":"object",
        "properties": {
          "yearBuilt": {
            "type":"integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type":"string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          }
        } 
      }'

Risposta

Una risposta corretta restituisce lo stato HTTP 201 (Creato) e un payload contenente i dettagli del tipo di dati appena creato, inclusi $id, meta:altId e version. Questi tre valori sono di sola lettura e sono assegnati dal Schema Registry.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    }
  },
  "refs": [],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Se si esegue una richiesta di GET in elencare tutti i tipi di dati nel contenitore tenant ora è incluso il tipo di dati Dettagli proprietà, oppure è possibile eseguire una richiesta di ricerca (GET) utilizzando l'URI con codifica URL $id per visualizzare direttamente il nuovo tipo di dati.

Aggiornamento di un tipo di dati

È possibile sostituire un intero tipo di dati con un'operazione PUT, in sostanza riscrivendo la risorsa. Quando si aggiorna un tipo di dati tramite una richiesta di PUT, il corpo deve includere tutti i campi che sarebbero necessari durante la creazione di un nuovo tipo di dati in una richiesta di POST.

NOTA

Se si desidera aggiornare solo parte di un tipo di dati invece di sostituirlo completamente, consultare la sezione relativa all' aggiornamento di una parte di un tipo di dati.

Formato API

PUT /tenant/datatypes/{DATA_TYPE_ID}
Parametro Descrizione
{DATA_TYPE_ID} Il meta:altId o l'URL-encoded $id del tipo di dati che si desidera riscrivere.

Richiesta

La richiesta seguente riscrive un tipo di dati esistente, aggiungendo un nuovo campo floorSize.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type":"integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type":"string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "floorSize" {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        } 
      }'

Risposta

Una risposta corretta restituisce i dettagli del tipo di dati aggiornato.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "floorSize" {
      "type":  "integer",
      "title":  "Floor Size",
      "description":  "The floor size of the property, in square feet.",
      "meta:xdmType": "int"
    }
  },
  "refs": [],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Aggiornare una parte di un tipo di dati

È possibile aggiornare una parte di un tipo di dati utilizzando una richiesta di PATCH. Schema Registry supporta tutte le operazioni standard di patch JSON, incluse add, remove e replace. Per ulteriori informazioni sulla patch JSON, consultate la Guida di base delle API.

NOTA

Se si desidera sostituire un'intera risorsa con nuovi valori invece di aggiornare i singoli campi, consultare la sezione relativa alla sostituzione di un tipo di dati con un'operazione PUT.

Formato API

PATCH /tenant/data type/{DATA_TYPE_ID}
Parametro Descrizione
{DATA_TYPE_ID} URI con codifica URL $id o meta:altId del tipo di dati da aggiornare.

Richiesta

La richiesta di esempio seguente aggiorna la description di un tipo di dati esistente e aggiunge un nuovo campo floorSize.

Il corpo della richiesta assume la forma di una matrice, con ogni oggetto elencato che rappresenta una specifica modifica a un singolo campo. Ciascun oggetto include l'operazione da eseguire (op), il campo in cui deve essere eseguita l'operazione (path) e le informazioni da includere in tale operazione (value).

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -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 '[
        {
          "op": "replace",
          "path": "/description",
          "value": "Construction-related information for a company-operated property."
        },
        { 
          "op": "add",
          "path": "/properties/floorSize",
          "value": {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      ]'

Risposta

La risposta indica che entrambe le operazioni sono state eseguite correttamente. Il description è stato aggiornato e floorSize è stato aggiunto in definitions.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:altId": "_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:resourceType": "datatypes",
  "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": "{IMS_ORG}",
  "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}"
}

Eliminare un tipo di dati

Può essere talvolta necessario rimuovere un tipo di dati dal Registro di sistema dello schema. Questa operazione viene eseguita eseguendo una richiesta di DELETE con l'ID del tipo di dati fornito nel percorso.

Formato API

DELETE /tenant/datatypes/{DATA_TYPE_ID}
Parametro Descrizione
{DATA_TYPE_ID} URI con codifica URL $id o meta:altId del tipo di dati da eliminare.

Richiesta

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.d5cc04eb8d50190001287e4c869ebe67 \
  -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}'

Risposta

Una risposta corretta restituisce lo stato HTTP 204 (Nessun contenuto) e un corpo vuoto.

È possibile confermare l'eliminazione provando una richiesta di ricerca (GET) al tipo di dati. Sarà necessario includere un'intestazione Accept nella richiesta, ma dovrebbe ricevere uno stato HTTP 404 (Non trovato) perché il tipo di dati è stato rimosso dal Registro di sistema dello schema.

In questa pagina