Documentação Experience Platform Guia dos conectores de origem

Criar uma conexão YOURSOURCE usando a API Flow Service

Última atualização: 5 de maio de 2025

Tópicos:

Criado para:

Desenvolvedor

Conforme você passar por este modelo, substitua ou exclua todos os parágrafos em itálico (começando por este).

Comece atualizando os metadados (título e descrição) na parte superior da página. Ignore todas as instâncias do DNL nesta página. Essa é uma tag que ajuda nossos processos de tradução automática a traduzir corretamente a página para os vários idiomas compatíveis. Adicionaremos marcas à sua documentação após você enviá-la.

Visão geral

Forneça uma breve visão geral da sua empresa, incluindo o valor que ela oferece aos clientes. Inclua um link para a página inicial da documentação do produto para leitura adicional.

IMPORTANTE

Este conector de origem e página de documentação são criados e mantidos pela equipe YourSource. Para qualquer consulta ou solicitação de atualização, contate-os diretamente em Inserir link ou endereço de email onde você pode ser contatado para atualizações.

Pré-requisitos

Adicione nesta seção informações sobre qualquer item que os clientes precisem saber antes de começar a configurar a origem na interface do usuário do Adobe Experience Platform. Isso pode ser sobre:

que precisa ser adicionado a uma lista de permissões
requisitos para hash de email
qualquer especificação de conta da sua parte
como obter uma chave de API para se conectar à sua plataforma

Coletar credenciais necessárias

Para conectar YOURSOURCE à Experience Platform, você deve fornecer valores para as seguintes propriedades de conexão:

Credencial	Descrição	Exemplo
credencial um	Adicione aqui uma breve descrição à credencial de autenticação da sua origem	Adicione aqui um exemplo da credencial de autenticação da sua origem
credencial dois	Adicione aqui uma breve descrição à credencial de autenticação da sua origem	Adicione aqui um exemplo da credencial de autenticação da sua origem
credencial três	Adicione aqui uma breve descrição à credencial de autenticação da sua origem	Adicione aqui um exemplo da credencial de autenticação da sua origem

Para obter mais informações sobre essas credenciais, consulte a documentação de autenticação de SUA ORIGEM. Adicione aqui o link para a documentação de autenticação da sua plataforma.

Conecte YOURSOURCE ao Experience Platform usando a API Flow Service

O tutorial a seguir orienta você pelas etapas para criar uma conexão de origem YOURSOURCE e criar um fluxo de dados para trazer dados YOURSOURCE para a Experience Platform usando a Flow Service API.

Criar uma conexão básica

Uma conexão base retém informações entre sua origem e a Experience Platform, incluindo as credenciais de autenticação da origem, o estado atual da conexão e a ID de conexão base exclusiva. A ID de conexão básica permite explorar e navegar pelos arquivos de dentro da origem e identificar os itens específicos que deseja assimilar, incluindo informações sobre os tipos de dados e formatos.

Para criar uma ID de conexão base, faça uma solicitação POST para o ponto de extremidade /connections ao fornecer suas credenciais de autenticação da YOURSOURCE como parte do corpo da solicitação.

Formato da API

POST /connections

Solicitação

A solicitação a seguir cria uma conexão base para YOURSOURCE:

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/connections' \
    -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": "{YOURSOURCE} base connection",
        "description": "{YOURSOURCE} base connection to authenticate to Experience Platform",
        "connectionSpec": {
            "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
            "version": "1.0"
        },
        "auth": {
            "specName": "OAuth generic-rest-connector",
            "params": {
                "accessToken": "{ACCESS_TOKEN}",
                "refreshToken": "{REFRESH_TOKEN}",
                "expirationDate": "{EXPIRATION_DATE}"
            }
        }
    }'

Propriedade

Descrição

name

O nome da sua conexão básica. Certifique-se de que o nome da sua conexão básica seja descritivo, pois você pode usá-lo para pesquisar informações sobre a sua conexão básica.

description

Um valor opcional que pode ser incluído para fornecer mais informações sobre sua conexão básica.

connectionSpec.id

A ID de especificação de conexão da sua origem. Essa ID pode ser recuperada depois que a origem é registrada e aprovada por meio da API Flow Service.

auth.specName

O tipo de autenticação que você está usando para autenticar sua origem na Experience Platform.

auth.params.

Contém as credenciais necessárias para autenticar sua origem.

Resposta

Uma resposta bem-sucedida retorna a conexão base recém-criada, incluindo seu identificador de conexão exclusivo (id). Essa ID é necessária para explorar a estrutura de arquivos e o conteúdo da fonte na próxima etapa.

{
     "id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
     "etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}

Explorar sua fonte

Usando a ID de conexão básica gerada na etapa anterior, você pode explorar arquivos e diretórios executando solicitações do GET.
Use as chamadas a seguir para localizar o caminho do arquivo que você deseja trazer para Experience Platform:

Formato da API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}

Ao executar solicitações do GET para explorar a estrutura e o conteúdo do arquivo de origem, você deve incluir os parâmetros de consulta listados na tabela abaixo:

Parâmetro

Descrição

{BASE_CONNECTION_ID}

A ID de conexão básica gerada na etapa anterior.

objectType=rest

O tipo de objeto que você deseja explorar. Atualmente, este valor está sempre configurado para rest.

{OBJECT}

Esse parâmetro é necessário somente ao visualizar um diretório específico. Seu valor representa o caminho do diretório que você deseja explorar.

fileType=json

O tipo do arquivo que você deseja trazer para a Experience Platform. Atualmente, json é o único tipo de arquivo com suporte.

{PREVIEW}

Um valor booliano que define se o conteúdo da conexão oferece suporte à visualização.

{SOURCE_PARAMS}

Define parâmetros para o arquivo de origem que você deseja trazer para a Experience Platform. Para recuperar o tipo de formato aceito para {SOURCE_PARAMS}, você deve codificar toda a cadeia de caracteres list_id em base64. No exemplo abaixo, "list_id": "10c097ca71" codificado em base64 equivale a eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=.

Solicitação

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
    -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}'

Resposta

Uma resposta bem-sucedida retorna a estrutura do arquivo consultado.

{
  "data": [
    {
      "members": [
        {
          "id": "cff65fb4c5f5828666ad846443720efd",
          "email_address": "roykent@gmail.com",
          "unique_email_id": "72c758cbf1",
          "full_name": "Roy Kent",
          "web_id": 547094062,
          "email_type": "html",
          "status": "subscribed",
          "merge_fields": {
            "FNAME": "Roy",
            "LNAME": "Kent",
            "ADDRESS": {
              "addr1": "",
              "addr2": "",
              "city": "Richmond",
              "state": "Virginia",
              "zip": "",
              "country": "US"
            },
            "PHONE": "",
            "BIRTHDAY": ""
          },
          "stats": {
            "avg_open_rate": 0,
            "avg_click_rate": 0
          },
          "ip_signup": "",
          "timestamp_signup": "",
          "ip_opt": "103.43.112.97",
          "timestamp_opt": "2021-06-01T15:31:36+00:00",
          "member_rating": 2,
          "last_changed": "2021-06-01T15:31:36+00:00",
          "language": "",
          "vip": false,
          "email_client": "",
          "location": {
            "latitude": 0,
            "longitude": 0,
            "gmtoff": 0,
            "dstoff": 0,
            "country_code": "",
            "timezone": ""
          },
          "source": "Admin Add",
          "tags_count": 0,
          "tags": [

          ],
          "list_id": "10c097ca71"
        }
      ],
      "list_id": "10c097ca71",
      "total_items": 2,
      "_links": [
        {
          "rel": "self",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
          "method": "GET",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
          "schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
        },
        {
          "rel": "parent",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
          "method": "GET",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
        },
        {
          "rel": "create",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
          "method": "POST",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
          "schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
        }
      ]
    }
  ]
}

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.

Formato da API

POST /sourceConnections

Solicitação

A solicitação a seguir cria uma conexão de origem para YOURSOURCE:

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": "{YOURSOURCE} Source Connection",
        "description": "{YOURSOURCE} Source Connection",
        "baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
        "connectionSpec": {
            "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
            "version": "1.0"
        },
        "data": {
            "format": "json"
        },
        "params": {
            "server": "us6",
            "listId": "10c097ca71"
        }
    }'

Propriedade

Descrição

name

O nome da sua conexão de origem. Certifique-se de que o nome da conexão de origem seja descritivo, pois você pode usá-lo para pesquisar informações sobre a conexão de origem.

description

Um valor opcional que pode ser incluído para fornecer mais informações sobre a conexão de origem.

baseConnectionId

A ID de conexão base de YOURSOURCE. Essa ID foi gerada em uma etapa anterior.

connectionSpec.id

A ID de especificação de conexão que corresponde à sua origem.

data.format

O formato dos dados de YOURSOURCE que você deseja assimilar. Atualmente, o único formato de dados com suporte é json.

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": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
     "etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}

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 em que os dados assimilados devem ser armazenados. Para criar uma conexão de destino, você deve fornecer a ID de especificação de conexão fixa que corresponde ao Data Lake. Esta ID é: 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 esses identificadores, você pode criar uma conexão de destino 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

A solicitação a seguir cria uma conexão de destino para YOURSOURCE:

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": "{YOURSOURCE} Target Connection",
        "description": "{YOURSOURCE} Target Connection",
        "connectionSpec": {
            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        },
        "data": {
            "format": "json"
        },
        "params": {
            "dataSetId": "5ef4551c52e054191a61a99f"
        }
    }'

Propriedade

Descrição

name

O nome da sua conexão de destino. Certifique-se de que o nome da conexão de destino seja descritivo, pois você pode usá-lo para pesquisar informações sobre a conexão de destino.

description

Um valor opcional que pode ser incluído para fornecer mais informações sobre a conexão de destino.

connectionSpec.id

A ID da especificação de conexão que corresponde a Data Lake. Esta ID fixa é: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

data.format

O formato dos dados de YOURSOURCE que você deseja trazer para a Experience Platform.

params.dataSetId

A ID do conjunto de dados de destino recuperada em uma etapa anterior.

Resposta

Uma resposta bem-sucedida retorna o identificador exclusivo (id) da nova conexão de destino. Essa ID é necessária nas etapas posteriores.

{
     "id": "7c96c827-3ffd-460c-a573-e9558f72f263",
     "etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}

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. Isso é feito executando uma solicitação POST para Data Prep API 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: {ORG_ID}' \
    -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 esquema XDM de destino gerada em uma etapa anterior.

mappings.destinationXdmPath

O caminho XDM de destino para o qual o atributo de origem está sendo mapeado.

mappings.sourceAttribute

O atributo de origem que precisa ser mapeado para um caminho XDM de destino.

mappings.identity

Um valor booliano que designa se o conjunto de mapeamento será marcado para Identity Service.

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}"
}

Criar um fluxo

A última etapa para trazer dados de YOURSOURCE para a Experience Platform é criar um fluxo de dados. Até agora, você tem os seguintes valores necessários preparados:

ID de conexão do Source
ID da conexão de destino
ID de mapeamento

Um fluxo de dados é responsável por agendar e coletar dados de uma origem. Você pode criar um fluxo de dados executando uma solicitação POST enquanto fornece os valores mencionados anteriormente na carga.

Para agendar uma assimilação, primeiro defina o valor da hora inicial como a época em segundos. Em seguida, defina 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 assimilações consecutivas. No entanto, criar uma assimilação única não requer que um intervalo seja definido. Para todas as outras frequências, o valor do intervalo deve ser definido como igual ou maior que 15.

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": "{YOURSOURCE} dataflow",
        "description": "{YOURSOURCE} dataflow",
        "flowSpec": {
            "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "246d052c-da4a-494a-937f-a0d17b1c6cf5"
        ],
        "targetConnectionIds": [
            "7c96c827-3ffd-460c-a573-e9558f72f263"
        ],
        "transformations": [
            {
                "name": "Mapping",
                "params": {
                    "mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
                    "mappingVersion": "0"
                }
            }
        ],
        "scheduleParams": {
            "startTime": "1625040887",
            "frequency": "minute",
            "interval": 15
        }
    }'

Propriedade

Descrição

name

O nome do fluxo de dados. Verifique se o nome do fluxo de dados é descritivo, pois você pode usá-lo para pesquisar informações sobre o fluxo de dados.

description

Um valor opcional que pode ser incluído para fornecer mais informações sobre o fluxo de dados.

flowSpec.id

A ID de especificação de fluxo necessária para criar um fluxo de dados. Esta ID fixa é: 6499120c-0b15-42dc-936e-847ea3c24d72.

flowSpec.version

A versão correspondente da ID de especificação de fluxo. O padrão deste valor é 1.0.

sourceConnectionIds

A ID da conexão de origem gerada em uma etapa anterior.

targetConnectionIds

A ID da conexão de destino gerada em uma etapa anterior.

transformations

Essa propriedade contém as várias transformações necessárias para serem aplicadas aos seus dados. Essa propriedade é necessária ao trazer dados não compatíveis com XDM para a Experience Platform.

transformations.name

O nome atribuído à transformação.

transformations.params.mappingId

A ID de mapeamento gerou em uma etapa anterior.

transformations.params.mappingVersion

A versão correspondente da ID de mapeamento. O padrão deste valor é 0.

scheduleParams.startTime

Essa propriedade contém informações sobre o agendamento de assimilação do fluxo de dados.

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 de fluxo consecutivas. O valor do intervalo deve ser um inteiro diferente de zero. O intervalo não é necessário quando a frequência está 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. Você pode usar essa ID para monitorar, atualizar ou excluir seu fluxo de dados.

{
     "id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
     "etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}

Apêndice

A seção a seguir fornece informações sobre as etapas que podem ser seguidas para monitorar, atualizar e excluir o fluxo de dados.

Monitorar seu fluxo de dados

Depois que o fluxo de dados for criado, você poderá monitorar os dados que estão sendo assimilados por meio dele para ver informações sobre execuções de fluxo, status de conclusão e erros. Para obter exemplos completos de API, leia o guia em monitorando seus fluxos de dados de fontes usando a API.

Atualizar seu fluxo de dados

Atualize os detalhes do seu fluxo de dados, como seu nome e descrição, bem como seu agendamento de execução e conjuntos de mapeamento associados fazendo uma solicitação PATCH para o ponto de extremidade /flows da API Flow Service, ao mesmo tempo em que fornece a ID do seu fluxo de dados. Ao fazer uma solicitação PATCH, você deve fornecer o etag exclusivo do fluxo de dados no cabeçalho If-Match. Para obter exemplos completos de API, leia o guia em atualizando fluxos de dados de fontes usando a API

Atualizar sua conta

Atualize o nome, a descrição e as credenciais da conta de origem executando uma solicitação PATCH para a API Flow Service enquanto fornece a ID da conexão base como um parâmetro de consulta. Ao fazer uma solicitação PATCH, você deve fornecer o etag exclusivo da sua conta de origem no cabeçalho If-Match. Para obter exemplos completos de API, leia o guia em atualizando a conta de origem usando a API.

Excluir seu fluxo de dados

Exclua seu fluxo de dados executando uma solicitação DELETE para a API Flow Service enquanto fornece a ID do fluxo de dados que você deseja excluir como parte do parâmetro de consulta. Para obter exemplos completos de API, leia o guia em excluindo seus fluxos de dados usando a API.

Excluir sua conta

Exclua sua conta executando uma solicitação DELETE para a API Flow Service enquanto fornece a ID de conexão básica da conta que você deseja excluir. Para obter exemplos completos de API, leia o guia em excluindo sua conta de origem usando a API.

recommendation-more-help