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

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

A Referência da API de assimilação em lote fornece informações adicionais sobre essas chamadas de API.

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

Introdução

Os pontos de extremidade de API usados neste guia fazem parte da API de assimilação em lote. Antes de continuar, consulte 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 para qualquer API Experience Platform com êxito.

Data Ingestion pré-requisitos

Práticas recomendadas de assimilação em lote

Restrições de assimilação em lote

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

Tipos

Ao assimilar dados, é importante entender como os esquemas do Experience Data Model (XDM) funcionam. Para obter mais informações sobre como os tipos de campo XDM são mapeados para formatos diferentes, leia o guia do desenvolvedor do Registro de Esquemas.

Há alguma flexibilidade ao assimilar dados - se um tipo não corresponder ao que está no esquema do público-alvo, os dados serão convertidos no tipo de público-alvo expresso. Se não puder, haverá falha no lote com um TypeCompatibilityException.

Por exemplo, nem JSON nem CSV têm um tipo date ou date-time. Como resultado, esses valores são expressos usando cadeias de caracteres formatadas em ISO 8601 ("2018-07-10T15:05:59.000-08:00") ou Tempo Unix formatados 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 compatíveis ao assimilar dados.

Uso da API

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

Criar um lote

Para que os dados possam ser adicionados a um conjunto de dados, eles devem estar 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}"
      }'

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

Upload de arquivo

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

É possível 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 de tamanho do corpo excedido e outras restrições), você poderá alternar para a API de upload de arquivo grande. Essa API faz upload do arquivo em partes e compila os dados usando a chamada de API Upload de arquivo grande concluído.

Upload de arquivo pequeno

Após a criação de um lote, 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}

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"

Resposta

#Status 200 OK, with empty response body

Upload de arquivo grande - criar arquivo

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

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize

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

Upload de arquivo grande - carregar partes subsequentes

Após a criação do arquivo, é possível fazer upload de todos os blocos subsequentes fazendo solicitações PATCH repetidas, uma para cada seção do arquivo.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

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"

Resposta

#Status 200 OK, with empty response

Sinal de conclusão de lote

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

Solicitação

POST /batches/{BATCH_ID}?action=COMPLETE

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}

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

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

Status de assimilação em lote