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.
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.
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.
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\""
}
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\""
}
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 . |
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"
}
]
},
]
}
]
}
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\""
}
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.
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.
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\""
}
No momento, não há suporte para funções de preparação de dados para Mailchimp Campaign.
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
, day
ou 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 , 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": "be2d5249-eeaf-4a74-bdbd-b7bf62f7b2da",
"etag": "\"7e010621-0000-0200-0000-615b5c9b0000\""
}
A seção a seguir fornece informações sobre as etapas que podem ser seguidas para monitorar, atualizar e excluir o 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.
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.
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.
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.
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.