Guia de solução de problemas do sistema XDM

Este documento fornece respostas a perguntas frequentes sobre o Experience Data Model (XDM) e o Sistema XDM no Adobe Experience Platform, incluindo um guia de solução de problemas para erros comuns. Para perguntas e soluções de problemas relacionadas a outros serviços da Platform, consulte o guia de solução de problemas do Experience Platform.

Experience Data Model (XDM) é uma especificação de código aberto que define esquemas padronizados para o gerenciamento da experiência do cliente. A metodologia na qual Experience Platform é criado, Sistema XDM, operacionaliza Experience Data Model esquemas para uso pelos serviços Platform. O Schema Registry fornece uma interface de usuário e uma API RESTful para acessar o Schema Library em Experience Platform. Consulte a documentação do XDM para obter mais informações.

Perguntas frequentes

Veja a seguir uma lista de respostas para perguntas frequentes sobre o Sistema XDM e o uso da API Schema Registry.

Noções básicas de esquema

Nesta seção, você pode encontrar respostas para perguntas fundamentais sobre a estrutura do esquema, o uso de campo e a identificação no Sistema XDM.

Como adicionar campos a um esquema?

Você pode adicionar campos a um esquema usando um grupo de campos de esquema. Cada grupo de campos é compatível com uma ou mais classes, permitindo que o grupo de campos seja usado em qualquer esquema que implemente uma dessas classes compatíveis. Embora a Adobe Experience Platform forneça vários grupos de campos do setor com seus próprios campos predefinidos, você pode adicionar seus próprios campos a um esquema criando grupos de campos personalizados usando a API ou a interface do usuário.

Para obter detalhes sobre como criar grupos de campos na API Schema Registry, consulte o manual de ponto de extremidade do grupo de campos. Se você estiver usando a interface, consulte o tutorial do Editor de esquemas.

Quais são os melhores usos para grupos de campos em relação aos tipos de dados?

Grupos de campos são componentes que definem um ou mais campos em um esquema. Os grupos de campos impõem como os campos aparecem na hierarquia do esquema e, portanto, exibem a mesma estrutura em cada esquema em que estão incluídos. Os grupos de campos são compatíveis apenas com classes específicas, conforme identificado pelo seu atributo meta:intendedToExtend.

Os tipos de dados também podem fornecer um ou mais campos para um esquema. No entanto, diferentemente dos grupos de campos, os tipos de dados não estão restritos a uma classe específica. Isso torna os tipos de dados uma opção mais flexível para descrever estruturas de dados comuns que são reutilizáveis em vários esquemas com classes potencialmente diferentes.

Qual é o identificador exclusivo de um esquema?

Todos os recursos do Schema Registry (esquemas, grupos de campos, tipos de dados, classes) têm um URI que atua como uma ID exclusiva para fins de referência e pesquisa. Ao visualizar um esquema na API, ele pode ser encontrado nos atributos $id e meta:altId de nível superior.

Para obter mais informações, consulte a seção identificação de recursos no guia de API Schema Registry.

Qual é o tamanho máximo de um tipo de campo longo?

Um tipo de campo longo é um inteiro com um tamanho máximo de 53(+1) bits, dando a ele um intervalo potencial entre -9007199254740992 e 9007199254740992. Isso se deve a uma limitação de como as implementações do JavaScript de JSON representam números inteiros longos.

Para obter mais informações sobre tipos de campos, consulte o documento sobre Restrições de tipo de campo XDM.

O que é meta:AltId?

meta:altId é um identificador exclusivo para um esquema. O meta:altId fornece uma ID de referência fácil para uso em chamadas de API. Essa ID evita a necessidade de ser codificada/decodificada sempre que for usada como com o formato JSON URI.

Quais são as restrições de uso para um tipo de dados de mapa?

O XDM impõe as seguintes restrições ao uso desse tipo de dados:

Consulte as restrições de uso para mapear objetos para obter mais detalhes.

Schema Identity Management

Esta seção contém respostas a perguntas comuns sobre a definição e o gerenciamento de identidades em seus esquemas.

Como definir identidades para meu esquema?

Em Experience Platform, as identidades são usadas para identificar um assunto (normalmente uma pessoa física) independentemente das fontes de dados que estão sendo interpretadas. Eles são definidos em esquemas ao marcar campos principais como "Identidade". Os campos comumente usados para identidade incluem endereço de email, número de telefone, Experience Cloud ID (ECID), ID de CRM e outros campos de ID exclusivos.

Os campos podem ser marcados como identidades usando a API ou a interface do usuário.

Definição de identidades na API

Na API, as identidades são estabelecidas por meio da criação de descritores de identidade. Os descritores de identidade sinalizam que uma propriedade específica de um esquema é um identificador exclusivo.

Os descritores de identidade são criados por uma solicitação POST para o endpoint /descriptors. Se for bem-sucedido, você receberá um Status HTTP 201 (Criado) e um objeto de resposta contendo os detalhes do novo descritor.

Para obter mais detalhes sobre como criar descritores de identidade na API, consulte o documento na seção descritores no guia do desenvolvedor Schema Registry.

Definição de identidades na interface

Com o esquema aberto no Editor de esquemas, selecione o campo na seção Estrutura do editor que você deseja marcar como uma identidade. Em Propriedades do campo no lado direito, marque a caixa de seleção Identidade.

Para obter mais detalhes sobre como gerenciar identidades na interface, consulte a seção sobre definição de campos de identidade no tutorial do Editor de esquemas.

Meu esquema precisa de uma identidade principal?

As identidades primárias são opcionais, pois os esquemas podem ter zero ou uma delas. No entanto, um esquema deve ter uma identidade primária para que o esquema seja habilitado para uso em Real-Time Customer Profile. Consulte a seção identity do tutorial do Editor de esquemas para obter mais informações.

Ativação do perfil de esquema

Esta seção fornece orientação sobre como ativar esquemas para uso com o Perfil de cliente em tempo real.

Como habilitar um esquema para uso no Real-Time Customer Profile?

Os esquemas estão habilitados para uso em Real-Time Customer Profile por meio da adição de uma tag de "união" no atributo meta:immutableTags do esquema. A habilitação de um esquema para uso com Profile pode ser feita usando a API ou a interface do usuário.

Habilitando um esquema existente para Profile usando a API

Faça uma solicitação PATCH para atualizar o esquema e adicionar o atributo meta:immutableTags como uma matriz contendo o valor "union". Se a atualização for bem-sucedida, a resposta mostrará o esquema atualizado que agora contém a tag de união.

Para obter mais informações sobre como usar a API para habilitar um esquema para uso em Real-Time Customer Profile, consulte o documento unions do guia do desenvolvedor Schema Registry.

Habilitando um esquema existente para Profile usando a interface

Em Experience Platform, selecione Esquemas no menu de navegação esquerdo e selecione o nome do esquema que deseja habilitar na lista de esquemas. Em seguida, no lado direito do editor, em Propriedades do esquema, selecione Perfil para ativá-lo.

Para obter mais informações, consulte a seção sobre usar em Perfil de cliente em tempo real no tutorial Editor de esquemas.

Quando os dados do Adobe Analytics são importados como uma origem, o esquema criado automaticamente é ativado para o Perfil?

O esquema não é ativado automaticamente para o Perfil de cliente em tempo real. Você precisa ativar explicitamente o conjunto de dados para o Perfil com base no esquema que está ativado para o Perfil. Consulte a documentação para saber as etapas e os requisitos necessários para habilitar um conjunto de dados para uso no Perfil do Cliente em Tempo Real.

Posso excluir esquemas habilitados para perfil?

Não é possível excluir um esquema depois que ele é ativado para o Perfil de cliente em tempo real. Depois que um esquema é ativado para o Perfil, ele não pode ser desativado ou excluído e os campos não podem ser removidos do esquema. Portanto, é crucial planejar e verificar cuidadosamente a configuração do esquema antes de habilitá-lo para o Perfil. No entanto, você pode excluir um conjunto de dados habilitado para perfil. Informações encontradas aqui: https://experienceleague.adobe.com/pt-br/docs/experience-platform/catalog/datasets/user-guide#delete-a-profile-enabled-dataset

Modificação e restrições do esquema

Esta seção fornece esclarecimentos sobre as regras de modificação de schema e sobre a prevenção de alterações.

Quando um esquema começa a impedir alterações?

Alterações interruptivas podem ser feitas em um esquema desde que ele nunca tenha sido usado na criação de um conjunto de dados ou esteja habilitado para uso no Real-Time Customer Profile. Depois que um esquema é usado na criação do conjunto de dados ou habilitado para uso com Real-Time Customer Profile, as regras de Evolução do Esquema tornam-se estritamente aplicadas pelo sistema.

Posso editar um esquema de união diretamente?

Os esquemas de união são somente leitura e são gerados automaticamente pelo sistema. Eles não podem ser editados diretamente. Os esquemas de união são criados para uma classe específica quando uma tag de "união" é adicionada ao esquema que implementa essa classe.

Para obter mais informações sobre uniões no XDM, consulte a seção uniões no guia de API Schema Registry.

Como devo formatar meu arquivo de dados para assimilar dados no meu esquema?

Experience Platform aceita arquivos de dados no formato Parquet ou JSON. O conteúdo desses arquivos deve estar em conformidade com o esquema referenciado pelo conjunto de dados. Para obter detalhes sobre as práticas recomendadas para assimilação de arquivos de dados, consulte a visão geral de assimilação em lote.

Como posso converter um esquema em um esquema somente leitura?

No momento, não é possível converter um esquema em somente leitura.

Erros e solução de problemas

Esta é uma lista de mensagens de erro que você pode encontrar ao trabalhar com a API Schema Registry.

Recurso não encontrado

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1010-404",
    "title": "Resource not found",
    "status": 404,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found.",
        "sub-errors": []
    },
    "detail": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found."
}

Esse erro é exibido quando o sistema não consegue encontrar um recurso específico. O recurso pode ter sido excluído ou o caminho na chamada à API é inválido. Verifique se você inseriu um caminho válido para a chamada de API antes de tentar novamente. Você pode verificar se inseriu a ID correta para o recurso e se o caminho foi namespace corretamente com o container apropriado (global ou locatário).

Para obter mais informações sobre como construir caminhos de pesquisa na API, consulte as seções contêiner e identificação de recursos no guia do desenvolvedor Schema Registry.

Título não exclusivo

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1521-400",
    "title": "Title not unique",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title",
        "sub-errors": []
    },
    "detail": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title"
}

Essa mensagem de erro é exibida quando você tenta criar um recurso com um título que já está sendo usado por outro recurso. Os títulos devem ser exclusivos em todos os tipos de recursos. Por exemplo, se você tentar criar um grupo de campos com um título que já está sendo usado por um esquema, você receberá esse erro.

Erro de validação de namespace

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1021-400",
    "title": "Namespace validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}.",
        "sub-errors": []
    },
    "detail": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}."
}

Essa mensagem de erro é exibida quando você tenta criar um recurso com campos com namespace incorretamente ou adicionar campos com namespace incorretamente a um recurso existente.

Os recursos definidos pela organização devem incluir os namespaces dos campos na ID do locatário para evitar conflitos com outros recursos do setor e do fornecedor. Ao criar um esquema usando grupos de campos padrão, todos os campos personalizados adicionados na estrutura desses grupos de campos também devem ter o namespace sob a ID do locatário.

Exemplos detalhados de estruturas de dados adequadas para recursos XDM podem ser encontrados no guia da API do registro de esquema:

Cabeçalho Aceitar inválido

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1006-400",
    "title": "Accept header invalid",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json",
        "sub-errors": []
    },
    "detail": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json"
}

As solicitações GET na API Schema Registry exigem um cabeçalho Accept para que o sistema determine como formatar a resposta. Este erro ocorre quando um cabeçalho Accept necessário é inválido ou está ausente.

Dependendo do ponto de extremidade que você está usando, a propriedade detailed-message indica como um cabeçalho Accept válido deve ser exibido para uma resposta bem-sucedida. Verifique se você inseriu corretamente um cabeçalho Accept que seja compatível com a solicitação de API que você está tentando fazer antes de tentar novamente.

Para obter listas de cabeçalhos Accept compatíveis para diferentes solicitações de API, consulte as seções correspondentes no guia do desenvolvedor do Registro de Esquemas.

Real-Time Customer Profile erros

As mensagens de erro a seguir estão associadas a operações envolvidas na habilitação de esquemas para Real-Time Customer Profile. Consulte a seção unions no guia de API Schema Registry para obter mais informações.

Deve haver um descritor de identidade de referência

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1526-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union.",
        "sub-errors": []
    },
    "detail": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union."
}

Esta mensagem de erro é exibida quando você tenta habilitar um esquema para Profile e uma de suas propriedades contém um descritor de relacionamento sem um descritor de identidade de referência. Adicione um descritor de identidade de referência ao campo de esquema em questão para resolver esse erro.

Os namespaces do campo do descritor de identidade de referência e do esquema de destino devem corresponder

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1527-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field.",
        "sub-errors": []
    },
    "detail": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field."
}

Para habilitar esquemas que contenham descritores de relacionamento para uso em Profile, o namespace do campo de origem e o namespace primário do campo de referência devem ser os mesmos. Esta mensagem de erro é exibida quando você tenta ativar um esquema que contém um namespace sem correspondência para seu descritor de identidade de referência.

Para resolver esse problema, verifique se o valor xdm:namespace do campo de identidade do esquema de referência corresponde ao valor da propriedade xdm:identityNamespace no descritor de identidade de referência do campo de origem.

Para obter uma lista de códigos de namespace de identidade padrão, consulte a seção sobre namespaces padrão na visão geral do namespace de identidade.

O esquema deve incluir um identityMap ou identidade primária

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1528-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "To participate in a union, a schema must include an identityMap fieldgroup or a primary identity descriptor.",
        "sub-errors": []
    },
    "detail": "To participate in a union, a schema must include an identityMap fieldgroup or a primary identity descriptor."
}

Antes de habilitar um esquema para Perfil, primeiro crie um descritor de identidade primário para o esquema ou inclua um campo de mapa de identidade para agir na identidade primária.

Não é possível mesclar tipos de dados incompatíveis

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1413-400",
    "title": "Merge Schema Error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "Cannot merge incompatible data types. The path /person/name has already been defined in schema (id=0238be93d3e7a06aec5e0655955901ec) using a different data type. Types: string, object",
        "sub-errors": []
    },
    "detail": "Cannot merge incompatible data types. The path /person/name has already been defined in schema (id=0238be93d3e7a06aec5e0655955901ec) using a different data type. Types: string, object"
}

Todos os esquemas habilitados para perfil pertencentes à mesma classe devem poder se mesclar para construir o esquema de união para essa classe. Esse erro aparece quando você tenta adicionar um campo a um esquema cujo caminho é compartilhado por outro esquema habilitado para perfil e o tipo de dados é diferente do original. Como os esquemas são habilitados para perfil e contêm o mesmo caminho de campo, o Perfil tentaria mesclar esses dois campos em um ao construir o esquema de união. Como tipos de dados diferentes não podem ser mesclados juntos, isso seria considerado um conflito de mesclagem e não é permitido.

Para resolver o problema, escolha um nome diferente para o campo ou aninhe-o em um objeto com namespace exclusivo para evitar conflitos de mesclagem com outros esquemas habilitados para perfil na mesma classe com campos semelhantes.