Para impulsionar experiências coordenadas, consistentes e personalizadas para seus clientes em vários canais em tempo real, os dados certos precisam estar prontamente disponíveis e continuamente atualizados à medida que as alterações ocorrem. O Adobe Experience Platform permite esse acesso em tempo real aos dados por meio do uso do que é conhecido como bordas. Uma borda é um servidor geograficamente posicionado que armazena dados e os torna prontamente acessíveis aos aplicativos. Por exemplo, aplicativos Adobe, como Adobe Target e Adobe Campaign, usam bordas para fornecer experiências personalizadas ao cliente em tempo real. Os dados são roteados para uma borda por uma projeção, com um destino de projeção que define a borda para a qual os dados serão enviados e uma configuração de projeção que define as informações específicas que serão disponibilizadas na borda. Este guia fornece instruções detalhadas para usar o Real-Time Customer Profile API para trabalhar com projeções de borda, incluindo destinos e configurações.
O endpoint da API usado neste guia faz parte da Real-Time Customer Profile 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 Experience Platform API.
Solicitações que contêm uma carga (POST, PUT, PATCH) exigem uma Content-Type
cabeçalho. Mais de um Content-Type
é usado neste documento. Preste atenção especial aos cabeçalhos nas chamadas de exemplo para garantir que você esteja usando o caminho correto Content-Type
para cada solicitação.
Uma projeção pode ser roteada para uma ou mais bordas especificando os locais para os quais os dados devem ser enviados. Cada destino de projeção criado tem uma ID exclusiva que é usada para criar a configuração de projeção.
Você pode listar os destinos de borda que já foram criados para sua organização fazendo uma solicitação GET para o /config/destinations
terminal.
Formato da API
GET /config/destinations
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/config/destinations \
-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
A resposta inclui uma projectionDestinations
com os detalhes de cada destino mostrado como um objeto individual dentro da matriz. Se nenhuma projeção tiver sido configurada, a variável projectionDestinations
a matriz retorna vazia.
Esta resposta foi encurtada por questões de espaço e mostra apenas dois destinos.
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations",
"templated": false
}
},
"_embedded": {
"projectionDestinations": [
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations/cef0e2ef-5249-4e25-be90-94f5797a2841",
"templated": false
}
},
"id": "cef0e2ef-5249-4e25-be90-94f5797a2841",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"VA5"
],
"version": 1
},
{
"_links": {
"self": {
"href": "/data/core/ups/config/destinations/7d26263f-a5df-43ce-b088-7f70e187f549",
"templated": false
}
},
"id": "7d26263f-a5df-43ce-b088-7f70e187f549",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"OR1"
],
"version": 1
}
]
}
}
Propriedade | Descrição |
---|---|
_links.self.href |
No nível superior, corresponde ao caminho usado para fazer a solicitação do GET. Em cada objeto de destino individual, esse caminho pode ser usado em uma solicitação do GET para pesquisar os detalhes de um destino específico diretamente. |
id |
Em cada objeto de destino, a variável "id" mostra o identificador exclusivo gerado pelo sistema e somente leitura para o destino. Essa ID é usada ao fazer referência a um destino específico e ao criar configurações de projeção. |
Para obter mais informações sobre os atributos de um destino individual, consulte a seção sobre criação de um destino a seguir.
Se o destino desejado ainda não existir, você poderá criar um novo destino de projeção fazendo uma solicitação POST para o /config/destinations
terminal.
Formato da API
POST /config/destinations
Solicitação
A solicitação a seguir cria um novo destino de borda.
A solicitação POST para criar um destino requer um Content-Type
conforme mostrado abaixo. Uso de um incorreto Content-Type
O cabeçalho do resulta em um erro HTTP Status 415 (Tipo de mídia não compatível).
curl -X POST \
https://platform.adobe.io/data/core/ups/config/destinations \
-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 'Content-Type: application/vnd.adobe.platform.projectionDestination+json; version=1' \
-d '{
"type": "EDGE",
"dataCenters": [
"OR1"
],
"ttl": 3600,
"replicationPolicy": REACTIVE
}'
Propriedade | Descrição |
---|---|
type (Obrigatório) |
O tipo de destino a ser criado. O único valor aceito, "EDGE", cria um destino de borda. |
dataCenters (Obrigatório) |
Uma matriz de cadeia de caracteres que lista as bordas para as quais as projeções devem ser roteadas. Pode conter um ou mais dos seguintes valores: "OR1" - Oeste dos Estados Unidos, "VA5" - Leste dos Estados Unidos, "NLD1" - EMEA. |
ttl (Obrigatório) |
Especifica a expiração da projeção. Intervalo de valores aceito: 600 a 604800. Valor padrão: 3600. |
replicationPolicy (Obrigatório) |
Define o comportamento da replicação de dados do hub para as bordas. Valores compatíveis: PROACTIVE, REATIVE. Valor padrão: REATIVE. |
Resposta
Uma resposta bem-sucedida retorna os detalhes do destino de borda recém-criado, incluindo a ID exclusiva somente leitura gerada pelo sistema (id
).
{
"self": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"id": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"type": "EDGE",
"dataCenters": [
"OR1"
],
"ttl": 3600,
"version": 1
}
Propriedade | Descrição |
---|---|
self.href |
Esse caminho é usado para pesquisar (GET) o destino diretamente e também pode ser usado para atualizar (PUT) ou excluir (DELETE) o destino. |
id |
A ID exclusiva somente leitura gerada pelo sistema para o destino. Essa ID é usada para fazer referência ao destino diretamente e ao criar configurações de projeção. |
version |
Este valor somente leitura mostra a versão atual do destino. Quando um destino é atualizado, o número da versão é incrementado automaticamente. |
Se você souber o ID exclusivo de um destino de projeção, poderá executar uma solicitação de pesquisa para exibir seus detalhes. Isso é feito fazendo uma solicitação GET ao /config/destinations
e incluindo a ID do destino no caminho da solicitação.
Formato da API
GET /config/destinations/{DESTINATION_ID}
Parâmetro | Descrição |
---|---|
{DESTINATION_ID} |
A ID exclusiva do destino da projeção que você deseja visualizar. |
Solicitação
A solicitação a seguir executa uma pesquisa (GET) para exibir o destino da ID fornecida no caminho da solicitação.
curl -X GET \
https://platform.adobe.io/data/core/ups/config/destinations/9d66c06e-c745-480c-b64c-1d5234d25f4b \
-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
O objeto de resposta mostra os detalhes do destino da projeção. A variável id
O atributo deve corresponder à ID do destino da projeção fornecida na solicitação.
{
"self": {
"href": "/data/core/ups/config/destinations/cef0e2ef-5249-4e25-be90-94f5797a2841",
"templated": false
},
"id": "cef0e2ef-5249-4e25-be90-94f5797a2841",
"type": "EDGE",
"ttl": 3600,
"dataCenters": [
"OR1"
],
"version": 1
}
Um destino existente pode ser atualizado fazendo uma solicitação PUT para o /config/destinations
e incluindo a ID do destino a ser atualizado no caminho da solicitação. Essa operação está essencialmente reescrevendo o destino, portanto, os mesmos atributos devem ser fornecidos no corpo da solicitação, como são fornecidos ao criar um novo destino.
A resposta da API à solicitação de atualização é imediata, no entanto, as alterações nas projeções são aplicadas de forma assíncrona. Em outras palavras, há uma diferença de tempo entre quando a atualização da definição do destino é feita e quando ela é aplicada.
Formato da API
PUT /config/destinations/{DESTINATION_ID}
Parâmetro | Descrição |
---|---|
{DESTINATION_ID} |
A ID exclusiva do destino de projeção que você deseja atualizar. |
Solicitação
A solicitação a seguir atualiza o destino existente para incluir um segundo local (dataCenters
).
A solicitação PUT requer um Content-Type
conforme mostrado abaixo. Uso de um incorreto Content-Type
O cabeçalho do resulta em um erro HTTP Status 415 (Tipo de mídia não compatível).
curl -X PUT \
https://platform.adobe.io/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7 \
-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 'Content-Type: application/vnd.adobe.platform.projectionDestination+json' \
-d '{
"type": "EDGE",
"dataCenters": [
"OR1",
"VA5"
],
"replicationPolicy": REACTIVE,
"currentVersion": 1
}'
Propriedade | Descrição |
---|---|
currentVersion |
A versão atual do destino existente. O valor de version atributo ao executar uma solicitação de pesquisa para o destino. |
Resposta
A resposta inclui os detalhes atualizados do destino, incluindo sua ID e o novo version
do destino.
{
"self": {
"href": "/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7",
"templated": false
},
"id": "8b90ce19-e7dd-403a-ae24-69683a6674e7",
"type": "EDGE",
"ttl": 8000,
"dataCenters": [
"OR1",
"VA5"
],
"version": 2
}
Se sua organização não exigir mais um destino de projeção, ele poderá ser excluído fazendo uma solicitação DELETE para o /config/destinations
e incluindo a ID do destino que você deseja excluir no caminho da solicitação.
A resposta da API à solicitação de exclusão é imediata, no entanto, as alterações reais nos dados nas bordas ocorrem de forma assíncrona. Em outras palavras, os dados do perfil serão removidos de todas as bordas (a variável dataCenters
especificado no destino da projeção), mas o processo levará tempo para ser concluído.
Formato da API
DELETE /config/destinations/{DESTINATION_ID}
Parâmetro | Descrição |
---|---|
{DESTINATION_ID} |
A ID exclusiva do destino de projeção que você deseja excluir. |
Solicitação
curl -X DELETE \
https://platform.adobe.io/data/core/ups/config/destinations/8b90ce19-e7dd-403a-ae24-69683a6674e7 \
-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
A solicitação de exclusão retorna o status HTTP 204 (Sem conteúdo) e um corpo de resposta vazio. Você pode confirmar que a exclusão foi bem-sucedida executando uma solicitação de pesquisa para o destino pela respectiva ID. A pesquisa deve retornar o status HTTP 404 (Não encontrado).
As configurações de projeção fornecem informações sobre quais dados devem estar disponíveis em cada borda. Em vez de projetar uma Experience Data Model (XDM) para a borda, uma projeção fornece apenas dados específicos, ou campos, do esquema. Sua organização pode definir mais de uma configuração de projeção para cada esquema XDM.
Você pode listar todas as configurações de projeção que foram criadas para sua organização fazendo uma solicitação GET para a /config/projections
terminal. Você também pode adicionar parâmetros opcionais ao caminho da solicitação para acessar configurações de projeção para um determinado esquema ou pesquisar uma projeção individual por seu nome.
Formato da API
GET /config/projections
GET /config/projections?schemaName={SCHEMA_NAME}
GET /config/projections?schemaName={SCHEMA_NAME}&name={PROJECTION_NAME}
Parâmetro | Descrição |
---|---|
{SCHEMA_NAME} |
O nome da classe de esquema associada à configuração de projeção que você deseja acessar. |
{PROJECTION_NAME} |
O nome da configuração de projeção que você deseja acessar. |
schemaName
é necessário ao usar o name
como um nome de configuração de projeção é exclusivo somente no contexto de uma classe de schema.
Solicitação
A solicitação a seguir lista todas as configurações de projeção associadas ao Experience Data Model classe de esquema, XDM Individual Profile. Para obter mais informações sobre o XDM e sua função no Platform, comece lendo o Visão geral do sistema XDM.
curl -X GET \
https://platform.adobe.io/data/core/ups/config/projections?schemaName=_xdm.context.profile \
-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 uma lista de configurações de projeção na raiz _embedded
atributo, contido na variável projectionConfigs
matriz. Se nenhuma configuração de projeção tiver sido feita para sua organização, a variável projectionConfigs
A matriz estará vazia.
{
"_links": {
"self": {
"href": "/data/core/ups/config/projections",
"templated": false
}
},
"_embedded": {
"projectionConfigs": [
{
"_links": {
"destination": {
"href": "/data/core/ups/config/destinations/a689248a-5d2b-44af-bb70-c8f17f97011b",
"templated": false
},
"self": {
"href": "/data/core/ups/config/projections/99aed0bc-c183-4997-ada7-7843642e08f6",
"templated": false
}
},
"_embedded": {
"destination": {
"self": {
"href": "/data/core/ups/config/destinations/a689248a-5d2b-44af-bb70-c8f17f97011b",
"templated": false
},
"id": "a689248a-5d2b-44af-bb70-c8f17f97011b",
"type": "EDGE",
"ttl": 1000,
"dataCenters": [
"OR1"
],
"version": 1
}
},
"selector": "strategy",
"version": 2,
"id": "99aed0bc-c183-4997-ada7-7843642e08f6",
"schemaName": "_xdm.context.profile",
"name": "adcloud_rlsa",
"destinationId": "a689248a-5d2b-44af-bb70-c8f17f97011b"
},
]
}
}
Você pode criar (POST) uma nova configuração de projeção que determinará quais campos XDM serão disponibilizados nas bordas.
Formato da API
POST /config/projections?schemaName={SCHEMA_NAME}
Parâmetro | Descrição |
---|---|
{SCHEMA_NAME} |
O nome da classe de esquema associada à configuração de projeção que você deseja acessar. |
Solicitação
A solicitação POST para criar uma configuração requer um Content-Type
conforme mostrado abaixo. Uso de um incorreto Content-Type
O cabeçalho do resulta em um erro HTTP Status 415 (Tipo de mídia não compatível).
curl -X POST \
https://platform.adobe.io/data/core/ups/config/projections?schemaName=_xdm.context.profile \
-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 'Content-Type: application/vnd.adobe.platform.projectionConfig+json; version=1' \
-d '{
"selector": "emails,person(firstName)",
"name": "my_test_projection",
"destinationId": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4"
}'
Propriedade | Descrição |
---|---|
selector |
Uma string que contém uma lista de propriedades no esquema que devem ser replicadas nas bordas. As práticas recomendadas para trabalhar com seletores estão disponíveis no Seletores seção deste documento. |
name |
Um nome descritivo para a nova configuração de projeção. |
destinationId |
O identificador do destino de borda para o qual os dados serão projetados. |
Resposta
Uma resposta bem-sucedida retorna os detalhes da configuração de projeção recém-criada.
{
"_links": {
"destination": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"self": {
"href": "/data/core/ups/config/projections/87fcd0bc-c183-4997-daf9-7843642g95a1",
"templated": false
}
},
"_embedded": {
"destination": {
"self": {
"href": "/data/core/ups/config/destinations/cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"templated": false
},
"id": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4",
"type": "EDGE",
"ttl": 1000,
"dataCenters": [
"OR1"
],
"version": 1
}
},
"selector": "emails,person(firstName)",
"version": 2,
"id": "87fcd0bc-c183-4997-daf9-7843642g95a1",
"schemaName": "_xdm.context.profile",
"name": "my_test_projection",
"destinationId": "cc5a3bd1-f2b9-4965-b9bd-4e7416a02cd4"
}
Um seletor é uma lista separada por vírgulas de nomes de campos XDM. Em uma configuração de projeção, o seletor designa as propriedades a serem incluídas nas projeções. O formato do selector
O valor do parâmetro é baseado livremente na sintaxe XPath. A sintaxe compatível está resumida abaixo, com exemplos adicionais fornecidos para referência.
field
que está aninhado dentro de um campo chamado foo
, usar o seletor foo.field
."( )"
.
addresses(type,city.country)
retorna somente o tipo de endereço e o país no qual a cidade do endereço está localizada para cada addresses
elemento de matriz.addresses.type,addresses.city.country
.A notação de pontos e a notação entre parênteses são compatíveis com subcampos de referência. No entanto, é prática recomendada usar a notação de pontos, pois ela é mais concisa e fornece uma ilustração melhor da hierarquia de campos.
Os exemplos a seguir mostram exemplos selector
parâmetros, seguidos pelos valores estruturados que representam.
person.lastName
Retorna a variável lastName
subcampo do person
no recurso solicitado.
{
"person": {
"lastName": "Smith"
}
}
endereços
Retorna todos os elementos na variável addresses
incluindo todos os campos em cada elemento, mas nenhum outro campo.
{
"addresses": [
{
"type": "home",
"street1": "100 Great Mall Parkway",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"street1": "1 Main Street",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
person.lastName, addresses
Retorna a variável person.lastName
e todos os elementos na variável addresses
matriz.
{
"person": {
"lastName": "Smith"
},
"addresses": [
{
"type": "home",
"street1": "100 Great Mall Parkway",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"street1": "1 Main Street",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
addresses.city
Retorna somente o campo cidade para todos os elementos na matriz de endereços.
{
"addresses": [
{
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
Sempre que um campo aninhado é retornado, a projeção inclui os objetos pai delimitadores. Os campos pai não incluem outros campos filho, a menos que também sejam selecionados explicitamente.
addresses(type,city)
Retorna apenas os valores de type
e city
campos para cada elemento na addresses
matriz. Todos os outros subcampos contidos em cada addresses
elementos são filtrados.
{
"addresses": [
{
"type": "home",
"city": {
"name": "San Jose",
"country": "United States"
}
},
{
"type": "work",
"city": {
"name": "San Jose",
"country": "United States"
}
}
]
}
Este guia mostrou as etapas envolvidas para configurar projeções e destinos, incluindo como formatar corretamente a variável selector
parâmetro. Agora você pode criar novos destinos de projeção e configurações específicos para as necessidades de sua organização.