Guia de solução de problemas do sistema XDM

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

Experience Data Model (XDM) é uma especificação de código aberto que define schemas padronizados para o gerenciamento de experiência do cliente. A metodologia na qual Experience Platform é criado, Sistema XDM, opera schemas Experience Data Model para uso pelos serviços Platform. O Schema Registry fornece uma interface de usuário e uma RESTful API para acessar o Schema Library em Experience Platform. Consulte a documentação 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.

Como faço para adicionar campos a um schema?

É possível adicionar campos a um schema usando uma combinação. Cada mistura é compatível com uma ou mais classes, permitindo que a mistura seja usada em qualquer schema que implemente uma dessas classes compatíveis. Enquanto a Adobe Experience Platform fornece várias combinações do setor com seus próprios campos predefinidos, você pode adicionar seus próprios campos a um schema criando novas combinações usando a API ou a interface do usuário.

Para obter detalhes sobre como criar novas combinações na API Schema Registry, consulte o guia de ponto de extremidade de mixagem. Se você estiver usando a interface do usuário, consulte o tutorial Editor de Schemas.

Quais são os melhores usos para misturas e tipos de dados?

As Misturas são componentes que definem um ou mais campos em um schema. As misturas impõem como seus campos aparecem na hierarquia do schema e, portanto, exibem a mesma estrutura em cada schema em que estão incluídos. As misturas só são compatíveis com classes específicas, conforme identificado pelo atributo meta:intendedToExtend.

Os tipos de dados também podem fornecer um ou mais campos para um schema. No entanto, ao contrário das combinações, os tipos de dados não sã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 schemas com classes potencialmente diferentes.

Qual é a ID exclusiva de um schema?

Todos os recursos Schema Registry (schemas, misturas, tipos de dados, classes) têm um URI que atua como uma ID exclusiva para fins de referência e pesquisa. Ao exibir um schema 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 do desenvolvedor da API Schema Registry.

Quando um start de schema impede a quebra de alterações?

É possível fazer alterações de quebra em um schema, desde que ele nunca tenha sido usado na criação de um conjunto de dados ou esteja habilitado para uso em Real-time Customer Profile. Depois que um schema é usado na criação do conjunto de dados ou ativado para uso com Real-time Customer Profile, as regras de Evolução do Schema tornam-se rigorosamente aplicadas pelo sistema.

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

Um tipo de campo longo é um número 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 JavaScript do JSON representam inteiros longos.

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

Como definir identidades para o meu schema?

Em Experience Platform, as identidades são usadas para identificar um assunto (normalmente uma pessoa individual) independentemente das fontes de dados que estão sendo interpretadas. São definidos em schemas marcando os campos de chave como "Identidade". Os campos usados frequentemente para identificação incluem endereço de email, número de telefone, Experience Cloud ID (ECID), ID do 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 pela criação de descritores de identidade. Os descritores de identidade sinalizam que uma propriedade específica de um schema é um identificador exclusivo.

Os descritores de identidade são criados por uma solicitação de POST para o terminal /descriptors. Se 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 do usuário

Com o schema aberto no Editor de Schemas, 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 Identity.

Para obter mais detalhes sobre como gerenciar identidades na interface do usuário, consulte a seção definindo campos de identidade no tutorial do Editor de Schemas.

Meu schema precisa de uma identidade primária?

As identidades primárias são opcionais, já que os schemas podem ter 0 ou 1 delas. No entanto, um schema deve ter uma identidade primária para que o schema seja habilitado para uso em Real-time Customer Profile. Consulte a seção identity do tutorial do Editor de Schemas para obter mais informações.

Como faço para ativar um schema para uso em Real-time Customer Profile?

Os schemas são habilitados para uso em Real-time Customer Profile por meio da adição de uma tag "união", localizada no atributo meta:immutableTags do schema. A ativação de um schema para uso com Profile pode ser feita usando a API ou a interface do usuário.

Habilitar um schema existente para Profile usando a API

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

Para obter mais informações sobre como usar a API para ativar um schema para uso em Real-time Customer Profile, consulte o documento união do guia do desenvolvedor Schema Registry.

Habilitar um schema existente para Profile usando a interface do usuário

Em Experience Platform, selecione Schemas na navegação à esquerda e selecione o nome do schema que deseja ativar na lista de schemas. Em seguida, no lado direito do editor em Propriedades do Schema, selecione Perfil para ativá-lo.

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

Posso editar uma schema de união diretamente?

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

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

Como devo formatar meu arquivo de dados para assimilar dados em meu schema?

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

Erros e solução de problemas

A seguir está uma lista de mensagens de erro que podem ser encontradas ao trabalhar com a API Schema Registry.

Objeto não encontrado

{
    "type": "/placeholder/type/uri",
    "status": 404,
    "title": "NotFoundError",
    "detail": "Object https://ns.adobe.com/incorrectTenantId/schemas/ee067e31b08514d21e2b82577813409d 
      with version 1 not found"
}

Este erro é exibido quando o sistema não conseguiu localizar um recurso específico. O recurso pode ter sido excluído ou o caminho na chamada da API é inválido. Verifique se você inseriu um caminho válido para sua chamada de API antes de tentar novamente. Você pode verificar se digitou a ID correta para o recurso e se o caminho foi nomeado 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 container e identificação de recursos no guia do desenvolvedor Schema Registry.

O título deve ser exclusivo

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "Title must be unique. An object 
      https://ns.adobe.com/{TENANT_ID}/schemas/26f6833e55db1dd8308aa07a64f2042d 
      already exists with the same title."
}

Esta 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 uma combinação com um título que já está sendo usado por um schema, você receberá esse erro.

Campos personalizados devem usar um campo de nível superior

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For custom fields, you must use a top level field named _{TENANT_ID}
       and all the other fields must be defined under it"
}

Esta mensagem de erro é exibida quando você tenta criar uma nova combinação com campos com nomes inadequados. As misturas definidas pela organização IMS devem namespace seus campos por um TENANT_ID para evitar conflitos com outros recursos do setor e do fornecedor. Exemplos detalhados de estruturas de dados adequadas para misturas podem ser encontrados no guia de ponto de extremidade mixins.

Real-time Customer Profile erros

As seguintes mensagens de erro estão associadas a operações envolvidas na ativação de schemas para Real-time Customer Profile. Consulte a seção união no guia do desenvolvedor da API Schema Registry para obter mais informações.

Para habilitar conjuntos de dados de perfil, o schema deve ser válido

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "To enable profile datasets the schema should be valid"
}

Esta mensagem de erro é exibida quando você tenta habilitar um conjunto de dados de perfil para um schema que não foi habilitado para Real-time Customer Profile. Verifique se o schema contém uma tag de união antes de habilitar o conjunto de dados.

Deve haver um descritor de identidade de referência

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For a schema to be able to participate in union, if any of its 
      property is associated with a xdm:descriptorOneToOne descriptor, there must 
      be a xdm:descriptorReferenceIdentity descriptor for that property"
}

Esta mensagem de erro é exibida quando você tenta habilitar um schema 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 schema em questão para resolver esse erro.

As namespaces do campo do descritor de identidade de referência e do schema de destino devem corresponder

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "If both schemas from an already defined xdm:descriptorOneToOne 
      descriptor are promoted to union, and if there is a primary identity on one of 
      the schemas from the xdm:descriptorOneToOne descriptor, the 
      xdm:identityNamespace of the sourceSchema's descriptorReferenceIdentity and the 
      xdm:namespace field of the xdm:descriptorIdentity for the destinationSchema must 
      match"
}

Para habilitar schemas que contêm descritores de relacionamento para uso em Profile, a namespace do campo de origem e a namespace primária do campo público alvo devem ser as mesmas. Esta mensagem de erro é exibida quando você tenta ativar um schema que contém uma namespace não correspondente para seu descritor de identidade de referência. Verifique se o valor xdm:namespace do campo de identidade do schema de destino corresponde ao valor da propriedade xdm:identityNamespace no descritor de identidade de referência do campo de origem para resolver esse problema.

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

Aceitar erros de cabeçalho

A maioria das solicitações de GET na API Schema Registry requer um cabeçalho Accept (Aceito) para que o sistema determine como formatar a resposta. A seguir está uma lista de erros comuns associados ao cabeçalho Accept (Aceitar). Para obter listas de cabeçalhos Accept compatíveis para solicitações de API diferentes, consulte suas seções correspondentes no Guia do desenvolvedor do Registro do Schema.

Aceitar parâmetro de cabeçalho é obrigatório

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Accept header parameter is required"
}

Esta mensagem de erro é exibida quando um cabeçalho Accept está ausente de uma solicitação de API. Certifique-se de que um cabeçalho Accept esteja incluído antes de tentar novamente.

Mídia de aceitação desconhecida fornecida

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept media supplied: xed+json"
}

Esta mensagem de erro é exibida quando um cabeçalho Accept é inválido. Verifique se você inseriu corretamente um cabeçalho Accept compatível com a solicitação de API que você está tentando fazer antes de tentar novamente.

Formato de Aceitação Desconhecido disponível

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept format available "
}

Esta mensagem de erro é exibida quando o cabeçalho Accept (Aceitar) é fornecido incorretamente ao procurar um descritor. Verifique se você inseriu corretamente um dos cabeçalhos de < a0/>aceitos suportados para descritores](./api/descriptors.md) antes de tentar novamente.[

A versão deve ser fornecida no cabeçalho Aceitar

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full-notext+json; version=1"
}

Esta mensagem de erro é exibida quando um número de versão não foi incluído no cabeçalho Aceitar. Determinados elementos, como schemas, exigem que uma versão seja especificada ao pesquisar instâncias individuais. Um cabeçalho Accept contendo um número de versão será semelhante ao seguinte:

application/vnd.adobe.xed+json; version=1

Para obter uma lista dos cabeçalhos Accept suportados, consulte a seção Aceitar cabeçalho no guia do desenvolvedor Schema Registry.

A versão não deve ser fornecida no cabeçalho Accept

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must not be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full+json"
}

Se você tentar incluir uma versão no cabeçalho Aceitar ao listar os recursos (GET), você receberá esse erro. As versões são necessárias somente ao tentar uma solicitação de pesquisa em um único recurso. Remova a versão do cabeçalho Accept (Aceitar) para resolver o erro.

Nesta página