Substituir um campo XDM na API

No Experience Data Model (XDM), é possível descontinuar um campo em um esquema ou recurso personalizado usando o API do registro de esquema. A desativação de um campo faz com que ele fique oculto nas interfaces downstream, como o Perfis espaço de trabalho e Customer Journey Analytics, mas caso contrário, é uma alteração ininterrupta e não afeta negativamente os fluxos de dados existentes.

Este documento aborda como descontinuar campos para diferentes recursos XDM. Para obter etapas sobre como descontinuar um campo XDM usando o Editor de esquemas na interface do usuário do Experience Platform, consulte o tutorial em substituição de um campo XDM na interface do.

Introdução

Este tutorial requer a realização de chamadas para a API do registro de esquema. Revise o guia do desenvolvedor para obter informações importantes que você precisa saber para fazer essas chamadas de API. Isso inclui o {TENANT_ID}, o conceito de "contêineres" e os cabeçalhos necessários para fazer solicitações (com especial atenção para os Accept e seus valores possíveis).

Substituir um campo personalizado

Para descontinuar um campo em uma classe personalizada, grupo de campos ou tipo de dados, atualize o recurso personalizado por meio de uma solicitação PUT ou PATCH e adicione o atributo meta:status: deprecated ao campo em questão.

A chamada de API de exemplo abaixo substitui um campo em um tipo de dados personalizado.

Formato da API

PATCH /tenant/datatypes/{DATA_TYPE_ID}

Solicitação

A solicitação a seguir substitui a expansionArea para um tipo de dados que descreve uma propriedade imobiliária.

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": "add",
          "path": "/properties/expansionArea/meta:status",
          "value": "deprecated"
        }
      ]'

Resposta

Uma resposta bem-sucedida retorna os detalhes de atualização do recurso personalizado, com o campo obsoleto contendo um meta:status valor de deprecated. O exemplo de resposta a seguir foi truncado por questões de espaço.

{
  "$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 real-estate property operated by the company.",
  "definitions": {
    "property": {
      "properties": {
        "_{TENANT_ID}": {
        "type":"object",
        "properties": {
            "expansionArea": {
              "title": "Expansion Area",
              "description": "Square footage for renovated additions to the property.",
              "type": "integer",
              "meta:status": "deprecated",
            },
            "propertyName": {
              "title": "Property Name",
              "description": "Name of the property",
              "type": "string"
            },
            "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"
            },
            "squareFeet": {
              "title": "Expansion Area",
              "description": "Square footage for renovated additions to the property.",
              "type": "integer",
            }
          }
        }
      }
    }
  },
  "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}"
}

Substituir um campo padrão em um esquema

Campos de classes padrão, grupos de campos e tipos de dados não podem ser descontinuados diretamente. Em vez disso, você pode descontinuar o uso deles nos esquemas individuais que empregam esses recursos padrão usando um descritor.

Criar um descritor de descontinuação de campo

Para criar um descritor para os campos de esquema que deseja descontinuar, faça uma solicitação POST para o /tenant/descriptors terminal.

Formato da API

POST /tenant/descriptors

Solicitação

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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": "xdm:descriptorDeprecated",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/faxPhone"
      }'

Resposta

{
    "@id": "d882b1202bac0ac71f1e31fbcd9afbcc37f364270186b4b3",
    "@type": "xdm:descriptorDeprecated",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/faxPhone",
    "imsOrg": "{IMS_ORG}",
    "version": "1",
    "meta:containerId": "tenant",
    "meta:sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
    "meta:sandboxType": "production"
}

Verificar o campo obsoleto

Após a aplicação do descritor, é possível verificar se o campo foi descontinuado, pesquisando o esquema em questão ao usar o método apropriado Accept cabeçalho.

Formato da API

GET /tenant/schemas

Solicitação

Para incluir informações sobre campos obsoletos na resposta da API, é necessário definir o Accept cabeçalho para application/vnd.adobe.xed-deprecatefield+json; version=1.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5 \
  -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 'Accept: application/vnd.adobe.xed-deprecatefield+json; version=1'

Resposta

Uma resposta bem-sucedida retorna os detalhes do esquema, com o campo obsoleto contendo um meta:status valor de deprecated. O exemplo de resposta a seguir foi truncado por questões de espaço.

"faxPhone": {
    "title": "Fax phone",
    "description": "Fax phone number.",
    "type": "object",
    "meta:xdmType": "object",
    "properties": {},
    "meta:referencedFrom": "https://ns.adobe.com/xdm/context/phonenumber",
    "meta:xdmField": "xdm:faxPhone",
    "meta:status": "deprecated"
}

Próximas etapas

Este documento abordou como descontinuar campos XDM usando a API do registro de esquema. Para obter mais informações sobre a configuração de campos para recursos personalizados, consulte o guia em definição de campos XDM na API. Para obter mais informações sobre o gerenciamento de descritores, consulte guia de endpoint de descritores.