Endpoint de entidades (Acesso ao perfil)
O Adobe Experience Platform permite que você acesse dados do Real-Time Customer Profile usando APIs RESTful ou a interface do usuário. Este guia descreve como acessar entidades, mais conhecidas como "perfis", usando a API. Para obter mais informações sobre como acessar perfis usando a interface do usuário do Experience Platform, consulte o Guia do usuário do perfil.
Introdução
O ponto de extremidade de API usado neste guia faz parte de Real-Time Customer Profile API. Antes de continuar, consulte 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 do Experience Platform.
Recuperar uma entidade retrieve-entity
Você pode recuperar uma entidade de Perfil fazendo uma solicitação GET para o ponto de extremidade /access/entities
junto com os parâmetros de consulta necessários.
Formato da API
code language-http |
---|
|
Os parâmetros de consulta fornecidos no caminho da solicitação especificam quais dados acessar. É possível incluir vários parâmetros, separados por "E" comercial (&).
Para acessar uma entidade Perfil, você deve fornecer os seguintes parâmetros de consulta:
schema.name
: o nome do esquema XDM da entidade. Nesse caso de uso, oschema.name=_xdm.context.profile
.entityId
: a ID da entidade que você está tentando recuperar.entityIdNS
: O namespace da entidade que você está tentando recuperar. Este valor deve ser fornecido seentityId
for não um XID.
Uma lista completa de parâmetros válidos é fornecida na seção parâmetros de consulta do apêndice.
Solicitação
A solicitação a seguir recupera o email e o nome de um cliente usando uma identidade.
accordion | ||
---|---|---|
Um exemplo de solicitação para recuperar uma entidade usando uma identidade | ||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com a entidade solicitada.
accordion | ||
---|---|---|
Um exemplo de resposta que contém a entidade solicitada | ||
|
note note |
---|
NOTE |
Se um gráfico relacionado vincular mais de 50 identidades, esse serviço retornará o status HTTP 422 e a mensagem "Muitas identidades relacionadas". Se você receber esse erro, considere adicionar mais parâmetros de consulta para restringir sua pesquisa. |
Formato da API
code language-http |
---|
|
Os parâmetros de consulta fornecidos no caminho da solicitação especificam quais dados acessar. É possível incluir vários parâmetros, separados por "E" comercial (&).
Para acessar os dados da Conta B2B, você deve fornecer os seguintes parâmetros de consulta:
schema.name
: o nome do esquema XDM da entidade. Nesse caso de uso, esse valor éschema.name=_xdm.context.account
.entityId
: a ID da entidade que você está tentando recuperar.entityIdNS
: O namespace da entidade que você está tentando recuperar. Este valor deve ser fornecido seentityId
for não um XID.
Uma lista completa de parâmetros válidos é fornecida na seção parâmetros de consulta do apêndice.
Solicitação
accordion | ||
---|---|---|
Um exemplo de solicitação para recuperar uma conta B2B | ||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com a entidade solicitada.
accordion | ||
---|---|---|
Um exemplo de resposta que contém a entidade solicitada | ||
|
Formato da API
code language-http |
---|
|
Os parâmetros de consulta fornecidos no caminho da solicitação especificam quais dados acessar. É possível incluir vários parâmetros, separados por "E" comercial (&).
Para acessar uma entidade de Oportunidade B2B, você deve fornecer os seguintes parâmetros de consulta:
schema.name
: o nome do esquema XDM da entidade. Nesse caso de uso, oschema.name=_xdm.context.opportunity
.entityId
: a ID da entidade que você está tentando recuperar.entityIdNS
: O namespace da entidade que você está tentando recuperar. Este valor deve ser fornecido seentityId
for não um XID.
Uma lista completa de parâmetros válidos é fornecida na seção parâmetros de consulta do apêndice.
Solicitação
accordion | ||
---|---|---|
Uma solicitação de amostra para recuperar uma entidade de oportunidade B2B | ||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com a entidade solicitada.
accordion | ||
---|---|---|
Um exemplo de resposta que contém a entidade solicitada | ||
|
Recuperar várias entidades retrieve-entities
Você pode recuperar várias entidades de Perfil fazendo uma solicitação POST para o ponto de extremidade /access/entities
e fornecendo as identidades na carga.
Formato da API
code language-http |
---|
|
Solicitação
A solicitação a seguir recupera os nomes e endereços de email de vários clientes por uma lista de identidades.
accordion | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Uma solicitação de amostra para recuperar várias entidades | |||||||||||||||||||||||||||||||||||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com os campos solicitados das entidades especificadas no corpo da solicitação.
accordion | ||
---|---|---|
Um exemplo de resposta que contém as entidades solicitadas | ||
|
Formato da API
code language-http |
---|
|
Solicitação
A solicitação a seguir recupera as contas B2B solicitadas.
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Uma solicitação de amostra para recuperar várias entidades | ||||||||||||||||||||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com as entidades solicitadas.
accordion | ||
---|---|---|
Um exemplo de resposta que contém as entidades solicitadas | ||
|
Formato da API
code language-http |
---|
|
Solicitação
A solicitação a seguir recupera as oportunidades B2B solicitadas.
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Uma solicitação de amostra para recuperar várias entidades | ||||||||||||||||||||
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com as entidades solicitadas.
accordion | ||
---|---|---|
Um exemplo de resposta que contém as entidades solicitadas | ||
|
Acessar uma página subsequente de resultados
Os resultados são paginados ao recuperar eventos de série temporal. Se houver páginas subsequentes de resultados, a propriedade _page.next
conterá uma ID. Além disso, a propriedade _links.next.href
fornece um URI de solicitação para recuperar a próxima página. Para recuperar os resultados, faça outra solicitação GET para o ponto de extremidade /access/entities
e substitua /entities
pelo valor do URI fornecido.
/entities/
acidentalmente no caminho da solicitação. Só deve aparecer uma vez como, /access/entities?start=...
Formato da API
GET /access/{NEXT_URI}
{NEXT_URI}
_links.next.href
.Solicitação
A solicitação a seguir recupera a próxima página de resultados usando o URI _links.next.href
como o caminho da solicitação.
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna a próxima página de resultados. Esta resposta não tem páginas subsequentes de resultados, conforme indicado pelos valores de cadeia de caracteres vazios de _page.next
e _links.next.href
.
code language-json |
---|
|
Excluir uma entidade delete-entity
Você pode excluir uma entidade do Repositório de Perfis fazendo uma solicitação DELETE para o ponto de extremidade /access/entities
junto com os parâmetros de consulta necessários.
Formato da API
DELETE /access/entities?{QUERY_PARAMETERS}
Os parâmetros de consulta fornecidos no caminho da solicitação especificam quais dados acessar. É possível incluir vários parâmetros, separados por "E" comercial (&).
Para excluir uma entidade, você deve fornecer os seguintes parâmetros de consulta:
schema.name
: o nome do esquema XDM da entidade. Neste caso de uso, você pode usar somenteschema.name=_xdm.context.profile
.entityId
: a ID da entidade que você está tentando recuperar.entityIdNS
: O namespace da entidade que você está tentando recuperar. Este valor deve ser fornecido seentityId
for não um XID.mergePolicyId
: a ID da política de mesclagem da entidade. A política de mesclagem contém informações sobre identificação de identidade e mesclagem de objetos XDM de valor-chave. Se esse valor não for fornecido, a política de mesclagem padrão será usada.
Solicitação
A solicitação a seguir exclui a entidade especificada.
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 202 com um corpo de resposta vazio.
Próximas etapas
Seguindo este guia, você acessou com êxito Real-Time Customer Profile dados de campos de dados, perfis e séries de tempo. Para saber como acessar outros recursos de dados armazenados no Experience Platform, consulte a visão geral sobre Acesso a Dados.
Apêndice appendix
A seção a seguir fornece informações adicionais sobre o acesso aos dados do Profile usando a API.
Parâmetros de consulta query-parameters
Os parâmetros a seguir são usados no caminho para solicitações GET para o ponto de extremidade /access/entities
. Eles servem para identificar a entidade de perfil que você deseja acessar e filtrar os dados retornados na resposta. Os parâmetros obrigatórios são rotulados, enquanto o restante é opcional.
schema.name
schema.name=_xdm.context.profile
relatedSchema.name
schema.name
for _xdm.context.experienceevent
, esse valor deverá especificar o esquema para a entidade de perfil à qual os eventos de série temporal estão relacionados.relatedSchema.name=_xdm.context.profile
entityId
entityIdNS
).entityId=janedoe@example.com
entityIdNS
entityId
não for fornecido como um XID, este campo deve especificar o namespace de identidade.entityIdNS=email
relatedEntityId
schema.name
for _xdm.context.experienceevent
, esse valor deverá especificar a ID da entidade de perfil relacionada. Este valor segue as mesmas regras que entityId
.relatedEntityId=69935279872410346619186588147492736556
relatedEntityIdNS
schema.name
for "_xdm.context.experienceevent", esse valor deverá especificar o namespace de identidade da entidade especificada em relatedEntityId
.relatedEntityIdNS=CRMID
fields
fields=personalEmail,person.name,person.gender
mergePolicyId
mergePolicyId=5aa6885fcf70a301dabdfa4a
orderBy
(+/-)timestamp
, com o padrão sendo +timestamp
.orderby=-timestamp
startTime
startTime=1539838505
endTime
endTime=1539838510
limit
limit=100
property
property=webPageDetails.isHomepage=true&property=localTime<="2020-07-20"