Ponto de extremidade de descritores
Os esquemas definem uma visualização estática das entidades de dados, mas não fornecem detalhes específicos sobre como os dados baseados nesses esquemas (conjuntos de dados, por exemplo) podem se relacionar. O Adobe Experience Platform permite descrever esses relacionamentos e outros metadados interpretativos sobre um esquema usando descritores.
Os descritores de esquema são metadados em nível de locatário, o que significa que são exclusivos de sua organização e todas as operações do descritor ocorrem no contêiner do locatário.
Cada esquema pode ter uma ou mais entidades de descritor de esquema aplicadas a ele. Cada entidade do descritor de esquema inclui um descritor @type
e a variável sourceSchema
aos quais se aplica. Depois de aplicados, esses descritores serão aplicados a todos os conjuntos de dados criados usando o esquema.
A variável /descriptors
endpoint na variável Schema Registry A API permite gerenciar descritores de forma programática no aplicativo de experiência.
Introdução
O endpoint usado neste guia faz parte da variável 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 exemplo neste documento e informações importantes sobre os cabeçalhos necessários para fazer chamadas com êxito para qualquer API de Experience Platform.
Recuperar uma lista de descritores list
Você pode listar todos os descritores que foram definidos pela sua organização fazendo uma solicitação para o GET /tenant/descriptors
.
Formato da API
GET /tenant/descriptors
Solicitação
curl -X GET \
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xdm-link+json'
O formato de resposta depende do Accept
cabeçalho enviado na solicitação. Observe que /descriptors
usos do endpoint Accept
cabeçalhos que são diferentes de todos os outros endpoints no Schema Registry API.
Accept
cabeçalhos que substituem xed
com xdm
e também oferecem uma link
que é exclusiva dos descritores. O correto Accept
os cabeçalhos foram incluídos nas chamadas de exemplo abaixo, mas tenha cuidado extra para garantir que os cabeçalhos corretos estejam sendo usados ao trabalhar com descritores.Accept
cabeçalhoapplication/vnd.adobe.xdm-id+json
application/vnd.adobe.xdm-link+json
application/vnd.adobe.xdm+json
application/vnd.adobe.xdm-v2+json
Accept
o cabeçalho deve ser usado para usar recursos de paginação.Resposta
A resposta inclui uma matriz para cada tipo de descritor que tem descritores definidos. Por outras palavras, se não existirem descritores de um certo @type
definido, o registro não retornará uma matriz vazia para esse tipo de descritor.
Ao usar o link
Accept
cada descritor é mostrado como um item de matriz no formato /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
{
"xdm:alternateDisplayInfo": [
"/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
"/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
"/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
],
"xdm:descriptorIdentity": [
"/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
],
"xdm:descriptorOneToOne": [
"/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
]
}
Pesquisar um descritor lookup
Se quiser visualizar os detalhes de um descritor específico, você pode pesquisar (GET) um descritor individual usando sua @id
.
Formato da API
GET /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
do descritor que você deseja pesquisar.Solicitação
A solicitação a seguir recupera um descritor por seu @id
valor. Os descritores não têm controle de versão, portanto, não Accept
o cabeçalho é necessário na solicitação de pesquisa.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-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}'
Resposta
Uma resposta bem-sucedida retorna os detalhes do descritor, incluindo seus @type
e sourceSchema
, bem como informações adicionais que variam dependendo do tipo de descritor. O resultado @id
deve corresponder ao descritor @id
fornecido no pedido.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"createdUser": "{CREATED_USER}",
"imsOrg": "{ORG_ID}",
"createdClient": "{CREATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"created": 1548899346989,
"updated": 1548899346989,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Criar um descritor create
Você pode criar um novo descritor fazendo uma solicitação POST para o /tenant/descriptors
terminal.
Formato da API
POST /tenant/descriptors
Solicitação
A solicitação a seguir define um descritor de identidade em um campo "endereço de email" em um esquema de amostra. Isso informa o Experience Platform usar o endereço de email como um identificador para ajudar a compilar informações sobre o indivíduo.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
-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 '
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 (Criado) e os detalhes do descritor recém-criado, incluindo seu @id
. A variável @id
é um campo somente leitura atribuído pelo Schema Registry e usado para fazer referência ao descritor na API.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Atualizar um descritor put
É possível atualizar um descritor incluindo sua @id
no caminho de uma solicitação PUT.
Formato da API
PUT /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
do descritor que você deseja atualizar.Solicitação
Essa solicitação reescreve essencialmente o descritor, de modo que o corpo da solicitação deve incluir todos os campos necessários para definir um descritor desse tipo. Em outras palavras, a carga da solicitação para atualizar (PUT) um descritor é a mesma que a carga para criar (POST) um descritor do mesmo tipo.
O exemplo a seguir atualiza um descritor de identidade para fazer referência a um xdm:sourceProperty
(mobile phone
) e altere o xdm:namespace
para Phone
.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-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 '{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/mobilePhone/number",
"xdm:namespace": "Phone",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 (Criado) e a variável @id
do descritor atualizado (que deve corresponder ao @id
enviado no pedido).
{
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Executar um solicitação de pesquisa (GET) para exibir o descritor mostra que os campos foram atualizados para refletir as alterações enviadas na solicitação PUT.
Excluir um descritor delete
Ocasionalmente, pode ser necessário remover um descritor definido na Schema Registry. Isso é feito fazendo uma solicitação DELETE referenciando o @id
do descritor que você deseja remover.
Formato da API
DELETE /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
do descritor que você deseja excluir.Solicitação
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2 \
-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}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 204 (Sem conteúdo) e um corpo em branco.
Para confirmar se o descritor foi excluído, é possível executar um solicitação de pesquisa no descritor @id
. A resposta retorna o status HTTP 404 (Não encontrado) porque o descritor foi removido da variável Schema Registry.
Apêndice
A seção a seguir fornece informações adicionais sobre como trabalhar com descritores na Schema Registry API.
Definição de descritores defining-descriptors
As seções a seguir fornecem uma visão geral dos tipos de descritores disponíveis, incluindo os campos obrigatórios para definir um descritor de cada tipo.
Descritor de identidade
Um descritor de identidade sinaliza que "sourceProperty" do "sourceSchema" é um Identity conforme descrito por Serviço de identidade da Adobe Experience Platform.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}
@type
xdm:descriptorIdentity
.xdm:sourceSchema
$id
URI do esquema no qual o descritor está sendo definido.xdm:sourceVersion
xdm:sourceProperty
xdm:namespace
id
ou code
valor do namespace de identidade. Uma lista de namespaces pode ser encontrada usando o Identity Service API.xdm:property
xdm:id
ou xdm:code
, dependendo da xdm:namespace
usado.xdm:isPrimary
Descritor de nome amigável friendly-name
Descritores de nome simples permitem que um usuário modifique a variável title
, description
, e meta:enum
valores dos campos do esquema da biblioteca principal. Especialmente úteis ao trabalhar com "eVars" e outros campos "genéricos" que você deseja rotular como contendo informações específicas da organização. A interface pode usá-los para mostrar um nome mais amigável ou para mostrar apenas campos que tenham um nome amigável.
{
"@type": "xdm:alternateDisplayInfo",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/xdm:eventType",
"xdm:title": {
"en_us": "Event Type"
},
"xdm:description": {
"en_us": "The type of experience event detected by the system."
},
"meta:enum": {
"click": "Mouse Click",
"addCart": "Add to Cart",
"checkout": "Cart Checkout"
},
"xdm:excludeMetaEnum": {
"web.formFilledOut": "Web Form Filled Out",
"media.ping": "Media ping"
}
}
@type
xdm:alternateDisplayInfo
.xdm:sourceSchema
$id
URI do esquema no qual o descritor está sendo definido.xdm:sourceVersion
xdm:sourceProperty
/
) e não terminar com um. Não incluir properties
no caminho (por exemplo, use /personalEmail/address
em vez de /properties/personalEmail/properties/address
).xdm:title
xdm:description
meta:enum
xdm:sourceProperty
é um campo de sequência, meta:enum
pode ser usado para adicionar valores sugeridos para o campo na interface do usuário de segmentação. É importante observar que meta:enum
não declara uma enumeração ou fornece qualquer validação de dados para o campo XDM.Isso só deve ser usado para campos XDM principais definidos pelo Adobe. Se a propriedade de origem for um campo personalizado definido por sua organização, edite o campo
meta:enum
propriedade diretamente por meio de uma solicitação PATCH para o recurso principal do campo.meta:excludeMetaEnum
xdm:sourceProperty
é um campo de string que tem valores sugeridos existentes fornecidos em uma meta:enum
é possível incluir esse objeto em um descritor de nome amigável para excluir alguns ou todos esses valores da segmentação. A chave e o valor de cada entrada devem corresponder aos incluídos no original meta:enum
do campo para que a entrada seja excluída.Descritor de relacionamento
Os descritores de relacionamento descrevem uma relação entre dois esquemas diferentes, anotados nas propriedades descritas em sourceProperty
e destinationProperty
. Veja o tutorial sobre definição de uma relação entre dois schemas para obter mais informações.
{
"@type": "xdm:descriptorOneToOne",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:destinationSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:destinationVersion": 1,
"xdm:destinationProperty": "/parentField/subField"
}
@type
xdm:descriptorOneToOne
.xdm:sourceSchema
$id
URI do esquema no qual o descritor está sendo definido.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
URI do esquema de referência com o qual este descritor está definindo uma relação.xdm:destinationVersion
xdm:destinationProperty
Descritor de identidade de referência
Os descritores de identidade de referência fornecem um contexto de referência para a identidade principal de um campo de esquema, permitindo que ele seja referenciado por campos em outros esquemas. O esquema de referência já deve ter um campo de identidade primário definido para que possa ser referenciado por outros esquemas por meio desse descritor.
{
"@type": "xdm:descriptorReferenceIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:identityNamespace": "Email"
}
@type
xdm:descriptorReferenceIdentity
.xdm:sourceSchema
$id
URI do esquema no qual o descritor está sendo definido.xdm:sourceVersion
xdm:sourceProperty
/personalEmail/address
em vez de /properties/personalEmail/properties/address
).xdm:identityNamespace
Descritor de campo obsoleto
Você pode substituir um campo em um recurso XDM personalizado adicionando um meta:status
atributo definido como deprecated
ao campo em questão. No entanto, se você quiser descontinuar os campos fornecidos pelos recursos XDM padrão em seus esquemas, poderá atribuir um descritor de campo descontinuado ao esquema em questão para obter o mesmo efeito. Usar o correto Accept
cabeçalho, você pode visualizar quais campos padrão estão obsoletos para um esquema ao pesquisá-lo na API.
{
"@type": "xdm:descriptorDeprecated",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/faxPhone"
}
@type
xdm:descriptorDeprecated
.xdm:sourceSchema
$id
do esquema ao qual você está aplicando o descritor.xdm:sourceVersion
1
.xdm:sourceProperty
["/firstName", "/lastName"]
).