O Serviço de fluxo é usado para coletar e centralizar dados do cliente de diferentes fontes no Adobe Experience Platform. O serviço fornece uma interface de usuário e uma RESTful API da qual todas as fontes compatíveis são conectáveis.
Este tutorial usa o Flow Service API para orientá-lo pelas etapas para criar uma conexão de transmissão usando o Flow Service API.
Este guia requer uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
Além disso, a criação de uma conexão de transmissão exige um esquema XDM de destino e um conjunto de dados. Para saber como criá-los, leia o tutorial em dados de registro de transmissão ou o tutorial em transmissão de dados da série de tempo.
Para obter informações sobre como fazer chamadas para APIs da plataforma com êxito, consulte o guia em introdução às APIs do Platform.
Uma conexão base especifica a fonte e contém as informações necessárias para tornar o fluxo compatível com as APIs de assimilação de streaming. Ao criar uma conexão base, você tem a opção de criar uma conexão não autenticada e autenticada.
As conexões não autenticadas são a conexão de transmissão padrão que pode ser criada quando você deseja transmitir dados na Plataforma.
Para criar uma conexão base não autenticada, faça uma solicitação de POST para a /connections
endpoint enquanto fornece um nome para a conexão, o tipo de dados e a ID da especificação da conexão da API HTTP. Esta ID é bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
Formato da API
POST /flowservice/connections
Solicitação
A solicitação a seguir cria uma conexão base para a API HTTP.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"dataType": "xdm"
}
}
}'
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection Raw Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"dataType": "raw"
}
}
}'
Propriedade | Descrição |
---|---|
name |
O nome da sua conexão básica. Certifique-se de que o nome seja descritivo, pois é possível usá-lo para pesquisar informações sobre a conexão básica. |
description |
(Opcional) Uma propriedade que pode ser incluída para fornecer mais informações sobre a conexão básica. |
connectionSpec.id |
A ID de especificação de conexão que corresponde à API HTTP. Esta ID é bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb . |
auth.params.dataType |
O tipo de dados para a conexão de transmissão. Os valores suportados incluem: xdm e raw . |
auth.params.name |
O nome da conexão de transmissão que deseja criar. |
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes da conexão recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
Propriedade | Descrição |
---|---|
id |
O id da sua conexão base recém-criada. |
etag |
Um identificador atribuído à conexão, especificando a versão da conexão base. |
As conexões autenticadas devem ser usadas quando for necessário diferenciar entre registros provenientes de fontes confiáveis e não confiáveis. Os usuários que desejam enviar informações com informações de identificação pessoal (PII) devem criar uma conexão autenticada ao transmitir informações para a plataforma.
Para criar uma conexão base autenticada, você deve incluir a variável authenticationRequired
na solicitação e especifique seu valor como true
. Durante essa etapa, também é possível fornecer uma ID de origem para a conexão de base autenticada. Esse parâmetro é opcional e usará o mesmo valor da variável name
, se não for fornecido.
Formato da API
POST /flowservice/connections
Solicitação
A solicitação a seguir cria uma conexão base autenticada para a API HTTP.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection XDM Data Authenticated",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Authenticated XDM streaming connection",
"dataType": "xdm",
"name": "Authenticated XDM streaming connection",
"authenticationRequired": true
}
}
}
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection Raw Data Authenticated",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Authenticated raw streaming connection",
"dataType": "raw",
"name": "Authenticated raw streaming connection",
"authenticationRequired": true
}
}
}
Propriedade | Descrição |
---|---|
auth.params.sourceId |
Um identificador adicional que pode ser usado ao criar uma conexão base autenticada. Esse parâmetro é opcional e usará o mesmo valor da variável name , se não for fornecido. |
auth.params.authenticationRequired |
O parâmetro que especifica a conexão de transmissão criada |
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes da conexão recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
Com a conexão básica criada, agora é possível recuperar o URL do terminal de transmissão.
Formato da API
GET /flowservice/connections/{BASE_CONNECTION_ID}
Parâmetro | Descrição |
---|---|
{BASE_CONNECTION_ID} |
O id valor da conexão criada anteriormente. |
Solicitação
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{BASE_CONNECTION_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com informações detalhadas sobre a conexão solicitada. O URL do endpoint de transmissão é criado automaticamente com a conexão e pode ser recuperado usando o inletUrl
valor.
{
"items": [
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"createdAt": 1669238699119,
"updatedAt": 1669238699119,
"createdBy": "acme@AdobeID",
"updatedBy": "acme@AdobeID",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "ACME Streaming Connection XDM Data",
"inletUrl": "https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"authenticationRequired": false,
"inletId": "667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"dataType": "xdm",
"name": "ACME Streaming Connection XDM Data"
}
},
"version": "\"f50185ed-0000-0200-0000-637e8fad0000\"",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
]
}
Para criar uma conexão de origem, faça uma solicitação de POST para a variável /sourceConnections
endpoint enquanto fornece a ID de conexão básica.
Formato da API
POST /flowservice/sourceConnections
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Source Connection for Customer Data",
"description": "A streaming source connection for ACME XDM Customer Data",
"baseConnectionId": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes da conexão de origem recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "34ece231-294d-416c-ad2a-5a5dfb2bc69f",
"etag": "\"d505125b-0000-0200-0000-637eb7790000\""
}
Para que os dados de origem sejam usados na Platform, um schema de target deve ser criado para estruturar os dados de origem de acordo com suas necessidades. O schema de destino é usado para criar um conjunto de dados da plataforma no qual os dados de origem estão contidos.
Um esquema XDM de destino pode ser criado executando-se uma solicitação de POST para a API do Registro de Schema.
Para obter etapas detalhadas sobre como criar um esquema XDM de destino, consulte o tutorial em criação de um schema usando a API.
Um conjunto de dados de destino pode ser criado executando uma solicitação de POST para a API do Serviço de catálogo, fornecendo a ID do schema do target no payload.
Para obter etapas detalhadas sobre como criar um conjunto de dados de destino, consulte o tutorial em criação de um conjunto de dados usando a API.
Uma conexão target representa a conexão com o destino onde os dados assimilados chegam. Para criar uma conexão do target, faça uma solicitação de POST para /targetConnections
ao fornecer IDs para o conjunto de dados de destino e o esquema XDM de destino. Durante essa etapa, você também deve fornecer a ID da especificação da conexão do lago de dados. Esta ID é c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Formato da API
POST /flowservice/targetConnections
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Target Connection",
"description": "ACME Streaming Target Connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "637eb7fadc8a211b6312b65b"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes da conexão de destino recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "07f2f6ff-1da5-4704-916a-c615b873cba9",
"etag": "\"340680f7-0000-0200-0000-637eb8730000\""
}
Para que os dados de origem sejam assimilados em um conjunto de dados de destino, eles devem primeiro ser mapeados para o schema de destino ao qual o conjunto de dados de destino adere.
Para criar um conjunto de mapeamento, faça uma solicitação de POST para a função mappingSets
endpoint da variável Data Prep API ao fornecer seu 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/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}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"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": "79a623960d3f4969835c9e00dc90c8df",
"version": 0,
"createdDate": 1669249214031,
"modifiedDate": 1669249214031,
"createdBy": "acme@AdobeID",
"modifiedBy": "acme@AdobeID"
}
Propriedade | Descrição |
---|
Com as conexões de origem e de destino criadas, agora é possível criar um fluxo de dados. O fluxo de dados é responsável por agendar e coletar dados de uma fonte. Você pode criar um fluxo de dados executando uma solicitação de POST para /flows
endpoint .
Formato da API
POST /flows
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Dataflow",
"description": "ACME streaming dataflow for customer data",
"flowSpec": {
"id": "d8a6f005-7eaf-4153-983e-e8574508b877",
"version": "1.0"
},
"sourceConnectionIds": [
"34ece231-294d-416c-ad2a-5a5dfb2bc69f"
],
"targetConnectionIds": [
"07f2f6ff-1da5-4704-916a-c615b873cba9"
]
}'
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "<name>",
"description": "<description>",
"flowSpec": {
"id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
"version": "1.0"
},
"sourceConnectionIds": [
"34ece231-294d-416c-ad2a-5a5dfb2bc69f"
],
"targetConnectionIds": [
"07f2f6ff-1da5-4704-916a-c615b873cba9"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "79a623960d3f4969835c9e00dc90c8df",
"mappingVersion": 0
}
}
]
}'
Propriedade | Descrição |
---|---|
name |
O nome do seu fluxo de dados. Certifique-se de que o nome do seu fluxo de dados seja descritivo, pois você pode usá-lo para pesquisar informações no seu fluxo de dados. |
description |
(Opcional) Uma propriedade que pode ser incluída para fornecer mais informações sobre o fluxo de dados. |
flowSpec.id |
A ID de especificação de fluxo para HTTP API. Para criar um fluxo de dados com transformações, você deve usar c1a19761-d2c7-4702-b9fa-fe91f0613e81 . Para criar um fluxo de dados sem transformações, use d8a6f005-7eaf-4153-983e-e8574508b877 . |
sourceConnectionIds |
O ID de conexão de origem recuperada em uma etapa anterior. |
targetConnectionIds |
O target connection ID recuperada em uma etapa anterior. |
transformations.params.mappingId |
O ID de mapeamento recuperada em uma etapa anterior. |
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes do fluxo de dados recém-criado, incluindo seu identificador exclusivo (id
).
{
"id": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"etag": "\"dc0459ae-0000-0200-0000-637ebaec0000\""
}
Depois de criar o fluxo, é possível enviar a mensagem JSON para o endpoint de transmissão criado anteriormente.
Formato da API
POST /collection/{INLET_URL}
Parâmetro | Descrição |
---|---|
{INLET_URL} |
O URL do terminal de transmissão. Você pode recuperar esse URL fazendo uma solicitação do GET para o /connections endpoint enquanto fornece a ID de conexão básica. |
Solicitação
curl -X POST https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2' \
-d '{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
},
"flowId": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"datasetId": "604a18a3bae67d18db6d258c"
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
}
},
"xdmEntity": {
"_id": "http-source-connector-acme-01",
"person": {
"name": {
"firstName": "suman",
"lastName": "nolan"
}
},
"workEmail": {
"primary": true,
"address": "suman@acme.com",
"type": "work",
"status": "active"
}
}
}
}'
curl -X POST https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: 1f086c23-2ea8-4d06-886c-232ea8bd061d' \
-d '{
"name": "Johnson Smith",
"location": {
"city": "Seattle",
"country": "United State of America",
"address": "3692 Main Street"
},
"gender": "Male",
"birthday": {
"year": 1984,
"month": 6,
"day": 9
}
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com detalhes das informações recém-assimiladas.
{
"inletId": "{BASE_CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507
}
Propriedade | Descrição |
---|---|
{BASE_CONNECTION_ID} |
A ID da conexão de transmissão criada anteriormente. |
xactionId |
Um identificador exclusivo gerou no lado do servidor para o registro que você acabou de enviar. Essa ID ajuda o Adobe a rastrear o ciclo de vida desse registro em vários sistemas e com a depuração. |
receivedTimeMs |
Um carimbo de data e hora (época em milissegundos) que mostra a hora em que a solicitação foi recebida. |
Ao seguir este tutorial, você criou uma conexão HTTP de transmissão, permitindo usar o endpoint de transmissão para assimilar dados na plataforma. Para obter instruções sobre como criar uma conexão de transmissão na interface do usuário, leia o tutorial de criação de uma conexão de transmissão.
Para saber como transmitir dados para a Platform, leia o tutorial em dados da série de tempo de transmissão ou o tutorial em dados de registro de transmissão.
Esta seção fornece informações complementares sobre como criar conexões de transmissão usando a API.
Se uma conexão de transmissão tiver a autenticação ativada, o cliente será solicitado a adicionar a variável Authorization
à solicitação.
Se a variável Authorization
não estiver presente ou um token de acesso inválido/expirado for enviado, uma resposta HTTP 401 Não autorizado será retornada, com uma resposta semelhante como abaixo:
Resposta
{
"type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
"status": "401",
"title": "Authorization",
"report": {
"message": "[id] Ims service token is empty"
}
}