Criar e testar um modelo de transformação de mensagem

Visão geral

Como parte do Destination SDK, o Adobe fornece ferramentas de desenvolvedor para ajudá-lo a configurar e testar seu destino. Esta página descreve como criar e testar um template de transformação de mensagem. Para obter informações sobre como testar seu destino, leia Testar a configuração de destino.

Para criar e testar um template de transformação de mensagem entre o schema de target no Adobe Experience Platform e o formato de mensagem compatível com seu destino, use o Ferramenta de criação de modelo mais adiante. Leia mais sobre a transformação de dados entre o schema de origem e de destino no documento de formato de mensagem.

A ilustração abaixo mostra como a criação e o teste de um modelo de transformação de mensagem se encaixa no fluxo de trabalho de configuração de destino no Destination SDK:

Por que você precisa criar e testar um template de transformação de mensagem

Uma das primeiras etapas ao criar seu destino no Destination SDK é pensar em como o formato de dados para associação de segmento, identidades e atributos de perfil é transformado quando exportado do Adobe Experience Platform para seu destino. Encontre informações sobre a transformação entre o esquema Adobe XDM e o esquema de destino no documento de formato de mensagem.

Para que a transformação seja bem-sucedida, é necessário fornecer um template de transformação, semelhante ao deste exemplo: Criar um modelo que envie segmentos, identidades e atributos de perfil.

O Adobe fornece uma ferramenta de modelo que permite criar e testar o modelo de mensagem que transforma dados do formato Adobe XDM no formato compatível com seu destino. A ferramenta tem dois pontos de extremidade de API que podem ser usados:

• Use o exemplo de API de modelo para obter um template de amostra.
• Use o API de modelo de renderização para renderizar o modelo de amostra, para que você possa comparar o resultado com o formato de dados esperado do seu destino. Depois de comparar os dados exportados com o formato de dados esperado pelo seu destino, você pode editar o modelo. Dessa forma, os dados exportados gerados correspondem ao formato de dados esperado pelo destino.

Etapas a serem concluídas antes de criar o modelo

Antes de estar pronto para criar o template, complete as etapas abaixo:

1. Criar uma configuração de servidor de destino. O modelo que você gerará será diferente, com base no valor fornecido para a variável maxUsersPerRequest parâmetro.
   • Use maxUsersPerRequest=1 se você quiser que uma chamada de API para seu destino inclua um único perfil, juntamente com suas qualificações de segmento, identidades e atributos de perfil.
   • Use maxUsersPerRequest com um valor maior que um se você quiser que uma chamada de API para seu destino inclua vários perfis, juntamente com suas qualificações de segmento, identidades e atributos de perfil.
2. Criar uma configuração de destino e adicione a ID da configuração do servidor de destino em destinationDelivery.destinationServerId.
3. Obter a ID da configuração de destino que você acabou de criar, para que possa usá-lo na ferramenta de criação de modelo.

Como usar a API de modelo de amostra e a API de modelo de renderização para criar um modelo para o seu destino

O processo para obter e testar o modelo é iterativo. Repita as etapas abaixo até que os perfis exportados correspondam ao formato de dados esperado do seu destino.

1. Primeiro, obter um modelo de amostra.
2. Use o modelo de amostra como ponto de partida para criar um rascunho próprio.
3. Chame o ponto de extremidade da API do modelo de renderização com seu próprio modelo. O Adobe gera perfis de amostra com base no esquema e retorna o resultado ou qualquer erro encontrado.
4. Compare os dados exportados com o formato de dados esperado pelo seu destino. Se necessário, edite o modelo .
5. Repita esse processo até que os perfis exportados correspondam ao formato de dados esperado do destino.

Obter um modelo de amostra usando a API do modelo de amostra

Adicione uma ID de destino à chamada, conforme mostrado abaixo, e a resposta retornará um exemplo de modelo correspondente à ID de destino.

curl --location --request GET 'https://platform.adobe.io/data/core/activation/authoring/testing/template/sample/5114d758-ce71-43ba-b53e-e2a91d67b67f' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: {API_KEY}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \

Se a ID de destino fornecida corresponder a uma configuração de destino com melhor agregação de esforço e maxUsersPerRequest=1 na política de agregação, a solicitação retorna um template de amostra semelhante a este:

{#- THIS is an example template for a single profile -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "identities": [
    {%- for idMapEntry in input.profile.identityMap -%}
    {%- set namespace = idMapEntry.key -%}
        {%- for identity in idMapEntry.value %}
        {
            "type": "{{ namespace }}",
            "id": "{{ identity.id }}"
        }{%- if not loop.last -%},{%- endif -%}
        {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
    {% endfor %}
    ],
    "AdobeExperiencePlatformSegments": {
        "add": [
        {%- for segment in input.profile.segmentMembership.ups | added %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ],
        "remove": [
        {#- Alternative syntax for filtering segments by status: -#}
        {% for segment in removedSegments(input.profile.segmentMembership.ups) %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ]
    }
}

Se a ID de destino fornecida corresponder a um modelo de servidor de destino com agregação configurável ou melhor agregação de esforço com maxUsersPerRequest maior que um, a solicitação retorna um template de amostra semelhante a este:

{#- THIS is an example template for multiple profiles -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "profiles": [
    {%- for profile in input.profiles %}
        {
            "identities": [
            {%- for idMapEntry in profile.identityMap -%}
            {%- set namespace = idMapEntry.key -%}
                {%- for identity in idMapEntry.value %}
                {
                    "type": "{{ namespace }}",
                    "id": "{{ identity.id }}"
                }{%- if not loop.last -%},{%- endif -%}
                {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
            {% endfor %}
            ],
            "AdobeExperiencePlatformSegments": {
                "add": [
                {%- for segment in profile.segmentMembership.ups | added %}
                    "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
                {% endfor %}
                ],
                "remove": [
                {#- Alternative syntax for filtering segments by status: -#}
                {% for segment in removedSegments(profile.segmentMembership.ups) %}
                    "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
                {% endfor %}
                ]
            }
        }{%- if not loop.last -%},{%- endif -%}
    {% endfor %}
    ]
}

Esqueça o modelo

Antes de usar o modelo para renderizar perfis que correspondam ao formato esperado do seu destino, você deve usar o caractere escape do modelo, como mostrado na gravação de tela abaixo.

Você pode usar uma ferramenta de escape de caracteres online. A demonstração acima usa o Formatador de escape JSON.

API do modelo de renderização

Depois de criar um template de transformação de mensagem usando o exemplo de API de modelo, você pode renderizar o modelo para gerar dados exportados com base neles. Isso permite verificar se os perfis que o Adobe Experience Platform exportaria para o seu destino correspondem ao formato esperado do seu destino.

Consulte a referência da API para obter exemplos de chamadas que você pode fazer:

• Renderizar um modelo sem perfis enviados no corpo
• Renderizar um modelo com perfis enviados no corpo

Edite o modelo e faça chamadas para o endpoint da API do modelo de renderização até que os perfis exportados correspondam ao formato de dados esperado do seu destino.

Adicionar seu modelo de escape de caractere à configuração do servidor de destino

Quando estiver satisfeito com seu template de transformação de mensagem, adicione-o a configuração do servidor de destino, em httpTemplate.requestBody.value.