Ponto de extremidade schemas

Um schema pode ser considerado como o modelo para os dados que você deseja ingerir no Adobe Experience Platform. Cada schema é composto de uma classe e zero ou mais combinações. O endpoint /schemas na API Schema Registry permite que você gerencie programaticamente schemas dentro do seu aplicativo de experiência.

Introdução

O endpoint da API usado neste guia faz parte da Schema Registry API. Antes de continuar, reveja o guia de introdução para obter links para a documentação relacionada, um guia para ler as chamadas de API de amostra neste documento e informações importantes sobre os cabeçalhos necessários que são necessários para fazer chamadas com êxito para qualquer API de Experience Platform.

Recuperar uma lista de schemas

Você pode lista todos os schemas no container global ou tenant, fazendo uma solicitação de GET para /global/schemas ou /tenant/schemas, respectivamente.

OBSERVAÇÃO

Ao listar recursos, o resultado do Limite do Registro do Schema é definido como 300 itens. Para retornar recursos além desse limite, você deve usar parâmetros de paginação. Também é recomendável usar parâmetros de query adicionais para filtrar resultados e reduzir o número de recursos retornados. Consulte a seção sobre parâmetros de query no documento apêndice para obter mais informações.

Formato da API

GET /{CONTAINER_ID}/schemas?{QUERY_PARAMS}
Parâmetro Descrição
{CONTAINER_ID} O container que contém os schemas que você deseja recuperar: global para schemas criados por Adobe ou tenant para schemas pertencentes à sua organização.
{QUERY_PARAMS} Parâmetros de query opcionais para filtrar os resultados. Consulte o documento apêndice para obter uma lista de parâmetros disponíveis.

Solicitação

A solicitação a seguir recupera uma lista de schemas do container tenant, usando um parâmetro de query orderby para classificar os resultados pelo atributo title.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?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}'

O formato de resposta depende do cabeçalho Accept enviado na solicitação. Os seguintes cabeçalhos Accept estão disponíveis para schemas de listagem:

Accept header Descrição
application/vnd.adobe.xed-id+json Retorna um breve resumo de cada recurso. Este é o cabeçalho recomendado para a listagem de recursos. (Limite: 300)
application/vnd.adobe.xed+json Retorna o schema JSON completo para cada recurso, com $ref e allOf originais incluídos. (Limite: 300)

Resposta

A solicitação acima usou o cabeçalho application/vnd.adobe.xed-id+json Accept, portanto, a resposta inclui apenas os atributos title, $id, meta:altId e version para cada schema. Usar o outro cabeçalho Accept (application/vnd.adobe.xed+json) retorna todos os atributos de cada schema. Selecione o cabeçalho Accept apropriado, dependendo das informações necessárias na sua resposta.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0238be93d3e7a06aec5e0655955901ec",
      "meta:altId": "_{TENANT_ID}.schemas.0238be93d3e7a06aec5e0655955901ec",
      "version": "1.4",
      "title": "Hotels"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0ef4ce0d390f0809fad490802f53d30b",
      "meta:altId": "_{TENANT_ID}.schemas.0ef4ce0d390f0809fad490802f53d30b",
      "version": "1.0",
      "title": "Loyalty Members"
    }
  ],
  "_page": {
        "orderby": "title",
        "next": null,
        "count": 2
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

Procure um schema

Você pode pesquisar um schema específico fazendo uma solicitação de GET que inclua a ID do schema no caminho.

Formato da API

GET /{CONTAINER_ID}/schemas/{SCHEMA_ID}
Parâmetro Descrição
{CONTAINER_ID} O container que hospeda o schema que você deseja recuperar: global para um schema criado por Adobe ou tenant para um schema pertencente à sua organização.
{SCHEMA_ID} O meta:altId ou $id codificado por URL do schema que você deseja pesquisar.

Solicitação

A solicitação a seguir recupera um schema especificado pelo valor meta:altId no caminho.

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

O formato de resposta depende do cabeçalho Accept enviado na solicitação. Todas as solicitações de pesquisa exigem que version sejam incluídas no cabeçalho Accept. Os seguintes cabeçalhos Accept estão disponíveis:

Accept header Descrição
application/vnd.adobe.xed+json; version={MAJOR_VERSION} Bruto com $ref e allOf, tem títulos e descrições.
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref e allOf resolvido, tem títulos e descrições.
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} Bruto com $ref e allOf, sem títulos ou descrições.
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref e allOf resolvidos, sem títulos ou descrições.
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $ref e allOf resolvidos, descritores incluídos.

Resposta

Uma resposta bem-sucedida retorna os detalhes do schema. Os campos retornados dependem do cabeçalho Accept enviado na solicitação. Experimente com cabeçalhos Accept diferentes para comparar as respostas e determinar qual cabeçalho é melhor para seu caso de uso.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:altId": "_{TENANT_ID}.schemas.20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:resourceType": "schemas",
  "version": "1.1",
  "title": "Example schema",
  "type": "object",
  "description": "An example schema created within the tenant container.",
  "allOf": [
      {
          "$ref": "https://ns.adobe.com/xdm/context/profile",
          "type": "object",
          "meta:xdmType": "object"
      },
      {
          "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
          "type": "object",
          "meta:xdmType": "object"
      }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": false,
  "meta:abstract": false,
  "meta:extends": [
      "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
      "https://ns.adobe.com/xdm/common/auditable",
      "https://ns.adobe.com/xdm/data/record",
      "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
      "repo:createdDate": 1602872911226,
      "repo:lastModifiedDate": 1603381419889,
      "xdm:createdClientId": "{CLIENT_ID}",
      "xdm:lastModifiedClientId": "{CLIENT_ID}",
      "xdm:createdUserId": "{USER_ID}",
      "xdm:lastModifiedUserId": "{USER_ID}",
      "eTag": "84b4da79b7445a4bf1c59269e718065effddb983c492f48e223d49c049c6d589",
      "meta:globalLibVersion": "1.15.4"
  },
  "meta:class": "https://ns.adobe.com/xdm/context/profile",
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Criar um schema

O processo de composição do schema começa atribuindo uma classe. A classe define os principais aspectos comportamentais dos dados (registro ou série cronológica), bem como os campos mínimos necessários para descrever os dados que serão assimilados.

OBSERVAÇÃO

A chamada de exemplo abaixo é apenas um exemplo básico de como criar um schema na API, com os requisitos mínimos de composição de uma classe e sem combinações. Para obter as etapas completas sobre como criar um schema na API, incluindo como atribuir campos usando misturas e tipos de dados, consulte o tutorial de criação de schemas a1/>.

Formato da API

POST /tenant/schemas

Solicitação

A solicitação deve incluir um atributo allOf que faça referência a $id de uma classe. Este atributo define a "classe base" que o schema implementará. Neste exemplo, a classe base é uma classe "Informações de propriedade" criada anteriormente.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -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 Information",
        "description": "Property-related information.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590" 
          } 
        ]
      }'
Propriedade Descrição
allOf Uma matriz de objetos, com cada objeto referindo-se a uma classe ou combinação cujos campos o schema implementa. Cada objeto contém uma única propriedade ($ref) cujo valor representa $id da classe ou o mixin do novo schema será implementado. Deve ser fornecida uma classe, com zero ou mais misturas adicionais. No exemplo acima, o único objeto na matriz allOf é a classe schema.

Resposta

Uma resposta bem-sucedida retorna o status HTTP 201 (Criado) e uma carga que contém os detalhes do schema recém-criado, incluindo $id, meta:altId e version. Esses valores são somente leitura e são atribuídos pelo Schema Registry.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.0",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088461236,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

A execução de uma solicitação de GET para lista de todos os schemas no container locatário agora inclui o novo schema. Você pode executar uma solicitação de pesquisa (GET) usando o URI $id codificado em URL para visualização do novo schema diretamente.

Para adicionar campos adicionais a um schema, você pode executar uma operação PATCH para adicionar combinações às matrizes allOf e meta:extends do schema.

Atualizar um schema

Você pode substituir um schema inteiro por uma operação de PUT, essencialmente regravando o recurso. Ao atualizar um schema por meio de uma solicitação de PUT, o corpo deve incluir todos os campos que seriam necessários ao criar um novo schema em uma solicitação de POST.

OBSERVAÇÃO

Se você quiser apenas atualizar parte de um schema em vez de substituí-lo totalmente, consulte a seção sobre atualizar uma parte de um schema.

Formato da API

PUT /tenant/schemas/{SCHEMA_ID}
Parâmetro Descrição
{SCHEMA_ID} O meta:altId ou $id codificado por URL do schema que você deseja gravar novamente.

Solicitação

A solicitação a seguir substitui um schema existente, alterando seus atributos title, description e allOf.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -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":"Commercial Property Information",
        "description": "Information related to commercial properties.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7" 
          } 
        ]
      }'

Resposta

Uma resposta bem-sucedida retorna os detalhes do schema atualizado.

{
    "title":"Commercial Property Information",
    "description": "Information related to commercial properties.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.0",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088470592,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Atualizar uma parte de um schema

É possível atualizar uma parte de um schema usando uma solicitação de PATCH. O Schema Registry suporta todas as operações padrão de Patch JSON, incluindo add, remove e replace. Para obter mais informações sobre o Patch JSON, consulte o guia de fundamentos da API.

OBSERVAÇÃO

Se quiser substituir um recurso inteiro por novos valores em vez de atualizar campos individuais, consulte a seção em substituição de um schema usando uma operação PUT.

Uma das operações de PATCH mais comuns envolve a adição de misturas previamente definidas a um schema, como demonstrado pelo exemplo abaixo.

Formato da API

PATCH /tenant/schema/{SCHEMA_ID} 
Parâmetro Descrição
{SCHEMA_ID} O URI $id codificado por URL ou meta:altId do schema que você deseja atualizar.

Solicitação

A solicitação de exemplo abaixo adiciona uma nova combinação a um schema adicionando o valor $id dessa combinação às matrizes meta:extends e allOf.

O corpo da solicitação assume a forma de uma matriz, com cada objeto listado representando uma alteração específica para um campo individual. Cada objeto inclui a operação a ser executada (op), em qual campo a operação deve ser executada (path) e quais informações devem ser incluídas nessa operação (value).

curl -X PATCH\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.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}' \
  -H 'content-type: application/json' \
  -d '[
        { 
          "op": "add",
          "path": "/meta:extends/-",
          "value":  "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        },
        {
          "op": "add",
          "path": "/allOf/-",
          "value":  {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
          }
        }
      ]'

Resposta

A resposta mostra que ambas as operações foram executadas com êxito. A mistura $id foi adicionada à matriz meta:extends e uma referência ($ref) à mistura $id agora aparece na matriz allOf.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Ative um schema para uso no Perfil do cliente em tempo real

Para que um schema participe do Perfil do cliente em tempo real, é necessário adicionar uma tag union ao storage do schema meta:immutableTags. Para fazer isso, faça uma solicitação PATCH para o schema em questão.

IMPORTANTE

Tags imutáveis são tags que devem ser definidas, mas nunca removidas.

Formato da API

PATCH /tenant/schema/{SCHEMA_ID} 
Parâmetro Descrição
{SCHEMA_ID} O URI $id codificado por URL ou meta:altId do schema que você deseja ativar.

Solicitação

A solicitação de exemplo abaixo adiciona uma matriz meta:immutableTags a um schema existente, dando ao storage um valor de sequência de caracteres único de union para permitir seu uso no Perfil.

curl -X PATCH\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.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}' \
  -H 'content-type: application/json' \
  -d '[
        {
          "op": "add",
          "path": "/meta:immutableTags",
          "value": ["union"]
        }
      ]'

Resposta

Uma resposta bem-sucedida retorna os detalhes do schema atualizado, mostrando que a matriz meta:immutableTags foi adicionada.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    },
    "meta:immutableTags": [
      "union"
    ]
}

Agora você pode visualização a união desta classe de schemas para confirmar se os campos de schemas estão representados. Consulte o guia de ponto de extremidade do união para obter mais informações.

Excluir um schema

Por vezes, pode ser necessário remover um schema do Registro do Schema. Isso é feito executando-se uma solicitação de DELETE com a ID do schema fornecida no caminho.

Formato da API

DELETE /tenant/schemas/{SCHEMA_ID}
Parâmetro Descrição
{SCHEMA_ID} O URI $id codificado por URL ou meta:altId do schema que você deseja excluir.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna o status HTTP 204 (Sem conteúdo) e um corpo em branco.

Você pode confirmar a exclusão tentando uma solicitação de pesquisa (GET) para o schema. Você precisará incluir um cabeçalho Accept na solicitação, mas deverá receber um status HTTP 404 (Não encontrado), pois o schema foi removido do Registro do Schema.

Nesta página