Endpoints de configurações e destinos de projeção de borda

Para direcionar 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 atualizados continuamente conforme as mudanças acontecem. O Adobe Experience Platform permite esse acesso em tempo real aos dados por meio do uso de bordas conhecidas como bordas. Uma borda é um servidor localizado geograficamente que armazena dados e a torna acessível para os 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 definindo a borda para a qual os dados serão enviados e uma configuração de projeção definindo as informações específicas que serão disponibilizadas na borda. Este guia fornece instruções detalhadas para usar a API Real-time Customer Profile para trabalhar com projeções de borda, incluindo destinos e configurações.

Introdução

O endpoint da API usado neste guia faz parte do 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 cabeçalhos necessários que são necessários para fazer chamadas com êxito para qualquer API Experience Platform.

Destinos de projeção

Uma projeção pode ser roteada para uma ou mais bordas especificando os locais onde 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.

Listar todos os destinos

Você pode listar os destinos de borda que já foram criados para sua organização, fazendo uma solicitação GET para o endpoint /config/destinations.

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

A resposta inclui uma matriz projectionDestinations com os detalhes de cada destino mostrados como um objeto individual dentro da matriz. Se nenhuma projeção tiver sido configurada, a matriz projectionDestinations retornará vazia.

{
    "_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
            }
        ]
    }
}

Para obter mais informações sobre os atributos de um destino individual, consulte a seção criar um destino que se segue.

Criar um destino

Se o destino necessário ainda não existir, é possível criar um novo destino de projeção fazendo uma solicitação de POST para o endpoint /config/destinations.

Formato da API

POST /config/destinations

Solicitação

A solicitação a seguir cria um novo destino de borda.

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: {IMS_ORG}' \
  -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
      }'

Resposta

Uma resposta bem-sucedida retorna os detalhes do destino de borda recém-criado, incluindo a ID exclusiva gerada pelo sistema somente leitura (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
}

Exibir um destino

Se você souber a ID exclusiva de um destino de projeção, poderá executar uma solicitação de pesquisa para exibir seus detalhes. Isso é feito fazendo uma solicitação GET para o endpoint /config/destinations e incluindo a ID do destino no caminho da solicitação.

Formato da API

GET /config/destinations/{DESTINATION_ID}

Solicitação

A solicitação a seguir realiza uma pesquisa (GET) para visualizar 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

O objeto de resposta mostra os detalhes do destino de projeção. O atributo id deve corresponder à ID do destino de projeção que foi 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
}

Atualizar um destino

Um destino existente pode ser atualizado fazendo uma solicitação PUT para o endpoint /config/destinations e incluindo a ID do destino a ser atualizado no caminho da solicitação. Essa operação basicamente está reescrevendo o destino, portanto, os mesmos atributos devem ser fornecidos no corpo da solicitação como são fornecidos ao criar um novo destino.

Formato da API

PUT /config/destinations/{DESTINATION_ID}

Solicitação

A solicitação a seguir atualiza o destino existente para incluir um segundo local (dataCenters).

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: {IMS_ORG}' \
  -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
      }'

Resposta

A resposta inclui os detalhes atualizados para o 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
}

Excluir um destino

Se sua organização não exigir mais um destino de projeção, ele poderá ser excluído fazendo uma solicitação DELETE ao endpoint /config/destinations e incluindo a ID do destino que você deseja excluir no caminho da solicitação.

Formato da API

DELETE /config/destinations/{DESTINATION_ID}

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: {IMS_ORG}' \
  -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. É possível confirmar que a exclusão foi bem-sucedida ao executar uma solicitação de pesquisa para o destino pela ID. A pesquisa deve retornar o status HTTP 404 (Não encontrado).

Configurações de projeção

As configurações de projeção fornecem informações sobre quais dados devem estar disponíveis em cada borda. Em vez de projetar um esquema Experience Data Model (XDM) completo na 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.

Listar todas as configurações de projeção

Você pode listar todas as configurações de projeção que foram criadas para sua organização, fazendo uma solicitação de GET para o endpoint /config/projections. Você também pode adicionar parâmetros opcionais ao caminho da solicitação para acessar configurações de projeção para um esquema específico ou pesquisar uma projeção individual pelo nome.

Formato da API

GET /config/projections
GET /config/projections?schemaName={SCHEMA_NAME}
GET /config/projections?schemaName={SCHEMA_NAME}&name={PROJECTION_NAME}

Solicitação

A solicitação a seguir lista todas as configurações de projeção associadas à classe de esquema Experience Data Model, XDM Individual Profile. Para obter mais informações sobre o XDM e sua função em Platform, comece lendo a 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna uma lista de configurações de projeção dentro do atributo _embedded raiz, contido na matriz projectionConfigs. Se nenhuma configuração de projeção tiver sido feita para sua organização, a matriz projectionConfigs 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"
            },
        ]
    }
}

Criar uma configuração de projeção

Você pode criar (POST) uma nova configuração de projeção que ditará quais campos XDM serão disponibilizados nas bordas.

Formato da API

POST /config/projections?schemaName={SCHEMA_NAME}

Solicitação

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: {IMS_ORG}' \
  -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"
      }'

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"
}

Seletores

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 valor do parâmetro selector é baseado vagamente na sintaxe XPath. A sintaxe suportada é resumida abaixo, com exemplos adicionais fornecidos para referência.

Sintaxe suportada

• Use vírgulas para selecionar vários campos. Não use espaços.
• Use a notação de pontos para selecionar campos aninhados.
  • Por exemplo, para selecionar um campo chamado field que está aninhado em um campo chamado foo, use o seletor foo.field.
• Ao incluir um campo que contenha subcampos, todos os subcampos também são projetados por padrão. No entanto, é possível filtrar os subcampos retornados usando parênteses "( )".
  • Por exemplo, addresses(type,city.country) retorna somente o tipo de endereço e o país em que a cidade do endereço está localizada para cada elemento de matriz addresses.
  • O exemplo acima é equivalente a addresses.type,addresses.city.country.

• Cada campo em um seletor é especificado em relação à raiz da resposta.
  • Se os dados forem uma coleção de recursos, a projeção incluirá uma matriz de recursos.
  • Se os dados forem um único recurso, a projeção incluirá campos relativos a esse recurso.
  • Se o campo selecionado for (ou fizer parte de) uma matriz, a projeção incluirá a parte selecionada de todos os elementos na matriz.

Exemplos do parâmetro do seletor

Os exemplos a seguir mostram os parâmetros de amostra selector, seguidos pelos valores estruturados que representam.

person.lastName

Retorna o subcampo lastName do objeto person no recurso solicitado.

{
  "person": {
    "lastName": "Smith"
  }
}

addresses

Retorna todos os elementos na matriz 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 o campo person.lastName e todos os elementos na matriz addresses.

{
  "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"
      }
    }
  ]
}

addresses(tipo, cidade)

Retorna apenas os valores dos campos type e city para cada elemento na matriz addresses. Todos os outros subcampos contidos em cada elemento addresses são filtrados.

{
  "addresses": [
    {
      "type": "home",
      "city": {
        "name": "San Jose",
        "country": "United States"
      }
    },
    {
      "type": "work",
      "city": {
        "name": "San Jose",
        "country": "United States"
      }
    }
  ]
}

Próximas etapas

Este guia mostrou as etapas envolvidas para configurar projeções e destinos, incluindo como formatar corretamente o parâmetro selector. Agora você pode criar novos destinos de projeção e configurações específicas às necessidades da sua organização.