Guia do desenvolvedor de assimilação em lote
Este documento fornece um guia abrangente sobre como usar o endpoints da API de assimilação em lote no Adobe Experience Platform. Para obter uma visão geral das APIs de assimilação em lote, incluindo pré-requisitos e práticas recomendadas, comece lendo o visão geral da API de assimilação em lote.
O apêndice deste documento fornece informações para formatação dos dados a serem usados para assimilação, incluindo arquivos de dados CSV e JSON de amostra.
Introdução
Os endpoints de API usados neste guia fazem parte do API de assimilação em lote. A assimilação em lote é fornecida por meio de uma API RESTful, na qual você pode executar operações CRUD básicas em relação aos tipos de objeto compatíveis.
Antes de continuar, reveja o visão geral da API de assimilação em lote e a variável guia de introdução.
Assimilar arquivos JSON
Criar lote
Primeiro, será necessário criar um lote, com JSON como formato de entrada. Ao criar o lote, será necessário fornecer uma ID de conjunto de dados. Você também precisará garantir que todos os arquivos carregados como parte do lote estejam em conformidade com o esquema XDM vinculado ao conjunto de dados fornecido.
isMultiLineJson
sinalizador precisará ser definido. Para obter mais informações, leia a guia de solução de problemas de assimilação em lote.Formato da API
POST /batches
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
{DATASET_ID}
Resposta
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
Fazer upload de arquivos
Agora que você criou um lote, pode usar a ID do lote da resposta de criação do lote para fazer upload dos arquivos para o lote. É possível fazer upload de vários arquivos para o lote.
Formato da API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'content-type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Resposta
200 OK
Concluir lote
Quando terminar de fazer upload de todas as diferentes partes do arquivo, você precisará sinalizar que os dados foram totalmente carregados e que o lote está pronto para promoção.
Formato da API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitação
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Assimilar arquivos do Parquet ingest-parquet-files
Criar lote
Primeiro, será necessário criar um lote, com Parquet como formato de entrada. Ao criar o lote, será necessário fornecer uma ID de conjunto de dados. Você também precisará garantir que todos os arquivos carregados como parte do lote estejam em conformidade com o esquema XDM vinculado ao conjunto de dados fornecido.
Solicitação
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-api-key: {API_KEY}" \
-H "x-sandbox-name: {SANDBOX_NAME}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Resposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Fazer upload de arquivos
Agora que você criou um lote, poderá usar o batchId
de antes para carregar arquivos no lote. É possível fazer upload de vários arquivos para o lote.
Formato da API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.parquet
.Resposta
200 OK
Concluir lote
Quando terminar de fazer upload de todas as diferentes partes do arquivo, você precisará sinalizar que os dados foram totalmente carregados e que o lote está pronto para promoção.
Formato da API
POST /batches/{BATCH_ID}?action=complete
{BATCH_ID}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Assimilar arquivos grandes do Parquet
Criar lote
Primeiro, será necessário criar um lote, com Parquet como formato de entrada. Ao criar o lote, será necessário fornecer uma ID de conjunto de dados. Você também precisará garantir que todos os arquivos carregados como parte do lote estejam em conformidade com o esquema XDM vinculado ao conjunto de dados fornecido.
Formato da API
POST /batches
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Resposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Inicializar arquivo grande
Depois de criar o lote, será necessário inicializar o arquivo grande antes de fazer upload dos blocos no lote.
Formato da API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=INITIALIZE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
201 Created
Fazer upload de grandes partes de arquivo
Agora que o arquivo foi criado, todos os blocos subsequentes podem ser carregados fazendo solicitações PATCH repetidas, uma para cada seção do arquivo.
Formato da API
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X PATCH https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Range: bytes {CONTENT_RANGE}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{CONTENT_RANGE}
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Resposta
200 OK
Arquivo grande completo
Agora que você criou um lote, poderá usar o batchId
de antes para carregar arquivos no lote. É possível fazer upload de vários arquivos para o lote.
Formato da API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
201 Created
Concluir lote
Quando terminar de fazer upload de todas as diferentes partes do arquivo, você precisará sinalizar que os dados foram totalmente carregados e que o lote está pronto para promoção.
Formato da API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Assimilar arquivos CSV
Para assimilar arquivos CSV, você precisará criar uma classe, esquema e um conjunto de dados que seja compatível com CSV. Para obter informações detalhadas sobre como criar a classe e o esquema necessários, siga as instruções fornecidas na tutorial de criação de esquema ad-hoc.
Criar conjunto de dados
Depois de seguir as instruções acima para criar a classe e o esquema necessários, será necessário criar um conjunto de dados que seja compatível com CSV.
Formato da API
POST /catalog/dataSets
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-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": "{DATASET_NAME}",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
{TENANT_ID}
{SCHEMA_ID}
Criar lote
Em seguida, será necessário criar um lote com CSV como o formato de entrada. Ao criar o lote, será necessário fornecer uma ID de conjunto de dados. Você também precisará garantir que todos os arquivos carregados como parte do lote estejam em conformidade com o esquema vinculado ao conjunto de dados fornecido.
Formato da API
POST /batches
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "csv"
}
}'
{DATASET_ID}
Resposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Fazer upload de arquivos
Agora que você criou um lote, poderá usar o batchId
de antes para carregar arquivos no lote. É possível fazer upload de vários arquivos para o lote.
Formato da API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.csv \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.csv"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.csv
.Resposta
200 OK
Concluir lote
Quando terminar de fazer upload de todas as diferentes partes do arquivo, você precisará sinalizar que os dados foram totalmente carregados e que o lote está pronto para promoção.
Formato da API
POST /batches/{BATCH_ID}?action=COMPLETE
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Cancelar um lote
Enquanto o lote estiver sendo processado, ele ainda poderá ser cancelado. No entanto, uma vez que um lote é finalizado (como sucesso ou falha), ele não pode ser cancelado.
Formato da API
POST /batches/{BATCH_ID}?action=ABORT
{BATCH_ID}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=ABORT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Excluir um lote delete-a-batch
Um lote pode ser excluído executando a seguinte solicitação POST com o action=REVERT
parâmetro de consulta para a ID do lote que você deseja excluir. O lote é marcado como "inativo", tornando-o qualificado para a coleta de lixo. O lote será coletado de forma assíncrona e nesse momento será marcado como "excluído".
Formato da API
POST /batches/{BATCH_ID}?action=REVERT
{BATCH_ID}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=REVERT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Correção de um lote
Ocasionalmente, pode ser necessário atualizar os dados na Loja de perfis da sua organização. Por exemplo, talvez seja necessário corrigir registros ou alterar um valor de atributo. A Adobe Experience Platform oferece suporte à atualização ou ao patch de dados da Loja de perfis por meio de uma ação de substituição ou "patch de um lote".
Para corrigir um lote, é necessário o seguinte:
- Um conjunto de dados ativado para Atualizações de perfil e atributo. Isso é feito por meio de tags de conjunto de dados e requer uma
isUpsert:true
tag a ser adicionada àunifiedProfile
matriz. Para obter detalhes sobre as etapas que mostram como criar um conjunto de dados ou configurar um conjunto de dados existente para substituição, siga o tutorial para ativar um conjunto de dados para atualizações de Perfil. - Um arquivo Parquet contendo os campos a serem corrigidos e campos de identidade para o Perfil. O formato de dados para corrigir um lote é semelhante ao processo normal de assimilação de lote. A entrada necessária é um arquivo Parquet e, além dos campos que serão atualizados, os dados carregados devem conter os campos de identidade para corresponder aos dados na Loja de Perfis.
Depois de ativar um conjunto de dados para Perfil e substituição e um arquivo do Parquet contendo os campos que você deseja corrigir, bem como os campos de identidade necessários, você pode seguir as etapas para Assimilar arquivos do Parquet para concluir o patch por meio da assimilação em lote.
Reproduzir um lote novamente
Se quiser substituir um lote já assimilado, faça isso com "repetição em lote". Essa ação equivale a excluir o lote antigo e assimilar um novo.
Criar lote
Primeiro, será necessário criar um lote, com JSON como formato de entrada. Ao criar o lote, será necessário fornecer uma ID de conjunto de dados. Você também precisará garantir que todos os arquivos carregados como parte do lote estejam em conformidade com o esquema XDM vinculado ao conjunto de dados fornecido. Além disso, será necessário fornecer os lotes antigos como referência na seção de repetição. No exemplo abaixo, você está reproduzindo lotes com IDs batchIdA
e batchIdB
.
Formato da API
POST /batches
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
},
"replay": {
"predecessors": ["${batchIdA}","${batchIdB}"],
"reason": "replace"
}
}'
{DATASET_ID}
Resposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"replay": {
"predecessors": [
"batchIdA", "batchIdB"
],
"reason": "replace"
},
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Fazer upload de arquivos
Agora que você criou um lote, poderá usar o batchId
de antes para carregar arquivos no lote. É possível fazer upload de vários arquivos para o lote.
Formato da API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitação
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Resposta
200 OK
Concluir lote
Quando terminar de fazer upload de todas as diferentes partes do arquivo, você precisará sinalizar que os dados foram totalmente carregados e que o lote está pronto para promoção.
Formato da API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Resposta
200 OK
Apêndice
A seção a seguir contém informações adicionais para assimilação de dados no Experience Platform usando a assimilação em lote.
Transformação de dados para assimilação em lote
Para assimilar um arquivo de dados em Experience Platform, a estrutura hierárquica do arquivo deve estar em conformidade com as Experience Data Model (XDM) esquema associado ao conjunto de dados que está sendo carregado.
Informações sobre como mapear um arquivo CSV para estar em conformidade com um esquema XDM podem ser encontradas no exemplos de transformações juntamente com um exemplo de um arquivo de dados JSON formatado corretamente. Os arquivos de exemplo fornecidos no documento podem ser encontrados aqui: