Extração de atividade em massa

Referência de Ponto de Extremidade de Extração de Atividade em Massa

As APIs REST de extração de atividade em massa recuperam grandes volumes de dados de atividade do Marketo. Use essas APIs para processos que não exigem baixa latência, como integração de CRM, ETL, data warehouse e arquivamento de dados.

Permissões

O usuário da API deve ter a permissão “Atividade somente leitura” ou “Atividade de leitura e gravação”.

Filtros

opções de primaryAttributeValueIds primaryattributevalueids-options

Ao usar primaryAttributeValueIds, você também deve incluir o filtro activityTypeIds. Este filtro pode conter somente IDs de atividade que correspondam ao grupo de ativos correspondente. Por exemplo, ao filtrar ativos de Formulários da Web, activityTypeIds pode conter somente a ID de tipo de atividade “Preencher Formulário”.

A solicitação a seguir inclui o filtro primaryAttributeValueIds:

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValueIds": [
      16,102,95,8
    ]
  }
}

primaryAttributeValueIds e primaryAttributeValues não podem ser usados juntos.

opções de primaryAttributeValues primaryattributevalues-options

Use a notação <program>.<asset> para especificar nomes para os grupos de ativos Programa de marketing, Lista estática e Formulário web. Por exemplo, especifique o form “Saída MPS” no programa “GL_OP_ALL_2021” como “GL_OP_ALL_2021.MPS de Saída”.

A solicitação a seguir inclui o filtro primaryAttributeValues:

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValues": [
      "GL_OP_ALL_2021.MPS Outbound"
    ]
  }
}

Ao usar primaryAttributeValues, você também deve incluir o filtro activityTypeIds. Este filtro pode conter somente IDs de atividade que correspondam ao grupo de ativos correspondente. Por exemplo, ao filtrar ativos de Formulários da Web, activityTypeIds pode conter somente a ID de tipo de atividade “Preencher Formulário”.

primaryAttributeValues e primaryAttributeValueIds não podem ser usados juntos.

Opções

Criação de um trabalho

Crie um trabalho de exportação para definir os registros a serem recuperados. Use o ponto de extremidade Criar Trabalho de Atividade de Exportação.

Todo trabalho requer um filtro createdAt. Seus parâmetros de datetime startAt e endAt definem as datas de criação de atividade mais antigas e mais recentes permitidas. Para excluir tipos de atividades que não são relevantes, inclua também o filtro activityTypeIds opcional.

A solicitação a seguir cria um trabalho de exportação de CSV para tipos de atividades selecionadas em um intervalo de datas:

POST /bulk/v1/activities/export/create.json

{
   "format": "CSV",
   "filter": {
      "createdAt": {
         "startAt": "2017-07-01T23:59:59-00:00",
         "endAt": "2017-07-31T23:59:59-00:00"
      },
      "activityTypeIds": [
         1,
         12,
         13
      ]
   }
}

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Created",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

A resposta retorna um exportId e um status de “Criado”. Uma tarefa criada ainda não está na fila de processamento.

Para adicionar o trabalho à fila, chame o ponto de extremidade Enfileirar Trabalho de Exportação com o exportId da resposta de criação.

POST /bulk/v1/activities/export/{exportId}/enqueue.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Queued",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

O status da resposta agora é “Em fila”. Quando um trabalhador se torna disponível, o status muda para “Processando” e o trabalho começa a agregar registros do Marketo.

Status do trabalho de pesquisa

O status do trabalho só pode ser recuperado para trabalhos criados pelo mesmo usuário da API.

A Extração de atividade em massa processa trabalhos de forma assíncrona. Sonde o ponto de extremidade Obter Status do Trabalho da Atividade de Exportação para determinar quando um trabalho é concluído:

GET /bulk/v1/activities/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Completed",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "startedAt": "2017-01-21T11:51:30-08:00",
         "finishedAt": "2017-01-21T12:59:30-08:00",
         "format": "CSV",
         "numberOfRecords": 15423,
         "fileSize": 12342,
         "fileChecksum": "sha256:c16514c7e80fcac5ea055dacae9617fc3c29aff5365e3743071313ce0ed2a815"
      }
   ]
}

O campo status retorna um dos seguintes valores:

Recuperação de dados

Quando o status do trabalho for “Concluído”, recupere os dados exportados com o ponto de extremidade Obter Arquivo de Atividade de Exportação:

GET /bulk/v1/activities/export/{exportId}/file.json

O corpo da resposta contém o arquivo no formato configurado para o trabalho.

Se um campo de atividade solicitado não contiver dados, null aparecerá no campo de arquivo de exportação correspondente. O exemplo a seguir mostra dados de atividade exportados:

marketoGUID,leadId,activityDate,activityTypeId,campaignId,primaryAttributeValueId,primaryAttributeValue,attributes
783957693,5414087,2022-02-13T14:06:20Z,104,8497,1670,MembershipTest1,"{""Reason"":""Changed by Smart Campaign MembershipTestCampaignStepChoice.MembershipTestCampaignStepChoiceSetUp action Change Data Value"",""Program Member ID"":3240303,""Acquired By"":true,""Old Status"":""Not in Program"",""New Status ID"":21,""Success"":false,""New Status"":""On List"",""Old Status ID"":20}"
783958220,5414094,2022-02-13T14:08:50Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":6,""Success"":true,""New Status"":""Attended"",""Old Status ID"":1}"
783958306,5414094,2022-02-13T14:09:16Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Attended"",""New Status ID"":6,""Success"":false,""New Status"":""Attended"",""Old Status ID"":6}"
783961924,5316669,2022-02-13T14:27:21Z,104,11614,2333,Nurture Automation,"{""Program Member ID"":3240306,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":27,""Success"":false,""New Status"":""Member"",""Old Status ID"":26}"

Para recuperação parcial ou retomável, o ponto de extremidade do arquivo dá suporte ao cabeçalho HTTP Range opcional com um intervalo bytes. Se você omitir esse cabeçalho, o endpoint retornará o arquivo inteiro. Para obter mais informações sobre como usar o cabeçalho Range, consulte Extração em Massa.

Cancelar um trabalho

Para parar um trabalho desnecessário ou configurado incorretamente, chame o ponto de extremidade Cancelar Trabalho da Atividade de Exportação:

POST /bulk/v1/activities/export/{exportId}/cancel.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Cancelled",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "format": "CSV"
      }
   ]
}

O status da resposta indica que a tarefa foi cancelada.