Criar um fluxo de dados para assimilar dados de um CRM na Experience Platform
Leia este guia para saber como criar um fluxo de dados e assimilar dados na Adobe Experience Platform usando a Flow Service API.
Introdução
Este guia requer uma compreensão funcional dos seguintes componentes do Experience Platform:
- Assimilação em lote: descubra como você pode fazer upload de grandes volumes de dados em lotes de maneira rápida e eficiente.
- Serviço de catálogo: organize e acompanhe seus conjuntos de dados na Experience Platform.
- Preparo de dados: transforme e mapeie seus dados de entrada para corresponder aos requisitos do esquema.
- Fluxos de dados: configure e gerencie os pipelines que movem seus dados das fontes para os destinos.
- Esquemas do Experience Data Model (XDM): estruture seus dados usando esquemas XDM para que estejam prontos para uso no Experience Platform.
- Sandboxes: testar e desenvolver com segurança em ambientes isolados, sem afetar os dados de produção.
- Fontes: saiba como conectar suas fontes de dados externas à Experience Platform.
Uso de APIs do Experience Platform
Para obter informações sobre como fazer chamadas com êxito para APIs do Experience Platform, leia o manual sobre a introdução às APIs do Experience Platform.
Criar conexão básica base
Para criar um fluxo de dados para sua origem, você precisará de uma conta de origem totalmente autenticada e sua ID de conexão base correspondente. Se você não tiver essa ID, visite o catálogo de fontes para encontrar uma lista de fontes para as quais você pode criar uma conexão base.
Criar um esquema XDM de destino target-schema
Um esquema do Experience Data Model (XDM) fornece uma maneira padronizada para organizar e descrever os dados de experiência do cliente no Experience Platform. Para assimilar os dados de origem na Experience Platform, primeiro você deve criar um esquema XDM de destino que defina a estrutura e os tipos de dados que deseja assimilar. Esse esquema serve de blueprint para o conjunto de dados do Experience Platform em que seus dados assimilados residirão.
Um esquema XDM de destino pode ser criado executando uma solicitação POST para a API do Registro de Esquema. Para obter etapas detalhadas sobre como criar um esquema XDM de destino, leia os seguintes guias:
Depois de criado, o esquema XDM de destino $id
será necessário posteriormente para o conjunto de dados e o mapeamento de destino.
Criar um conjunto de dados de destino target-dataset
Um conjunto de dados é uma construção de armazenamento e gerenciamento para uma coleção de dados, normalmente estruturada como uma tabela com colunas (esquema) e linhas (campos). Os dados assimilados com sucesso na Experience Platform são armazenados no data lake como conjuntos de dados. Durante essa etapa, você pode criar um novo conjunto de dados ou usar um existente.
Você pode criar um conjunto de dados de destino fazendo uma solicitação POST para a API de Serviço de Catálogo e, ao mesmo tempo, fornecendo a ID do esquema de destino na carga. Para obter etapas detalhadas sobre como criar um conjunto de dados de destino, leia o manual sobre criação de um conjunto de dados usando a API.
Formato da API
code language-http |
---|
|
Solicitação
O exemplo a seguir mostra como criar um conjunto de dados de destino que esteja ativado para assimilação de Perfil do cliente em tempo real. Nesta solicitação, a propriedade unifiedProfile
está definida como true
(no objeto tags
), o que instrui a Experience Platform a incluir o conjunto de dados no Perfil de Cliente em Tempo Real.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propriedade | Descrição |
name |
Um nome descritivo para o conjunto de dados de destino. Use um nome claro e exclusivo para facilitar a identificação e o gerenciamento do conjunto de dados em operações futuras. |
schemaRef.id |
A ID do esquema XDM do público-alvo. |
tags.unifiedProfile |
Um valor booleano que informa à Experience Platform se os dados devem ser assimilados no Perfil do cliente em tempo real. |
Resposta
Uma resposta bem-sucedida retorna a ID do conjunto de dados de destino. Essa ID é necessária posteriormente para criar uma conexão de destino.
code language-json |
---|
|
Criar uma conexão de origem source
Uma conexão de origem define como os dados são trazidos para a Experience Platform a partir de uma origem externa. Ele especifica o sistema de origem e o formato dos dados recebidos e faz referência a uma conexão base que contém detalhes de autenticação. Cada conexão de origem é exclusiva de sua organização.
- Para fontes baseadas em arquivos (como armazenamentos em nuvem), uma conexão de origem pode incluir configurações como delimitador de coluna, tipo de codificação, tipo de compactação, expressões regulares para seleção de arquivos e se os arquivos devem ser assimilados recursivamente.
- Para fontes baseadas em tabela (como bancos de dados, CRMs e provedores de automação de marketing), uma conexão de origem pode especificar detalhes como o nome da tabela e os mapeamentos de coluna.
Para criar uma conexão de origem, faça uma solicitação POST para o ponto de extremidade /sourceConnections
da API Flow Service e forneça a ID da conexão base, a ID da especificação da conexão e o caminho para o arquivo de dados de origem.
Formato da API
POST /sourceConnections
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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/json' \
-d '{
"name": "ACME source connection",
"description": "A source connection for ACME contact data",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Contact",
"columns": [
{
"name": "TestID",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Datefield",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
name
description
baseConnectionId
id
da sua conexão base. Você pode recuperar essa ID autenticando sua origem no Experience Platform usando a API Flow Service.data.format
tabular
para fontes baseadas em tabela (como bancos de dados, CRMs e provedores de automação de marketing).params.tableName
params.columns
connectionSpec.id
Resposta
Uma resposta bem-sucedida retorna a ID da conexão de origem. Essa ID é necessária para criar um fluxo de dados e assimilar seus dados.
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
Criar uma conexão de destino target
Uma conexão de destino representa a conexão com o destino onde os dados assimilados chegam. Para criar uma conexão de destino, você deve fornecer a ID de especificação da conexão fixa associada ao data lake. Esta ID de especificação de conexão é: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Formato da API
POST /targetConnections
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-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/json' \
-d '{
"name": "ACME target connection",
"description": "ACME target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6889f4f89b982b2b90bc1207"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
name
description
data.schema.id
params.dataSetId
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.Mapeamento mapping
Em seguida, mapeie os dados de origem para o esquema de destino ao qual o conjunto de dados de destino adere. Para criar um mapeamento, faça uma solicitação POST para o ponto de extremidade mappingSets
da Data Prep API. Inclua a ID do esquema XDM do público-alvo e os detalhes dos conjuntos de mapeamento que deseja criar.
Formato da API
POST /mappingSets
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-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/json' \
-d '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "TestID",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.birthDate",
"sourceAttribute": "Datefield",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema
$id
do esquema XDM de destino.Resposta
Uma resposta bem-sucedida retorna detalhes do mapeamento recém-criado, incluindo seu identificador exclusivo (id
). Essa ID é necessária em uma etapa posterior para criar um fluxo de dados.
{
"id": "93ddfa69c4864d978832b1e5ef6ec3b9",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Recuperar especificações de fluxo de dados flow-specs
Antes de criar um fluxo de dados, primeiro recupere as especificações do fluxo de dados que correspondem à origem. Para recuperar essas informações, faça uma solicitação do GET para o ponto de extremidade /flowSpecs
da API Flow Service.
Formato da API
GET /flowSpecs?property=name=="{NAME}"
property=name=="{NAME}"
O nome da especificação do fluxo de dados.
- Para fontes baseadas em arquivo (como armazenamento na nuvem), defina esse valor como
CloudStorageToAEP
. - Para fontes baseadas em tabela (como bancos de dados, CRMs e provedores de automação de marketing), defina esse valor como
CRMToAEP
.
Solicitação
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
-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 os detalhes da especificação do fluxo de dados responsáveis por trazer os dados de sua origem para a Experience Platform. A resposta inclui a especificação de fluxo exclusiva id
necessária para criar um novo fluxo de dados.
Para garantir que você esteja usando a especificação de fluxo de dados correta, verifique a matriz items.sourceConnectionSpecIds
na resposta. Confirme se a ID de especificação de conexão da sua origem está incluída nesta lista.
code language-json |
---|
|
Criar um fluxo de dados dataflow
Um fluxo de dados é um pipeline configurado que transfere dados entre os serviços da Experience Platform. Ele define como os dados são assimilados de fontes externas (como bancos de dados, armazenamento em nuvem ou APIs), processados e roteados para conjuntos de dados de destino. Esses conjuntos de dados são usados por serviços como o Serviço de identidade, Perfil do cliente em tempo real e Destinos para ativação e análise.
Para criar um fluxo de dados, será necessário fornecer valores para os seguintes itens:
Durante essa etapa, você pode usar os seguintes parâmetros no scheduleParams
para configurar um agendamento de assimilação para seu fluxo de dados:
startTime
frequency
A frequência da ingestão. Configure a frequência para indicar a frequência de execução do fluxo de dados. Você pode definir a frequência como:
once
: Defina sua frequência comoonce
para criar uma assimilação única. As configurações de intervalo e preenchimento retroativo não estão disponíveis para trabalhos de assimilação únicos. Por padrão, a frequência de agendamento é definida como uma vez.minute
: Defina sua frequência comominute
para agendar seu fluxo de dados para assimilar dados por minuto.hour
: Defina sua frequência comohour
para agendar seu fluxo de dados para assimilar dados por hora.day
: Defina sua frequência comoday
para agendar seu fluxo de dados para assimilar dados por dia.week
: Defina sua frequência comoweek
para agendar seu fluxo de dados para assimilar dados por semana.
interval
O intervalo entre as assimilações consecutivas (necessário para todas as frequências, exceto once
). Defina a configuração de intervalo para estabelecer o intervalo de tempo entre cada assimilação. Por exemplo, se sua frequência estiver definida como dia e o intervalo for 15, o fluxo de dados será executado a cada 15 dias. Você não pode definir o intervalo como zero. O valor mínimo de intervalo aceito para cada frequência é o seguinte:
once
: n/dminute
: 15hour
: 1day
: 1week
: 1
backfill
startTime
.Formato da API
POST /flows
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "ACME Contact Dataflow",
"description": "A dataflow for ACME contact data",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"b7581b59-c603-4df1-a689-d23d7ac440f3"
],
"targetConnectionIds": [
"320f119a-5ac1-4ab1-88ea-eb19e674ea2e"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "Datefield",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "93ddfa69c4864d978832b1e5ef6ec3b9",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1612310466",
"frequency":"minute",
"interval":"15",
"backfill": "true"
}
}'
name
description
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations.params.deltaColum
deltaColumn
é yyyy-MM-dd HH:mm:ss
. Para Microsoft Dynamics, o formato com suporte para deltaColumn
é yyyy-MM-ddTHH:mm:ssZ
.transformations.params.deltaColumn.dateFormat
transformations.params.deltaColumn.timeZone
transformations.params.mappingId
scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
ou week
.scheduleParams.interval
scheduleParams.backfill
true
ou false
) que determina se os dados históricos devem ser assimilados (preenchimento retroativo) quando o fluxo de dados é criado pela primeira vez.Resposta
Uma resposta bem-sucedida retorna a ID (id
) do fluxo de dados recém-criado.
{
"id": "ae0a9777-b322-4ac1-b0ed-48ae9e497c7e",
"etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}
Use a interface do para validar o fluxo de trabalho da API validate-in-ui
É possível usar a interface do usuário do Experience Platform para validar a criação do fluxo de dados. Navegue até o catálogo Fontes na interface do usuário do Experience Platform e selecione Fluxos de Dados nas guias do cabeçalho. Em seguida, use a coluna Nome do Fluxo de Dados e localize o fluxo de dados criado usando a API Flow Service.
Você pode validar ainda mais seu fluxo de dados por meio da interface Atividade de fluxo de dados. Use o painel direito para exibir as informações de uso da API do seu fluxo de dados. Esta seção exibe a mesma ID de fluxo de dados, ID de conjunto de dados e ID de mapeamento que foi gerada durante o processo de criação do fluxo de dados em Flow Service.
Próximas etapas
Este tutorial guiou você pelo processo de criação de um fluxo de dados no Experience Platform usando a API Flow Service. Você aprendeu a criar e configurar os componentes necessários, incluindo o esquema XDM do destino, o conjunto de dados, a conexão de origem, a conexão de destino e o próprio fluxo de dados. Seguindo essas etapas, é possível automatizar a assimilação de dados de fontes externas na Experience Platform, permitindo que serviços downstream, como Perfil do cliente em tempo real e Destinos, aproveitem os dados assimilados para casos de uso avançados.
Monitorar seu fluxo de dados
Depois que o fluxo de dados é criado, é possível monitorar o desempenho diretamente na interface do Experience Platform. Isso inclui o rastreamento das taxas de assimilação, as métricas de sucesso e quaisquer erros que ocorram. Para obter mais informações sobre como monitorar o fluxo de dados, visite o tutorial em monitoramento de contas e fluxos de dados.
Atualizar seu fluxo de dados
Para atualizar as configurações do agendamento de fluxos de dados, mapeamento ou informações gerais, visite o tutorial em atualizando fluxos de dados de fontes.
Excluir seu fluxo de dados
Você pode excluir fluxos de dados que não são mais necessários ou que foram criados incorretamente usando a função Excluir disponível no espaço de trabalho Fluxos de Dados. Para obter mais informações sobre como excluir fluxos de dados, visite o tutorial em excluindo fluxos de dados.