Este tutorial aborda as etapas para recuperar dados de um armazenamento em nuvem de terceiros e trazê-los para a Plataforma por meio dos conectores de origem e da Flow Service API.
Este tutorial requer que você tenha acesso a um armazenamento em nuvem de terceiros por meio de uma conexão válida e informações sobre o arquivo que deseja trazer para a Plataforma, incluindo o caminho e a estrutura do arquivo. Se você não tiver essas informações, consulte o tutorial em explorar um armazenamento em nuvem de terceiros usando a Flow Service API antes de tentar este tutorial.
Este tutorial também exige que você tenha uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
{TENANT_ID}
, o conceito de "container" e os cabeçalhos necessários para fazer solicitações (com atenção especial ao cabeçalho Accept e seus possíveis valores).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 em como ler chamadas de API de exemplo no guia de solução de problemas do Experience Platform.
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 de API de Experience Platform, como mostrado abaixo:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}
Todos os recursos no Experience Platform, incluindo os pertencentes a Flow Service, são isolados para caixas de proteção virtuais específicas. Todas as solicitações para APIs de plataforma exigem um cabeçalho que especifique o nome da caixa de proteção em que a operação ocorrerá:
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:
Content-Type: application/json
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 enum para o atributo de formato de dados.
Use os seguintes valores enum para conectores baseados em arquivo:
Formato dos dados | Valor Enum |
---|---|
Delimitado | delimited |
JSON | json |
Parquet | parquet |
Para todos os conectores baseados em tabela, defina o valor como tabular
.
É possível assimilar arquivos CSV e TSV com um conector de origem de armazenamento na nuvem especificando um delimitador de coluna como uma propriedade. Qualquer valor de caractere único é um delimitador de coluna permitido. Se não fornecido, uma vírgula (,)
é usada como valor padrão.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Cloud storage source connector",
"connectionId": "9e2541a0-b143-4d23-a541-a0b143dd2301",
"description": "Cloud storage source connector",
"data": {
"format": "delimited",
"columnDelimiter": "\t"
},
"params": {
"path": "/ingestion-demos/leads/tsv_data/*.tsv",
"recursive": "true"
},
"connectionSpec": {
"id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
"version": "1.0"
}
}'
Propriedade | Descrição |
---|---|
connectionId |
A ID exclusiva de conexão do sistema de armazenamento em nuvem de terceiros que você está acessando. |
data.format |
Um valor enum que define o atributo de formato de dados. |
data.columnDelimiter |
Você pode usar qualquer delimitador de coluna de caractere único para coletar arquivos simples. Essa propriedade só é necessária ao assimilar arquivos CSV ou TSV. |
params.path |
O caminho do arquivo de origem que você está acessando. |
connectionSpec.id |
A ID de especificação de conexão associada ao sistema de armazenamento em nuvem de terceiros específico. Consulte o apêndice para obter uma lista de IDs de especificações de conexão. |
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo (id
) da conexão de origem recém-criada. Essa ID é necessária em uma etapa posterior para criar um fluxo de dados.
{
"id": "26b53912-1005-49f0-b539-12100559f0e2",
"etag": "\"11004d97-0000-0200-0000-5f3c3b140000\""
}
Para que os dados de origem sejam usados na Plataforma, um schema de público alvo deve ser criado para estruturar os dados de origem de acordo com suas necessidades. O schema do público alvo é então usado para criar um conjunto de dados da Plataforma no qual os dados de origem estão contidos.
Um schema XDM de público alvo pode ser criado executando-se uma solicitação POST para a API do Registro de Schemas.
Formato da API
POST /schemaregistry/tenant/schemas
Solicitação
A solicitação de exemplo a seguir cria um schema XDM que estende a classe de Perfil Individual XDM.
curl -X POST \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
-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 '{
"type": "object",
"title": "Target schema for a Cloud Storage connector",
"description": "Target schema for a Cloud Storage connector",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:containerId": "tenant",
"meta:resourceType": "schemas",
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/profile"
}'
Resposta
Uma resposta bem-sucedida retorna detalhes do schema recém-criado, incluindo seu identificador exclusivo ($id
). Essa ID é necessária em etapas posteriores para criar um conjunto de dados de público alvo, mapeamento e fluxo de dados.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"meta:altId": "_{TENANT_ID}.schemas.995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"meta:resourceType": "schemas",
"version": "1.0",
"title": "Target schema cloud storage",
"type": "object",
"description": "Target schema for cloud storage",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
"type": "object",
"meta:xdmType": "object"
}
],
"refs": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/context/profile"
],
"imsOrg": "{IMS_ORG}",
"meta:extensible": false,
"meta:abstract": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1597783248870,
"repo:lastModifiedDate": 1597783248870,
"xdm:createdClientId": "{CREATED_CLIENT_ID}",
"xdm:lastModifiedClientId": "{LAST_MODIFIED_CLIENT_ID}",
"xdm:createdUserId": "{CREATED_USER_ID}",
"xdm:lastModifiedUserId": "{LAST_MODIFIED_USER_ID}",
"eTag": "596661ec6c7a9c6ae530676e98290a4a58ca29540ed92489cf4478b2bf013a65",
"meta:globalLibVersion": "1.13.3"
},
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:containerId": "tenant",
"meta:tenantNamespace": "{TENANT_ID}"
}
Um conjunto de dados de público alvo pode ser criado executando-se uma solicitação POST para a API do serviço de catálogo, fornecendo a ID do schema de público alvo dentro da carga.
Formato da API
POST /catalog/dataSets
Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
-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": "Target dataset for cloud storage",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
}
}'
Propriedade | Descrição |
---|---|
schemaRef.id |
A ID do schema XDM do público alvo. |
Resposta
Uma resposta bem-sucedida retorna uma matriz que contém a ID do conjunto de dados recém-criado no formato "@/datasets/{DATASET_ID}"
. A ID do conjunto de dados é uma sequência de caracteres somente leitura, gerada pelo sistema, usada para fazer referência ao conjunto de dados em chamadas de API. A ID do conjunto de dados do público alvo é necessária em etapas posteriores para criar uma conexão de público alvo e um fluxo de dados.
[
"@/dataSets/5f3c3cedb2805c194ff0b69a"
]
Uma conexão de público alvo representa a conexão com o destino onde os dados ingeridos chegam. Para criar uma conexão de público alvo, é necessário fornecer a ID de especificação de 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 de um schema de público alvo de um conjunto de dados de público alvo e a ID de especificação de conexão para o Data Lake. Usando esses identificadores, você pode criar uma conexão de público alvo usando a API Flow Service para especificar 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Target Connection for a Cloud Storage connector",
"description": "Target Connection for a Cloud Storage connector",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "5f3c3cedb2805c194ff0b69a"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Propriedade | Descrição |
---|---|
data.schema.id |
O $id do schema XDM do público alvo. |
params.dataSetId |
A ID do conjunto de dados do público alvo. |
connectionSpec.id |
A ID de especificação de conexão fixa para o Data Lake. Esta ID é: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo da nova conexão de público alvo (id
). Essa ID é necessária em etapas posteriores.
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
Para que os dados de origem sejam ingeridos em um conjunto de dados de público alvo, eles devem primeiro ser mapeados para o schema de público alvo ao qual o conjunto de dados de público alvo adere. Isso é feito executando uma solicitação POST para o Serviço de conversão com mapeamentos de dados definidos na carga da solicitação.
Formato da API
POST /conversion/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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "FirstName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "LastName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
Propriedade | Descrição |
---|---|
xdmSchema |
A ID do schema XDM do público alvo. |
Resposta
Uma resposta bem-sucedida retorna detalhes do mapeamento recém-criado, incluindo seu identificador exclusivo (id
). Esse valor é necessário em uma etapa posterior para criar um fluxo de dados.
{
"id": "bf5286a9c1ad4266baca76ba3adc9366",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Um dataflow é responsável por coletar dados de fontes e trazê-los para a Plataforma. Para criar um fluxo de dados, primeiro você deve obter as especificações de fluxo de dados responsáveis pela coleta de dados de armazenamentos em nuvem.
Formato da API
GET /flowSpecs?property=name=="CloudStorageToAEP"
Solicitação
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CloudStorageToAEP%22' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
Uma resposta bem-sucedida retorna os detalhes da especificação de fluxo de dados responsável por trazer os dados da sua fonte para a Plataforma. A resposta inclui a especificação de fluxo exclusiva id
necessária para criar um novo fluxo de dados.
{
"items": [
{
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"name": "CloudStorageToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"sourceConnectionSpecIds": [
"b3ba5556-48be-44b7-8b85-ff2b69b46dc4",
"ecadc60c-7455-4d87-84dc-2a0e293d997b",
"b7829c2f-2eb0-4f49-a6ee-55e33008b629",
"4c10e202-c428-4796-9208-5f1f5732b1cf",
"fb2e94c9-c031-467d-8103-6bd6e0a432f2",
"32e8f412-cdf7-464c-9885-78184cb113fd",
"b7bf2577-4520-42c9-bae9-cad01560f7bc",
"998b8ae3-cec0-43b7-8abe-40b1eb4ee069",
"be5ec48c-5b78-49d5-b8fa-7c89ec4569b8"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"transformationSpecs": [
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from source to target",
"properties": {
"mappingId": {
"type": "string"
},
"mappingVersion": {
"type": "string"
}
}
}
}
],
"scheduleSpec": {
"name": "PeriodicSchedule",
"type": "Periodic",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"startTime": {
"description": "epoch time",
"type": "integer"
},
"endTime": {
"description": "epoch time",
"type": "integer"
},
"interval": {
"type": "integer"
},
"frequency": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week"
]
},
"backfill": {
"type": "boolean",
"default": true
}
},
"required": [
"startTime",
"frequency",
"interval"
],
"if": {
"properties": {
"frequency": {
"const": "minute"
}
}
},
"then": {
"properties": {
"interval": {
"minimum": 15
}
}
},
"else": {
"properties": {
"interval": {
"minimum": 1
}
}
}
}
},
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
]
}
}
]
}
A última etapa para coletar dados de armazenamento em nuvem é criar um fluxo de dados. Agora, você tem os seguintes valores obrigatórios preparados:
Um fluxo de dados é responsável por programar e coletar dados de uma fonte. Você pode criar um fluxo de dados executando uma solicitação de POST ao fornecer os valores mencionados anteriormente dentro da carga.
Para agendar uma ingestão, é necessário primeiro definir o valor de tempo do start para cada tempo em segundos. Em seguida, você deve definir o valor de frequência para uma das cinco opções: once
, minute
, hour
, day
ou week
. O valor do intervalo designa o período entre duas ingestões consecutivas e a criação de uma ingestão única não requer a definição de um intervalo. Para todas as outras frequências, o valor do intervalo deve ser definido como igual ou maior que 15
.
É altamente recomendável agendar seu fluxo de dados para ingestão única ao usar o conector FTP.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Cloud Storage flow to Platform",
"description": "Cloud Storage flow to Platform",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"26b53912-1005-49f0-b539-12100559f0e2"
],
"targetConnectionIds": [
"f7eb08fa-5f04-4e45-ab08-fa5f046e45ee"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1597784298",
"frequency":"minute",
"interval":"30"
}
}'
Propriedade | Descrição |
---|---|
flowSpec.id |
A ID de especificação de fluxo recuperada na etapa anterior. |
sourceConnectionIds |
A ID de conexão de origem recuperada em uma etapa anterior. |
targetConnectionIds |
A ID de conexão do público alvo recuperada em uma etapa anterior. |
transformations.params.mappingId |
A ID de mapeamento recuperada numa etapa anterior. |
scheduleParams.startTime |
A hora de start do fluxo de dados em cada época. |
scheduleParams.frequency |
A frequência com que o fluxo de dados coletará dados. Os valores aceitáveis incluem: once , minute , hour , day ou week . |
scheduleParams.interval |
O intervalo designa o período entre duas execuções consecutivas de fluxo. O valor do intervalo deve ser um número inteiro diferente de zero. O intervalo não é necessário quando a frequência é definida como once e deve ser maior ou igual a 15 para outros valores de frequência. |
Resposta
Uma resposta bem-sucedida retorna a ID (id
) do fluxo de dados recém-criado.
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
Depois que seu fluxo de dados for criado, você poderá monitorar os dados que estão sendo assimilados por ele para ver informações sobre execuções de fluxo, status de conclusão e erros. Para obter mais informações sobre como monitorar fluxos de dados, consulte o tutorial em monitoramento de fluxos de dados na API
Ao seguir este tutorial, você criou um conector de origem para coletar dados do seu armazenamento em nuvem de forma programada. Os dados recebidos agora podem ser usados por serviços de plataforma downstream, como Real-time Customer Profile e Data Science Workspace. Consulte os seguintes documentos para obter mais detalhes:
A seção a seguir lista os diferentes conectores de origem do armazenamento de nuvem e suas especificações de conexões.
Nome do conector | Especificação da conexão |
---|---|
Amazon S3 (S3) | ecadc60c-7455-4d87-84dc-2a0e293d997b |
Amazon Kinesis (Kinesis) | 86043421-563b-46ec-8e6c-e23184711bf6 |
Azure Blob (Blob) | 4c10e202-c428-4796-9208-5f1f5732b1cf |
Azure Data Lake Storage Gen2 (ADLS Gen2) | 0ed90a81-07f4-4586-8190-b40eccef1c5a |
Azure Event Hubs (Hubs de Evento) | bf9f5905-92b7-48bf-bf20-455bc6b60a4e |
Azure File Storage | be5ec48c-5b78-49d5-b8fa-7c89ec4569b8 |
Google Cloud Storage | 32e8f412-cdf7-464c-9885-78184cb113fd |
HDFS | 54e221aa-d342-4707-bcff-7a4bceef0001 |
SFTP | bf367b0d-3d9b-4060-b67b-0d3d9bd06094 |