Criar um fluxo de dados para Mailchimp Campaign uso da API do Serviço de fluxo

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

Pré-requisitos

Antes de se conectar Mailchimp ao Adobe Experience Platform usando o código de atualização OAuth 2, primeiro você deve recuperar o token de acesso para MailChimp. Consulte a Mailchimp Guia do OAuth 2 para obter instruções detalhadas sobre como localizar o token de acesso.

Criar uma conexão básica

Depois de recuperar o Mailchimp credenciais de autenticação, agora é possível iniciar o processo de criação do fluxo de dados para trazer Mailchimp Campaign dados para a Platform. A primeira etapa na criação de um fluxo de dados é criar uma conexão base.

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.

Mailchimp O oferece suporte à autenticação básica e ao código de atualização do OAuth 2. Consulte os exemplos a seguir para obter orientação sobre como realizar a autenticação com qualquer um dos tipos de autenticação.

Criar um Mailchimp conexão básica usando autenticação básica

Para criar um Mailchimp conexão básica usando autenticação básica, faça uma solicitação POST ao /connections endpoint de Flow Service ao fornecer credenciais para o authorizationTestUrl, username, e password.

Formato da API

POST /connections

Solicitação

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

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -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": "Mailchimp base connection with basic authentication",
      "description": "Mailchimp Campaign base connection with basic authentication",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "Basic Authentication",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "username": "{USERNAME}",
              "password": "{PASSWORD}"
          }
      }
  }'
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 (Opcional) Uma propriedade que você pode incluir 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 conectar sua origem à Platform.
auth.params.authorizationTestUrl (Opcional) O URL de teste de autorização é usado para validar credenciais ao criar uma conexão base. Se não forem fornecidas, as credenciais serão automaticamente verificadas durante a etapa de criação da conexão de origem.
auth.params.username O nome de usuário que corresponde ao seu Mailchimp conta. Isso é necessário para a autenticação básica.
auth.params.password A senha que corresponde ao seu Mailchimp conta. Isso é necessário para a autenticação básica.

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": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

Criar um Mailchimp conexão básica usando o código de atualização OAuth 2

Para criar um Mailchimp conexão básica usando o código de atualização OAuth 2, faça uma solicitação POST para o /connections ao fornecer credenciais para o seu authorizationTestUrl, e accessToken.

Formato da API

POST /connections

Solicitação

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

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -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": "Mailchimp base connection with OAuth 2 refresh code",
      "description": "Mailchimp Campaign base connection with OAuth 2 refresh code",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "oAuth2RefreshCode",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "accessToken": "{ACCESS_TOKEN}"
          }
      }
  }'
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 (Opcional) Uma propriedade que você pode incluir 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 após o registro da origem usando o Flow Service API.
auth.specName O tipo de autenticação que você está usando para autenticar sua origem na Platform.
auth.params.authorizationTestUrl (Opcional) O URL de teste de autorização é usado para validar credenciais ao criar uma conexão base. Se não forem fornecidas, as credenciais serão automaticamente verificadas durante a etapa de criação da conexão de origem.
auth.params.accessToken O token de acesso correspondente usado para autenticar sua origem. Isso é necessário para a autenticação baseada em OAuth.

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": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

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. 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.
{OBJECT_TYPE} O tipo do objeto que você deseja explorar. Para origens REST, esse valor assume como padrão rest.
{OBJECT} O objeto que você deseja explorar.
{FILE_TYPE} 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.
{PREVIEW} Um valor booliano que define se o conteúdo da conexão oferece suporte à visualização.
{SOURCE_PARAMS} Uma string codificada na base64 de seu campaign_id.
DICA

Para recuperar o tipo de formato aceito para {SOURCE_PARAMS}, você deve codificar o inteiro campaignId sequência de caracteres em base64. Por exemplo, {"campaignId": "c66a200cda"} codificado em base64 equivale a eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9.

Formato da API

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

Solicitação

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/05c595e5-edc3-45c8-90bb-fcf556b57c4b/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9' \
  -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": [
        {
            "emails": [
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "cff65fb4c5f5828666ad846443720efd",
                    "email_address": "kendall2134@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
                        }
                    ]
                },
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "a16b82774b211afaf60902d1afd8abc5",
                    "email_address": "logan9935890967@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
                        }
                    ]
                },
            ]
        }
    ]
}

Criar uma conexão de origem

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.

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 fontes baseadas em arquivo:

Formato dos dados Valor de enumeração
Delimitado delimited
JSON json
Parquet parquet

Para todas as fontes baseadas em tabela, defina o valor como tabular.

Formato da API

POST /sourceConnections

Solicitação

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

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": "MailChimp source connection to ingest campaign ID",
      "description": "MailChimp Campaign source connection to ingest campaign ID",
      "baseConnectionId": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      },
      "params": {
          "campaignId": "c66a200cda"
      }
  }'
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 Mailchimp. 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 Mailchimp dados que você deseja assimilar.
params.campaignId A variável Mailchimp a ID da campanha identifica uma Mailchimp campanha, que permite enviar emails para suas listas/públicos.

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": "d6557bf1-7347-415f-964c-9316bd4cbf56",
    "etag": "\"e205c206-0000-0200-0000-615b5c070000\""
}

Criar um esquema XDM de destino

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

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

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 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 Mailchimp:

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": "MailChimp target connection",
      "description": "MailChimp Campaign target connection",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "parquet_xdm",
          "schema": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/570630b91eb9d5cf5db0436756abb110d02912917a67da2d",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "6155e3a9bd13651949515f14"
      }
  }'
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 Mailchimp 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": "9463fe9c-027d-4347-a423-894fcd105647",
    "etag": "\"b902e822-0000-0200-0000-615b5c370000\""
}
IMPORTANTE

No momento, não há suporte para funções de preparação de dados para Mailchimp Campaign.

Criar um fluxo

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

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 e a criação de uma assimilação única (once) 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 '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": "MailChimp Campaign dataflow",
      "description": "MailChimp Campaign dataflow",
      "flowSpec": {
          "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "d6557bf1-7347-415f-964c-9316bd4cbf56"
      ],
      "targetConnectionIds": [
          "9463fe9c-027d-4347-a423-894fcd105647"
      ],
      "scheduleParams": {
          "startTime": "1632809759",
          "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 (Opcional) Uma propriedade que você pode incluir 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.
scheduleParams.startTime A hora de início designada para o início da primeira assimilação 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": "be2d5249-eeaf-4a74-bdbd-b7bf62f7b2da",
    "etag": "\"7e010621-0000-0200-0000-615b5c9b0000\""
}

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.

Nesta página