Criar um fluxo de dados para fontes de banco de dados usando a API Flow Service
Este tutorial aborda as etapas para recuperar dados de uma fonte de banco de dados e trazê-los para a Experience Platform usando a Flow Service API.
OBSERVAÇÃO- Para criar um fluxo de dados, você já deve ter uma ID de conexão base válida com uma origem de banco de dados. Se você não tiver essa ID, consulte a visão geral das fontes para obter uma lista de fontes de banco de dados com as quais você pode criar uma conexão base.
- Para que o Experience Platform assimile dados, os fusos horários de todas as fontes de lote baseadas em tabela devem ser configurados como UTC. O único carimbo de data/hora com suporte para Snowflake origem é TIMESTAMP_NTZ com hora UTC.
Introdução
Este tutorial requer que você tenha uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
-
Experience Data Model (XDM) System: a estrutura padronizada pela qual o Experience Platform organiza os dados de experiência do cliente.
- Noções básicas sobre a composição de esquema: saiba mais sobre os blocos de construção básicos de esquemas XDM, incluindo princípios-chave e práticas recomendadas na composição de esquema.
- Guia do desenvolvedor do Registro de Esquema: inclui informações importantes que você precisa saber para executar com êxito chamadas para a API do Registro de Esquema. Isso inclui o
{TENANT_ID}, o conceito de "contêineres" e os cabeçalhos necessários para fazer solicitações (com atenção especial ao cabeçalho Aceitar e seus valores possíveis).
-
Catalog Service: Catálogo é o sistema de registro para localização e linhagem de dados no Experience Platform.
-
Batch ingestion: a API de assimilação em lote permite assimilar dados na Experience Platform como arquivos em lote.
-
Sandboxes: a Experience Platform fornece sandboxes virtuais que particionam uma única instância do Experience Platform em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.
Uso de APIs do Experience Platform
Para obter informações sobre como fazer chamadas para APIs do Experience Platform com êxito, consulte o manual sobre introdução às APIs do Experience Platform.
Criar uma conexão de origem
Você pode criar uma conexão de origem fazendo uma solicitação POST para a API Flow Service. Uma conexão de origem consiste em uma ID de conexão, um caminho para o arquivo de dados de origem e uma ID de especificação de conexão.
Para criar uma conexão de origem, você também deve definir um valor de enumeração para o atributo de formato de dados.
Use os seguintes valores de enumeração para conectores baseados em arquivo:
| Formato dos dados | Valor de enumeração |
|---|---|
| Delimitado | delimited |
| JSON | json |
| Parquet | parquet |
Para todos os conectores baseados em tabela, defina o valor como tabular.
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": "Database source connection",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"description": "Database source connection",
"data": {
"format": "tabular"
},
"params": {
"tableName": "test1.Mytable",
"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"
}
}
],
"cdcEnabled": true
},
"connectionSpec": {
"id": "3c9b37f8-13a6-43d8-bad3-b863b941fedd",
"version": "1.0"
}
}'
| Propriedade | Descrição |
|---|---|
baseConnectionId | A ID de conexão da origem do banco de dados. |
params.tableName | O caminho do arquivo de origem. |
params.cdcEnabled |
Um valor booleano que indica se a captura do histórico de alterações está ativada ou não. Esta propriedade é suportada pelas seguintes fontes de banco de dados:
Para obter mais informações, leia o manual sobre como usar a captura de dados de alteração nas fontes. |
connectionSpec.id | A ID da especificação de conexão da origem do banco de dados. Consulte o Apêndice para obter uma lista de IDs de especificação do banco de dados. |
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo (id) da conexão de origem recém-criada. Essa ID é necessária nas etapas posteriores para criar uma conexão de destino.
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
Criar um esquema XDM de destino
Para que os dados de origem sejam usados no Experience Platform, um esquema de destino deve ser criado para estruturar os dados de origem de acordo com suas necessidades. O esquema de destino é usado para criar um conjunto de dados do Experience Platform no qual os dados de origem estão contidos.
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, consulte o tutorial sobre criação de um esquema usando a API.
Criar um conjunto de dados de destino
Um conjunto de dados de destino pode ser criado executando uma solicitação POST para a API de Serviço de Catálogo, fornecendo a ID do esquema de destino na carga.
Para obter etapas detalhadas sobre como criar um conjunto de dados de destino, consulte o tutorial sobre criação de um conjunto de dados usando a API.
Criar uma conexão de destino
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.
Agora você tem os identificadores exclusivos, um esquema de destino, um conjunto de dados de destino e a ID de especificação da conexão para o data lake. Usando a API Flow Service, você pode criar uma conexão de destino especificando esses identificadores junto com o conjunto de dados que conterá os dados de origem de entrada.
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": "Database target connection",
"description": "Database target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6019e0e7c5dcf718db5ebc71"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
| Propriedade | Descrição |
|---|---|
data.schema.id | O $id do esquema XDM de destino. |
data.schema.version | A versão do esquema. Este valor deve ser definido como application/vnd.adobe.xed-full+json;version=1, que retorna a versão secundária mais recente do esquema. |
params.dataSetId | A ID do conjunto de dados de destino gerado na etapa anterior. Observação: você deve fornecer uma ID de conjunto de dados válida ao criar uma conexão de destino. Uma ID de conjunto de dados inválida resultará em um erro. |
connectionSpec.id | A ID da especificação de conexão usada para conectar ao data lake. Esta ID é: c604ff05-7f1a-43c0-8e18-33bf874cb11c. |
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo (id) da nova conexão de destino. Esse valor é necessário em uma etapa posterior para criar um fluxo de dados.
{
"id": "320f119a-5ac1-4ab1-88ea-eb19e674ea2e",
"etag": "\"c0038936-0000-0200-0000-6019e1190000\""
}
Criar um mapeamento
Para que os dados de origem sejam assimilados em um conjunto de dados de destino, eles devem primeiro ser mapeados para o esquema de destino ao qual o conjunto de dados de destino adere.
Para criar um conjunto de mapeamento, faça uma solicitação POST para o ponto de extremidade mappingSets da Data Prep API enquanto fornece o esquema XDM de destino $id 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
}
]
}'
| Propriedade | Descrição |
|---|---|
xdmSchema | O $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": "0b090130b58b4819afc78b6dc98b484d",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}