Show Menu
TÓPICOS×

Crie destinos de marketing por email e ative dados na Plataforma de dados do cliente em tempo real da Adobe

Este tutorial demonstra como usar chamadas de API para se conectar aos dados da plataforma Adobe Experience, criar um destino de marketing por email, criar um fluxo de dados para o novo destino criado e ativar os dados para o novo destino criado.
Este tutorial usa o destino de Adobe Campaign em todos os exemplos, mas as etapas são idênticas para todos os destinos de marketing de email.
Se você preferir usar a interface do usuário no CDP em tempo real da Adobe para conectar um destino e ativar dados, consulte o Connect um destino e Ativar perfis e segmentos em tutoriais de destino .

Comece já

Este guia exige uma compreensão prática dos seguintes componentes da Adobe Experience Platform:
  • Sistema do Experience Data Model (XDM): A estrutura padronizada pela qual a plataforma Experience organiza os dados da experiência do cliente.
  • Serviço de catálogo: Catálogo é o sistema de registro para localização e linhagem de dados na Experience Platform.
  • Caixas de proteção : A plataforma Experience fornece caixas de proteção virtuais que particionam uma única instância da Plataforma em ambientes virtuais separados para ajudar a desenvolver e desenvolver aplicativos de experiência digital.
As seções a seguir fornecem informações adicionais que você precisará saber para ativar dados para destinos de marketing por email no Adobe Real-time CDP.

Reunir credenciais obrigatórias

Para concluir as etapas neste tutorial, você deve ter as seguintes credenciais prontas, dependendo do tipo de destinos aos quais você está conectando e ativando segmentos.
  • Para conexões do Amazon S3 com plataformas de marketing de email: accessId , secretKey
  • Para conexões SFTP com plataformas de marketing de email: domain , port , username``password ou ssh key (dependendo do método de conexão com o local FTP)

Lendo chamadas de exemplo da API

Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O JSON de amostra retornado em respostas de API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de amostra, consulte a seção sobre como ler chamadas de API de exemplo no guia de solução de problemas da plataforma Experience.

Coletar valores para cabeçalhos obrigatórios e opcionais

Para fazer chamadas para APIs de plataforma, você deve primeiro concluir o tutorial de autenticação. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas da API da plataforma da experiência, como mostrado abaixo:
  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Os recursos na plataforma Experience podem ser isolados para caixas de proteção virtuais específicas. Em solicitações para APIs de plataforma, você pode especificar o nome e a ID da caixa de proteção em que a operação ocorrerá. Esses são parâmetros opcionais.
  • x-sandbox-name: {SANDBOX_NAME}
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho de tipo de mídia adicional:
  • Tipo de conteúdo: application/json

Documentação do Swagger

Você pode encontrar a documentação de referência para todas as chamadas de API neste tutorial no Swagger. Consulte https://platform.adobe.io/data/foundation/flowservice/swagger#/. Recomendamos que você use este tutorial e a página de documentação do Swagger em paralelo.

Obtenha a lista dos destinos disponíveis

Como primeira etapa, você deve decidir para qual destino de marketing de email ativar os dados. Para começar, execute uma chamada para solicitar uma lista de destinos disponíveis aos quais você possa se conectar e ativar segmentos. Execute a seguinte solicitação GET ao connectionSpecs ponto de extremidade para retornar uma lista de destinos disponíveis:
Formato da API
GET /connectionSpecs

Solicitação
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Resposta
Uma resposta bem-sucedida contém uma lista de destinos disponíveis e seus identificadores exclusivos ( id ). Armazene o valor do destino que você planeja usar, pois ele será necessário em outras etapas. Por exemplo, se você deseja conectar e fornecer segmentos ao Adobe Campaign, procure o seguinte trecho na resposta:
{
    "id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
  "name": "Adobe Campaign",
  ...
  ...
}

Conecte-se aos dados da sua plataforma de experiência

Em seguida, você deve se conectar aos dados da plataforma da experiência para poder exportar dados do perfil e ativá-los no destino desejado. Este conjunto consiste em duas etapas descritas abaixo.
  1. Primeiro, você deve executar uma chamada para autorizar o acesso aos seus dados na Experience Platform, configurando uma conexão básica.
  2. Em seguida, usando a ID de conexão básica, você fará outra chamada na qual criará uma conexão de origem, que estabelece a conexão com os dados da plataforma de experiência.

Autorizar o acesso aos seus dados na plataforma Experience

Formato da API
POST /connections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME} \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão para o serviço de Perfil unificado - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
Resposta
Uma resposta bem-sucedida contém o identificador exclusivo ( id ) da conexão base. Armazene esse valor conforme necessário na próxima etapa para criar a conexão de origem.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Conecte-se aos dados da sua plataforma de experiência

Formato da API
POST /sourceConnections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Unified Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "CSV",
                "schema": null
            },
            "params" : {}
}'

  • {BASE_CONNECTION_ID} : Use a ID obtida na etapa anterior.
  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão para o serviço de Perfil unificado - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da conexão de origem recém-criada ao Serviço de Perfil Unificado. Isso confirma que você se conectou com êxito aos dados da plataforma de experiência. Armazene esse valor conforme necessário em uma etapa posterior.
{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Conectar-se ao destino de marketing de email

Nesta etapa, você está configurando uma conexão com seu destino de marketing de email desejado. Este conjunto consiste em duas etapas descritas abaixo.
  1. Primeiro, você deve executar uma chamada para autorizar o acesso ao provedor de serviço de email configurando uma conexão básica.
  2. Em seguida, usando a ID de conexão básica, você fará outra chamada na qual criará uma conexão de público alvo, que especifica o local em sua conta de armazenamento onde os dados exportados serão entregues, bem como o formato dos dados que serão exportados.

Autorizar acesso ao destino de marketing de email

Formato da API
POST /connections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "S3 Connection for Adobe Campaign",
    "description": "your company's holiday campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{S3 or SFTP}",
        "params": {
            "accessId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}"
        }
    }
}'

  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão obtida na etapa Obtenha a lista dos destinos disponíveis.
  • {S3 or SFTP} : preencha o tipo de conexão desejado para esse destino. No catálogo de destino, role até o destino desejado para ver se os tipos de conexão S3 e/ou SFTP são suportados.
  • {ACCESS_ID} : Sua ID de acesso para a localização do armazenamento Amazon S3.
  • {SECRET_KEY} : Sua chave secreta para a localização do armazenamento Amazon S3.
Resposta
Uma resposta bem-sucedida contém o identificador exclusivo ( id ) da conexão base. Armazene esse valor conforme necessário na próxima etapa para criar uma conexão de público alvo.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Especificar a localização do armazenamento e o formato dos dados

Formato da API
POST /targetConnections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Adobe Campaign",
    "description": "Connection to Adobe Campaign",
    "baseConnection": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKETNAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
}'

  • {BASE_CONNECTION_ID} : Use a ID de conexão básica obtida na etapa acima.
  • {CONNECTION_SPEC_ID} : Use as especificações de conexão obtidas na etapa Obtenha a lista dos destinos disponíveis.
  • {BUCKETNAME} : Seu bucket Amazon S3, onde o CDP em tempo real depositará a exportação de dados.
  • {FILEPATH} : O caminho no diretório bucket do Amazon S3 no qual o CDP em tempo real depositará a exportação de dados.
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da conexão de público alvo recém-criada para o destino de marketing por email. Armazene esse valor conforme necessário em etapas posteriores.
{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

Criar um fluxo de dados

Usando as IDs obtidas nas etapas anteriores, agora é possível criar um fluxo de dados entre os dados da plataforma da experiência e o destino para o qual você ativará os dados. Considere essa etapa como a construção do pipeline, pelo qual os dados fluirão posteriormente, entre a plataforma da experiência e o destino desejado.
Para criar um fluxo de dados, execute uma solicitação POST, como mostrado abaixo, enquanto fornece os valores mencionados abaixo dentro da carga.
Execute a seguinte solicitação POST para criar um fluxo de dados.
Formato da API
POST /flows

Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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/json' \
-d  '{
   
        "name": "Activate segments to Adobe Campaign",
        "description": "This operation creates a dataflow which we will later use to activate segments to Adobe Campaign",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ],
        "transformations": [
            {
                "name": "GeneralTransform",
                "params": {
                    "segmentSelectors": {
                        "selectors": []
                    },
                    "profileSelectors": {
                        "selectors": []
                    }
                }
            }
        ]
    }

  • {FLOW_SPEC_ID} : Use o fluxo para o destino de marketing de email ao qual você deseja se conectar. Para obter a especificação do fluxo, execute uma operação GET no flowspecs endpoint. Consulte a documentação do Swagger aqui: https://platform.adobe.io/data/foundation/flowservice/swagger#/Flow%20Specs%20API/getFlowSpecs. Na resposta, procure upsTo e copie a ID correspondente do destino de marketing de email ao qual você deseja se conectar. Por exemplo, para Adobe Campaign, procure upsToCampaign e copie o id parâmetro.
  • {SOURCE_CONNECTION_ID} : Use a ID de conexão de origem obtida na etapa Conectar-se à sua plataforma de experiência.
  • {TARGET_CONNECTION_ID} : Use a ID de conexão do público alvo obtida na etapa Conectar ao destino de marketing por email.
Resposta
Uma resposta bem-sucedida retorna a ID ( id ) do fluxo de dados recém-criado e um etag . Anote os dois valores. como você os fará na próxima etapa, para ativar segmentos.
{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

Ativar dados para o novo destino

Depois de criar todas as conexões e o fluxo de dados, agora você pode ativar seus dados de perfil na plataforma de marketing por email. Nessa etapa, você seleciona quais segmentos e quais atributos de perfil está enviando para o destino e pode agendar e enviar dados para o destino.
Para ativar segmentos no seu novo destino, é necessário executar uma operação PATCH JSON, semelhante ao exemplo abaixo. Você pode ativar vários segmentos e atributos de perfil em uma chamada. Para saber mais sobre o JSON PATCH, consulte a especificação rfc6902RFC.
Formato da API
PATCH /flows

Solicitação
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]

  • {DATAFLOW_ID} : Use o fluxo de dados obtido na etapa anterior.
  • {ETAG} : Use a tag obtida na etapa anterior.
  • {SEGMENT_ID} : Forneça a ID do segmento que deseja exportar para esse destino. Para recuperar IDs de segmento dos segmentos que você deseja ativar, acesse https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/ e procure a GET /segment/jobs operação.
  • {PROFILE_ATTRIBUTE} : Por exemplo, "person.lastName"
Resposta
Procure uma resposta 202 OK. Nenhum corpo de resposta é retornado. Para validar se a solicitação estava correta, consulte a próxima etapa, Validar o fluxo de dados.

Validar o fluxo de dados

Como etapa final do tutorial, você deve validar se os segmentos e os atributos do perfil foram corretamente mapeados para o fluxo de dados.
Para validar isso, execute a seguinte solicitação GET:
Formato da API
GET /flows

Solicitação
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"' 

  • {DATAFLOW_ID} : Use o fluxo de dados da etapa anterior.
  • {ETAG} : Use a tag da etapa anterior.
Resposta
A resposta retornada deve incluir no transformations parâmetro os segmentos e os atributos do perfil enviados na etapa anterior. Um exemplo de transformations parâmetro na resposta pode ser parecido com o seguinte:
"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                "selectors": []
            },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

Próximas etapas

Ao seguir este tutorial, você conectou com êxito o CDP em tempo real a um dos destinos de marketing de email de sua preferência e configurou um fluxo de dados para o respectivo destino. Os dados enviados agora podem ser usados no destino para campanhas de email, publicidade direcionada e muitos outros casos de uso. Consulte as seguintes páginas para obter mais detalhes: