Visão geral da API de assimilação em lote

A API de assimilação de dados do Adobe Experience Platform permite assimilar dados na Platform como arquivos em lote. Os dados que estão sendo assimilados podem ser dados de perfil de um arquivo simples (como um arquivo Parquet) ou dados que estão em conformidade com um esquema conhecido na Experience Data Model Registro (XDM).

O Referência da API da assimilação de dados O fornece informações adicionais sobre essas chamadas de API.

O diagrama a seguir descreve o processo de ingestão em lote:

Introdução

Os endpoints de API usados neste guia fazem parte do API de assimilação de dados. Antes de continuar, reveja o guia de introdução para 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 API do Experience Platform.

Data Ingestion pré-requisitos

  • Os dados para fazer upload devem estar nos formatos Parquet ou JSON.
  • Um conjunto de dados criado na Catalog services.
  • O conteúdo do arquivo Parquet deve corresponder a um subconjunto do esquema do conjunto de dados no qual o upload está sendo feito.
  • Ter seu Token de acesso exclusivo após a autenticação.

Práticas recomendadas de assimilação de lote

  • O tamanho de lote recomendado é entre 256 MB e 100 GB.
  • Cada lote deve conter no máximo 1500 arquivos.

Restrições de assimilação em lote

A assimilação de dados em lote tem algumas restrições:

  • Número máximo de arquivos por lote: 1500
  • Tamanho máximo do lote: 100 GB
  • Número máximo de propriedades ou campos por linha: 10000
  • Número máximo de lotes por minuto, por usuário: 138
OBSERVAÇÃO

Para carregar um arquivo com mais de 512 MB, o arquivo precisará ser dividido em partes menores. Instruções para carregar um arquivo grande podem ser encontradas no seção de upload de arquivo grande deste documento.

Tipos

Ao assimilar dados, é importante entender como Experience Data Model Os esquemas (XDM) funcionam. Para obter mais informações sobre como os tipos de campos XDM mapeiam para diferentes formatos, leia o Guia do desenvolvedor do Registro de Schema.

Há alguma flexibilidade na assimilação de dados - se um tipo não corresponder ao que está no schema de target, os dados serão convertidos para o tipo de target expresso. Se não puder, ocorrerá uma falha no lote com um TypeCompatibilityException.

Por exemplo, nem JSON nem CSV têm um date ou date-time tipo . Como resultado, esses valores são expressos usando Strings formatadas ISO 8061 ("2018-07-10T15:05:59.000-08:00") ou Tempo Unix formatado em milissegundos (1531263959000) e são convertidos no momento da assimilação para o tipo XDM de destino.

A tabela abaixo mostra as conversões suportadas ao assimilar dados.

Entrada (linha) vs Destino (col) String Byte Curto Número inteiro Longo Duplo Data Data e hora Objeto Mapa
String X X X X X X X X
Byte X X X X X X
Curto X X X X X X
Número inteiro X X X X X X
Longo X X X X X X X X
Duplo X X X X X X
Data X
Data e hora X
Objeto X X
Mapa X X
OBSERVAÇÃO

Booleanos e matrizes não podem ser convertidos em outros tipos.

Uso da API

O Data Ingestion A API permite assimilar dados como lotes (uma unidade de dados que consiste em um ou mais arquivos a serem assimilados como uma única unidade) em Experience Platform em três etapas básicas:

  1. Crie um novo lote.
  2. Faça upload de arquivos para um conjunto de dados especificado que corresponda ao esquema XDM dos dados.
  3. Sinaliza o fim do lote.

Criar um lote

Antes que os dados possam ser adicionados a um conjunto de dados, eles devem ser vinculados a um lote, que será carregado posteriormente em um conjunto de dados especificado.

POST /batches

Solicitação

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "Content-Type: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}"
      }'
Propriedade Descrição
datasetId A ID do conjunto de dados no qual os arquivos serão carregados.

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}"
}
Propriedade Descrição
id A ID do lote que acabou de ser criado (usada em solicitações subsequentes).
relatedObjects.id A ID do conjunto de dados no qual os arquivos serão carregados.

Upload de arquivo

Depois de criar com êxito um novo lote para upload, os arquivos podem ser carregados em um conjunto de dados específico.

Você pode fazer upload de arquivos usando a API de upload de arquivo pequeno. No entanto, se os arquivos forem muito grandes e o limite do gateway for excedido (como tempos limite estendidos, solicitações para o tamanho do corpo excedido e outras restrições), você poderá alternar para a API de upload de arquivo grande. Essa API faz o upload do arquivo em blocos e une os dados usando a chamada de API de Upload de Arquivo Grande Concluído.

OBSERVAÇÃO

A assimilação em lote pode ser usada para atualizar gradualmente os dados na Loja de perfis. Para obter mais informações, consulte a seção em atualização de um lote no guia do desenvolvedor de ingestão em lote.

INFORMAÇÕES

Os exemplos abaixo usam a variável Apache Parquet formato de arquivo. Um exemplo que usa o formato de arquivo JSON pode ser encontrado no guia do desenvolvedor de ingestão em lote.

Upload de arquivo pequeno

Depois que um lote é criado, os dados podem ser carregados em um conjunto de dados preexistente. O arquivo que está sendo carregado deve corresponder ao esquema XDM referenciado.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Propriedade Descrição
{BATCH_ID} A ID do lote.
{DATASET_ID} A ID do conjunto de dados para fazer upload de arquivos.
{FILE_NAME} O nome do arquivo como será visto no conjunto de dados.

Solicitação

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Propriedade Descrição
{FILE_PATH_AND_NAME} O caminho e o nome do arquivo a ser carregado no conjunto de dados.

Resposta

#Status 200 OK, with empty response body

Upload de arquivo grande - criar arquivo

Para carregar um arquivo grande, o arquivo deve ser dividido em partes menores e carregado um de cada vez.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize
Propriedade Descrição
{BATCH_ID} A ID do lote.
{DATASET_ID} A ID do conjunto de dados que assimila os arquivos.
{FILE_NAME} O nome do arquivo como será visto no conjunto de dados.

Solicitação

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Resposta

#Status 201 CREATED, with empty response body

Carregamento de arquivo grande - carregue as partes subsequentes

Após a criação do arquivo, todos os fragmentos subsequentes podem ser carregados fazendo solicitações PATCH repetidas, uma para cada seção do arquivo.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Propriedade Descrição
{BATCH_ID} A ID do lote.
{DATASET_ID} A ID do conjunto de dados no qual os arquivos serão carregados.
{FILE_NAME} Nome do arquivo como será visto no conjunto de dados.

Solicitação

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Propriedade Descrição
{FILE_PATH_AND_NAME} O caminho e o nome do arquivo a ser carregado no conjunto de dados.

Resposta

#Status 200 OK, with empty response

Conclusão do lote de sinais

Depois que todos os arquivos tiverem sido carregados no lote, o lote poderá ser sinalizado para conclusão. Ao fazer isso, a variável Catalog As entradas DataSetFile são criadas para os arquivos concluídos e associadas ao lote gerado acima. O Catalog em seguida, o lote é marcado como bem-sucedido, o que aciona os fluxos downstream para assimilar os dados disponíveis.

Solicitação

POST /batches/{BATCH_ID}?action=COMPLETE
Propriedade Descrição
{BATCH_ID} A ID do lote a ser carregado no conjunto de dados.
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Resposta

#Status 200 OK, with empty response

Verificar status do lote

Enquanto aguarda os arquivos serem carregados no lote, o status do lote pode ser verificado para ver seu progresso.

Formato da API

GET /batch/{BATCH_ID}
Propriedade Descrição
{BATCH_ID} A ID do lote que está sendo verificado.

Solicitação

curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Resposta

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}
Propriedade Descrição
{USER_ID} A ID do usuário que criou ou atualizou o lote.

O "status" é o que mostra o status atual do lote solicitado. Os lotes podem ter um dos seguintes estados:

Status de assimilação em lote

Status Descrição
Abandonado O lote não foi concluído no período de tempo esperado.
Abortado Uma operação abort tem explicitamente foi chamado (por meio da API de assimilação de lote) para o lote especificado. Quando o lote estiver em um estado "Carregado", ele não poderá ser anulado.
Ativo O lote foi promovido com êxito e está disponível para consumo downstream. Esse status pode ser usado alternadamente com "Sucesso".
Excluído Os dados do lote foram completamente removidos.
Falha Um estado de terminal que resulta de uma configuração incorreta e/ou dados incorretos. Os dados de um lote com falha serão not aparecer. Esse status pode ser usado alternadamente com "Falha".
Inativo O lote foi promovido com êxito, mas foi revertido ou expirou. O lote não está mais disponível para consumo downstream.
Carregado Os dados do lote estão completos e o lote está pronto para promoção.
Carregamento Os dados deste lote estão sendo carregados e o lote está no momento not pronto para ser promovido.
Tentando novamente Os dados desse lote estão sendo processados. No entanto, devido a um erro transitório ou de sistema, o lote falhou - como resultado, esse lote está sendo repetido.
Preparado A fase de preparo do processo de promoção para um lote está concluída e o trabalho de assimilação foi executado.
Armazenamento temporário Os dados do lote estão sendo processados.
Paralisado Os dados do lote estão sendo processados. No entanto, a promoção em lote parou após várias tentativas.

Nesta página