Documentação Experience Platform Guia do Perfil do cliente em tempo real

Ponto de extremidade de trabalhos de exportação de perfil

Last update: Wed Feb 28 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:
Profiles

Criado para:

Developer

Real-Time Customer Profile O permite criar uma única visualização de clientes individuais reunindo dados de várias fontes, incluindo dados de atributos e dados comportamentais. Os dados do perfil podem ser exportados para um conjunto de dados para processamento adicional. Por exemplo, Profile os dados podem ser exportados para ativação criando públicos-alvo, e os atributos de perfil podem ser exportados para relatórios.

Este documento fornece instruções passo a passo para criar e gerenciar trabalhos de exportação usando o API de perfil.

NOTE

Este guia aborda o uso de trabalhos de exportação no Profile API. Para obter informações sobre como gerenciar trabalhos de exportação para o Serviço de segmentação do Adobe Experience Platform, consulte o guia em exportar trabalhos na API de segmentação.

Além de criar um trabalho de exportação, você também pode acessar Profile dados usando o /entities também conhecido como "Profile Access". Consulte a manual de endpoint de entidades para obter mais informações. Para obter etapas sobre como acessar Profile dados usando a interface do usuário, consulte a guia do usuário.

Introdução

Os endpoints de API usados neste guia fazem parte da Real-Time Customer Profile API. Antes de continuar, reveja o guia de introdução para obter links para a documentação relacionada, um guia para ler as chamadas de API de exemplo neste documento e informações importantes sobre os cabeçalhos necessários para fazer chamadas com êxito para qualquer Experience Platform API.

Criar um trabalho de exportação

Exportação Profile os dados exigem primeiro a criação de um conjunto de dados para o qual os dados serão exportados e, em seguida, o início de um novo trabalho de exportação. Ambas as etapas podem ser realizadas usando APIs de Experience Platform, sendo que a primeira usa a API de Serviço de catálogo e a última usa a API de perfil do cliente em tempo real. As instruções detalhadas para concluir cada etapa estão descritas nas seções a seguir.

Criar um conjunto de dados de destino

Ao exportar Profile dados, um conjunto de dados de destino deve ser criado primeiro. É importante que o conjunto de dados seja configurado corretamente para garantir que a exportação seja bem-sucedida.

Uma das principais considerações é o esquema no qual o conjunto de dados se baseia (schemaRef.id na solicitação de amostra de API abaixo). Para exportar dados do perfil, o conjunto de dados deve ser baseado na variável XDM Individual Profile Esquema de união (https://ns.adobe.com/xdm/context/profile__union). Um esquema de união é um esquema somente leitura gerado pelo sistema que agrega os campos de esquemas que compartilham a mesma classe. No caso em apreço, XDM Individual Profile classe. Para obter mais informações sobre esquemas de visualização de união, consulte a seção união no guia de noções básicas da composição de esquema.

As etapas a seguir neste tutorial descrevem como criar um conjunto de dados que faça referência ao XDM Individual Profile Esquema de união usando o Catalog API. Você também pode usar o Platform para criar um conjunto de dados que faça referência ao esquema de união. As etapas para usar a interface do usuário estão descritas em este tutorial de interface do usuário para exportação de públicos mas também são aplicáveis aqui. Depois de concluído, você pode retornar a este tutorial para prosseguir com as etapas para iniciar um novo trabalho de exportação.

Se você já tiver um conjunto de dados compatível e souber sua ID, poderá prosseguir diretamente para a etapa para iniciar um novo trabalho de exportação.

Formato da API

POST /dataSets

Solicitação

A solicitação a seguir cria um novo conjunto de dados, fornecendo parâmetros de configuração na carga.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -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}' \
  -d '{
        "name": "Profile Data Export",
        "schemaRef": {
          "id": "https://ns.adobe.com/xdm/context/profile__union",
          "contentType": "application/vnd.adobe.xed+json;version=1"
        }
      }'

Propriedade

Descrição

name

Um nome descritivo para o conjunto de dados.

schemaRef.id

A ID da visualização de união (esquema) à qual o conjunto de dados será associado.

Resposta

Uma resposta bem-sucedida retorna uma matriz que contém a ID exclusiva gerada pelo sistema somente leitura do conjunto de dados recém-criado. É necessária uma ID de conjunto de dados configurada corretamente para exportar os dados do perfil com êxito.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Iniciar trabalho de exportação initiate

Depois de ter um conjunto de dados persistente em união, você pode criar um trabalho de exportação para persistir os dados do Perfil para o conjunto de dados fazendo uma solicitação POST para o /export/jobs ponto de extremidade na API do perfil do cliente em tempo real e fornece os detalhes dos dados que você deseja exportar no corpo da solicitação.

Formato da API

POST /export/jobs

Solicitação

A solicitação a seguir cria um novo trabalho de exportação, fornecendo parâmetros de configuração na carga.

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs \
  -H 'Content-Type: application/json' \
  -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}' \
  -d '{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields": {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    }
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }'

Propriedade

Descrição

fields

(Opcional) Limita os campos de dados a serem incluídos na exportação somente aos fornecidos neste parâmetro. A omissão desse valor resultará na inclusão de todos os campos nos dados exportados.

mergePolicy

(Opcional) Especifica a política de mesclagem para controlar os dados exportados. Inclua esse parâmetro quando houver vários públicos-alvo sendo exportados.

mergePolicy.id

A ID da política de mesclagem.

mergePolicy.version

A versão específica da política de mesclagem a ser usada. A omissão desse valor assumirá como padrão a versão mais recente.

additionalFields.eventList

(Opcional) Controla os campos de evento de série temporal exportados para objetos filho ou associados fornecendo uma ou mais das seguintes configurações:

eventList.fields: controle os campos que serão exportados.
eventList.filter: Especifica critérios que limitam os resultados incluídos de objetos associados. Espera um valor mínimo necessário para a exportação, normalmente uma data.
eventList.filter.fromIngestTimestamp: Filtra os eventos de série temporal para aqueles que foram assimilados após o carimbo de data e hora fornecido. Esse não é o tempo do evento em si, mas o tempo de assimilação dos eventos.

destination

(Obrigatório) Informações de destino dos dados exportados:

destination.datasetId: (Obrigatório) A ID do conjunto de dados para o qual os dados devem ser exportados.
destination.segmentPerBatch: (Opcional) Um valor booleano que, se não for fornecido, assumirá como padrão false. Um valor de false O exporta todas as IDs de definição de segmento em uma única ID de lote. Um valor de true O exporta uma ID de definição de segmento para uma ID de lote. Observe que definir o valor como true pode afetar o desempenho da exportação em lote.

schema.name

(Obrigatório) O nome do esquema associado ao conjunto de dados para o qual os dados devem ser exportados.

NOTE

Para exportar apenas dados de Perfil e não incluir dados de série temporal relacionados, remova o objeto "additionalFields" da solicitação.

Resposta

Uma resposta bem-sucedida retorna um conjunto de dados preenchido com dados do Perfil, conforme especificado na solicitação.

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "NEW",
    "requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
    "computeGatewayJobId": {},
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1559674261657
        }
    },
    "destination": {
      "dataSetId": "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{ORG_ID}",
    "creationTime": 1559674261657
}

Listar todos os trabalhos de exportação

Você pode retornar uma lista de todos os trabalhos de exportação para uma organização específica executando uma solicitação GET para a export/jobs terminal. A solicitação também suporta os parâmetros de consulta limit e offset, conforme mostrado abaixo.

Formato da API

GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}

Parâmetro

Descrição

start

Deslocar a página de resultados retornados de acordo com o tempo de criação da solicitação. Exemplo: start=4

limit

Limitar o número de resultados retornados. Exemplo: limit=10

page

Retornar uma página específica de resultados, de acordo com o horário de criação da solicitação. Exemplo: page=2

sort

Classificar os resultados por um campo específico em ordem crescente ( asc ) ou decrescente ( desc ). O parâmetro de classificação não funciona ao retornar várias páginas de resultados. Exemplo: sort=updateTime:asc

Solicitação

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/ \
  -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

A resposta inclui uma records objeto que contém os trabalhos de exportação criados por sua organização.

{
  "records": [
    {
      "profileInstanceId": "ups",
      "jobType": "BATCH",
      "id": 726,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "timestampOrdered-none-mp",
          "version": 1
      },
      "status": "SUCCEEDED",
      "requestId": "d995479c-8a08-4240-903b-af469c67be1f",
      "computeGatewayJobId": {
          "exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
          "pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538615973895,
              "endTimeInMs": 1538616233239,
              "totalTimeInMs": 259344
          },
          "profileExportTime": {
              "startTimeInMs": 1538616067445,
              "endTimeInMs": 1538616139576,
              "totalTimeInMs": 72131
          },
          "aCPDatasetWriteTime": {
              "startTimeInMs": 1538616195172,
              "endTimeInMs": 1538616195715,
              "totalTimeInMs": 543
          }
      },
      "destination": {
          "datasetId": "5b7c86968f7b6501e21ba9df",
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
      },
      "updateTime": 1538616233239,
      "imsOrgId": "{ORG_ID}",
      "creationTime": 1538615973895
    },
    {
      "profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
      "errors": [
        {
          "code": "0090000009",
          "msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
          "callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
        },
        {
          "code": "unknown",
          "msg": "Job aborted.",
          "callStack": "org.apache.spark.SparkException: Job aborted."
        }
      ],
      "jobType": "BATCH",
      "filter": {
        "segments": [
            {
                "segmentId": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
            }
        ]
      },
      "id": 722,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
          "version": 1
      },
      "status": "FAILED",
      "requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
      "computeGatewayJobId": {
          "exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538573416687,
              "endTimeInMs": 1538573922551,
              "totalTimeInMs": 505864
          },
          "profileExportTime": {
              "startTimeInMs": 1538573872211,
              "endTimeInMs": 1538573918809,
              "totalTimeInMs": 46598
          }
      },
      "destination": {
          "datasetId": "5bb4c46757920712f924a3eb",
          "batchId": ""
      },
      "updateTime": 1538573922551,
      "imsOrgId": "{ORG_ID}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

Monitorar o progresso da exportação

Para exibir os detalhes de um trabalho de exportação específico ou monitorar seu status à medida que ele é processado, você pode fazer uma solicitação GET ao /export/jobs e inclua o id do trabalho de exportação no caminho. O trabalho de exportação é concluído depois que a variável status O campo retorna o valor "SUCCEEDED".

Formato da API

GET /export/jobs/{EXPORT_JOB_ID}

Parâmetro

Descrição

{EXPORT_JOB_ID}

A variável id do trabalho de exportação que você deseja acessar.

Solicitação

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/24115 \
  -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

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "SUCCEEDED",
    "requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
    "computeGatewayJobId": {
      "exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
      "pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
    },
    "metrics": {
      "totalTime": {
        "startTimeInMs": 1547053539564,
        "endTimeInMs": 1547054743929,
        "totalTimeInMs": 1204365
      },
      "profileExportTime": {
        "startTimeInMs": 1547053667591,
        "endTimeInMs": 1547053778195,
        "totalTimeInMs": 110604
      },
      "aCPDatasetWriteTime": {
        "startTimeInMs": 1547054660416,
        "endTimeInMs": 1547054698918,
        "totalTimeInMs": 38502
      }
    },
    "destination": {
      "dataSetId": "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{ORG_ID}",
    "creationTime": 1559674261657
}

Propriedade

Descrição

batchId

O identificador dos lotes criados a partir de uma exportação bem-sucedida, para ser usado para fins de pesquisa ao ler dados do perfil.

Cancelar um trabalho de exportação

o Experience Platform permite cancelar um trabalho de exportação existente, que pode ser útil por vários motivos, incluindo se o trabalho de exportação não foi concluído ou ficou preso no estágio de processamento. Para cancelar um trabalho de exportação, é possível executar uma solicitação DELETE para o /export/jobs e inclua o id do trabalho de exportação que você deseja cancelar para o caminho da solicitação.

Formato da API

DELETE /export/jobs/{EXPORT_JOB_ID}

Parâmetro

Descrição

{EXPORT_JOB_ID}

A variável id do trabalho de exportação que você deseja acessar.

Solicitação

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs/726 \
  -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 solicitação de exclusão bem-sucedida retorna o Status HTTP 204 (Sem conteúdo) e um corpo de resposta vazio, indicando que a operação de cancelamento foi bem-sucedida.

Próximas etapas

Depois que a exportação for concluída com sucesso, seus dados estarão disponíveis no Data Lake no Experience Platform. Em seguida, você pode usar o API de acesso a dados para acessar os dados usando o batchId associada à exportação. Dependendo do tamanho da exportação, os dados podem estar em partes e o lote pode consistir em vários arquivos.

Para obter instruções passo a passo sobre como usar a API de acesso a dados para acessar e baixar arquivos em lote, siga o Tutorial de acesso a dados.

Você também pode acessar com êxito os dados exportados do Perfil do cliente em tempo real usando o serviço de consulta da Adobe Experience Platform. Usando a interface ou a API RESTful, o Serviço de consulta permite gravar, validar e executar consultas em dados no Data Lake.

Para obter mais informações sobre como consultar dados de público, consulte a Documentação do Serviço de consulta.

Apêndice

A seção a seguir contém informações adicionais sobre trabalhos de exportação na API do perfil.

Exemplos adicionais de carga útil de exportação

O exemplo de chamada de API mostrado na seção em iniciar um trabalho de exportação O cria um processo que contém dados de perfil (registro) e de evento (série temporal). Esta seção fornece exemplos adicionais de carga da solicitação para limitar a exportação para conter um tipo de dados ou o outro.

A carga a seguir cria um trabalho de exportação que contém apenas dados de perfil (nenhum evento):

{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Para criar um trabalho de exportação que contenha apenas dados do evento (sem atributos de perfil), a carga pode ser semelhante ao seguinte:

{
    "fields": "identityMap",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields": {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Exportação de públicos

Você também pode usar o endpoint de trabalhos de exportação para exportar públicos em vez de Profile dados. Consulte o guia sobre exportar trabalhos na API de segmentação para obter mais informações.

recommendation-more-help

54550d5b-f1a1-4065-a394-eb0f23a2c38b