Documentação Experience Platform Guia dos conectores de origem

Criar um SUA FONTE conexão usando o Flow Service API

Last update: Wed Nov 01 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:

Criado para:

Desenvolvedor

À medida que passa por esse 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 tags à sua documentação depois que 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.

IMPORTANT

Esse conector de origem e a página de documentação são criados e mantidos pelo SuaOrigem equipe. Para qualquer consulta ou solicitação de atualização, entre em contato diretamente em Inserir link ou endereço de email no qual você pode ser contatado para obter atualizações.

Pré-requisitos

Adicione informações nesta seção sobre qualquer coisa que os clientes precisem saber antes de começar a configurar o código-fonte na interface do usuário do Adobe Experience Platform. Isso pode se referir a:

que precisam ser adicionados a uma lista de permissões
requisitos para hash de email
quaisquer detalhes específicos da conta da sua parte
como obter uma chave de API para se conectar à sua plataforma

Coletar credenciais necessárias

Para se conectar SUA FONTE para Experience Platform, você deve fornecer valores para as seguintes propriedades de conexão:

Credencial

Descrição

Exemplo

credencial um

Adicione uma breve descrição à credencial de autenticação da sua origem aqui

Adicione um exemplo da credencial de autenticação da sua origem aqui

credencial dois

Adicione uma breve descrição à credencial de autenticação da sua origem aqui

Adicione um exemplo da credencial de autenticação da sua origem aqui

credencial três

Adicione uma breve descrição à credencial de autenticação da sua origem aqui

Adicione um exemplo da credencial de autenticação da sua origem aqui

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

Conectar SUA FONTE para a Platform usando o Flow Service API

O tutorial a seguir guiará você pelas etapas para criar um SUA FONTE conexão de origem e criar um fluxo de dados para trazer SUA FONTE dados para a Platform usando o Flow Service API.

Crie uma conexão básica base-connection

Uma conexão base retém informações entre sua origem e a Platform, incluindo as credenciais de autenticação da origem, o estado atual da conexão e sua 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 um ID de conexão base, faça uma solicitação POST ao /connections ao fornecer sua SUA FONTE credenciais de autenticação como parte do corpo da solicitação.

Formato da API

POST /connections

Solicitação

A solicitação a seguir cria uma conexão básica para SUA FONTE:

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 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 do Flow Service API.

auth.specName

O tipo de autenticação que você está usando para autenticar sua origem na 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 explore

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 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. No momento, esse valor está sempre definido como 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 Platform. Atualmente, json é o único tipo de arquivo compatível.

{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 Platform. Para recuperar o tipo de formato aceito para {SOURCE_PARAMS}, você deve codificar o inteiro list_id sequência de caracteres 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 source-connection

Você pode criar uma conexão de origem fazendo uma solicitação POST para o Flow Service API. 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 SUA FONTE:

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 SUA FONTE. 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 do SUA FONTE dados que você deseja assimilar. No momento, o único formato de dados compatível é 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 target-schema

Para que os dados de origem sejam usados na 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 da Platform no qual os dados de origem estão contidos.

Um schema XDM de destino pode ser criado executando uma solicitação POST para o 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 schema usando a API.

Criar um conjunto de dados de destino target-dataset

Um conjunto de dados de destino pode ser criado executando uma solicitação POST para o API do serviço de catálogo, fornecendo a ID do schema de destino na carga útil.

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 target-connection

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 da conexão fixa que corresponde à Data Lake. Essa 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 o Flow Service API 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 SUA FONTE:

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 de especificação de conexão que corresponde a Data Lake. Essa ID fixa é: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

data.format

O formato do SUA FONTE que você deseja trazer para a 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 da nova conexão de destino (id). Essa ID é necessária nas etapas posteriores.

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

Criar um mapeamento mapping

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 do público-alvo 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 booleano 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 flow

O último passo para trazer dados de SUA FONTE para a Platform é criar um fluxo de dados. Até agora, você tem os seguintes valores necessários preparados:

ID da conexão de origem
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 como uma das cinco opções: once, minute, hour, dayou 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. Essa ID fixa é: 6499120c-0b15-42dc-936e-847ea3c24d72.

flowSpec.version

A versão correspondente da ID de especificação de fluxo. Esse valor é padronizado como 1.0.

sourceConnectionIds

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

targetConnectionIds

A variável 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 Platform.

transformations.name

O nome atribuído à transformação.

transformations.params.mappingId

A variável ID do mapeamento gerada em uma etapa anterior.

transformations.params.mappingVersion

A versão correspondente da ID de mapeamento. Esse valor é padronizado como 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, dayou 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 monitoramento de fluxos de dados de origens usando a API.

Atualizar seu fluxo de dados

Atualize os detalhes do seu fluxo de dados, como nome e descrição, bem como o agendamento de execução e os conjuntos de mapeamento associados fazendo uma solicitação PATCH para o /flows endpoint de Flow Service ao fornecer a ID do fluxo de dados. Ao fazer uma solicitação PATCH, você deve fornecer os atributos exclusivos de seu fluxo de dados etag no If-Match cabeçalho. Para obter exemplos completos de API, leia o guia em atualização de fluxos de dados de origens usando a API

Atualizar sua conta

Atualize o nome, a descrição e as credenciais da sua conta de origem executando uma solicitação PATCH para a Flow Service ao fornecer a ID de conexão básica como um parâmetro de consulta. Ao fazer uma solicitação PATCH, você deve fornecer as informações exclusivas de sua conta de origem etag no If-Match cabeçalho. Para obter exemplos completos de API, leia o guia em atualização da conta de origem usando a API.

Excluir seu fluxo de dados

Exclua seu fluxo de dados executando uma solicitação DELETE para o Flow Service ao fornecer 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 exclusão de fluxos de dados usando a API.

Excluir sua conta

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

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089