Extração de atividade em massa

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

O conjunto de Extração de atividade em massa de APIs REST fornece uma interface programática para recuperar grandes quantidades de dados de atividade do Marketo.  Para casos que não exigem baixa latência e devem transferir volumes significativos de dados de atividades para fora do Marketo, como integração de CRM, ETL, data warehouse e arquivamento de dados.

Permissões

As APIs de Extração de atividade em massa exigem que o usuário da API tenha as permissões de "Atividade somente leitura" ou "Atividade de leitura e gravação".

Filtros

opções de primaryAttributeValueIds primaryattributevalueids-options

Ao usar primaryAttributeValueIds, o filtro activityTypeIds deve estar presente e conter somente IDs de atividade que correspondam ao grupo de ativos correspondente. Por exemplo, se você estiver filtrando ativos de Formulários da Web, somente a ID de tipo de atividade "Preencher Formulário" será permitida em activityTypeIds.

Exemplo de corpo da solicitação:

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

Observe que você deve usar "<programa>.notação <asset>" para especificar o nome dos seguintes grupos de ativos: Programa de marketing, Lista estática, Formulário web. Por exemplo, um formulário com o nome "Saída MPS" que reside abaixo de um programa com o nome "GL_OP_ALL_2021" seria especificado como "GL_OP_ALL_2021.Saída MPS".

Exemplo de corpo da solicitação:

{
  "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, o filtro activityTypeIds deve estar presente e conter somente IDs de atividade que correspondam ao grupo de ativos correspondente. Por exemplo, se você estiver filtrando ativos de Formulários da Web, somente a ID de tipo de atividade "Preencher Formulário" será permitida em activityTypeIds. primaryAttributeValues e primaryAttributeValueIds não podem ser usados juntos.

Opções

Criação de um trabalho

Para exportar registros, primeiro defina o trabalho e o conjunto de registros que deseja recuperar.  Crie o trabalho usando o ponto de extremidade Criar Trabalho de Atividade de Exportação.  Ao exportar atividades, há dois filtros principais que podem ser aplicados: createdAt, que é sempre obrigatório, e activityTypeIds, que é opcional.  O filtro createdAt é usado para definir um intervalo de datas em que as atividades foram criadas, usando os parâmetros startAt e endAt, que são campos de data e hora, e representam a data de criação mais antiga permitida e a data de criação mais recente permitida, respectivamente.  Você também pode filtrar apenas alguns tipos de atividades, usando o filtro activityTypeIds.  Isso é útil para remover resultados que não são relevantes para seu caso de uso.

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 tarefa agora tem um status de "Criada", mas ainda não está na fila de processamento.  Para colocá-lo na fila para que ele possa começar a ser processado, chame o ponto de extremidade Enfileirar Trabalho de Atividade de Exportação usando a exportId da resposta de status 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"
      }
   ]
}

Agora, o status é informando que a tarefa foi colocada em fila.  Quando um trabalhador se torna disponível para esse trabalho, o status é alternado 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 do Marketo é um endpoint assíncrono, portanto, o status do trabalho deve ser sondado para determinar quando o trabalho é concluído.  Consulte usando o ponto de extremidade Obter Status do Trabalho da Atividade de Exportação da seguinte maneira:

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 de status pode responder com um dos seguintes valores:

Recuperação de dados

Quando o trabalho for concluído, recupere seus dados usando o ponto de extremidade Obter Arquivo de Atividade de Exportação.

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

A resposta contém um arquivo formatado da maneira que o trabalho foi configurado. O endpoint responde com o conteúdo do arquivo.

Se um campo de cliente em potencial solicitado estiver vazio (não contiver dados), then null será colocado no campo correspondente no arquivo de exportação.  No exemplo abaixo, o campo campaignId da atividade retornada está vazio.

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 oferecer suporte à recuperação parcial e de fácil retomada de dados extraídos, o ponto de extremidade do arquivo oferece suporte opcionalmente ao cabeçalho HTTP Range do tipo bytes.  Se o cabeçalho não estiver definido, todo o conteúdo será retornado.  Você pode ler mais sobre como usar o cabeçalho Intervalo com a Extração em massa do Marketo.

Cancelar um trabalho

Se um trabalho for configurado incorretamente ou se se tornar desnecessário, ele poderá ser facilmente cancelado usando 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"
      }
   ]
}

Essa resposta tem um status que indica que o trabalho foi cancelado.