Esta documentação ajudará a responder às perguntas frequentes sobre o Adobe Experience Platform Batch Data Ingestion APIs.
A variável 200 OK
A resposta da API significa que o lote foi aceito para processamento - ele não estará ativo até fazer a transição para seu estado final, como Ativo ou Falha.
Sim - é seguro tentar novamente a chamada da API. Apesar da falha, é possível que a operação tenha sido bem-sucedida e o lote tenha sido aceito com êxito. No entanto, espera-se que os clientes tenham mecanismos de repetição em caso de falha da API e, na verdade, são incentivados a tentar novamente. Se a operação for bem-sucedida, a API retornará com êxito, mesmo após uma nova tentativa.
O tamanho de arquivo recomendado para usar a API de Upload de arquivo grande é 256 MB ou maior. Mais informações sobre como usar a API de upload de arquivo grande podem ser encontradas aqui.
Se partes de um arquivo grande estiverem sobrepostas ou ausentes, o servidor responderá com uma solicitação HTTP 400 incorreta. Isso pode ocorrer porque é possível carregar partes sobrepostas, já que as validações de intervalo são feitas no momento da conclusão do arquivo, quando as partes do arquivo são unidas.
Atualmente, o Parquet e o JSON são compatíveis. O CSV é compatível com base no legado — embora os dados sejam promovidos para verificações principais e preliminares sejam feitas, nenhum recurso moderno, como conversão, particionamento ou validação de linha é compatível.
O formato de entrada deve ser especificado no momento da criação do lote dentro da carga. Um exemplo de como especificar o formato de entrada de lote pode ser visto abaixo:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
Para que os dados apareçam no conjunto de dados, o lote deve ser marcado como concluído. Todos os arquivos que você deseja assimilar devem ser carregados antes de marcar o lote como concluído. Um exemplo de marcação de um lote como concluído pode ser visto abaixo:
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}'
Para assimilar JSON de várias linhas, a variável isMultiLineJson
O sinalizador precisa ser definido no momento da criação do lote. Um exemplo disso pode ser visto abaixo:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json",
"isMultiLineJson": true
}
}'
Para linhas JSON, há um objeto JSON por linha. Por exemplo:
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}
Para JSON de várias linhas, um objeto pode ocupar várias linhas, enquanto todos os objetos são envolvidos em uma matriz JSON. Por exemplo:
[
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
{
"string": "string3",
"int": 3,
"array": [
3,
6,
9
],
"dict": {
"key": "value3",
"extra_key": "extra_value3"
}
}
]
Por padrão, Batch Data Ingestion usa JSON de linha única.
A assimilação de CSV só é compatível com esquemas simples. Atualmente, a assimilação de dados hierárquicos em CSV não é suportada.
Para obter todos os recursos de assimilação de dados, é necessário usar os formatos JSON ou Parquet.
Há três níveis de validação executados nos dados:
Um lote já assimilado pode ser substituído usando o recurso Repetição de lote. Mais informações sobre Repetição em Lote podem ser encontradas aqui.
Depois que um lote tiver sido sinalizado para a promoção de lotes, o progresso da assimilação de lotes poderá ser monitorado com a seguinte solicitação:
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
Com essa solicitação, você receberá uma resposta semelhante a esta:
200 OK
{
"{BATCH_ID}":{
"imsOrg":"{ORG_ID}",
"created":1494349962314,
"createdClient":"{API_KEY}",
"createdUser":"{USER_ID}",
"updatedUser":"{USER_ID}",
"completed":1494349963467,
"externalId":"{EXTERNAL_ID}",
"status":"staging",
"errors":[],
}
}
Um lote pode, em seu ciclo de vida, passar pelos seguintes estados:
Status | Dados gravados no Principal | Descrição |
---|---|---|
Abandonado | O cliente falhou ao concluir o lote no período de tempo esperado. | |
Anulado | O cliente chamou explicitamente o, por meio da variável Batch Data Ingestion APIs, uma operação de anulação para o lote especificado. Quando um lote está no estado Carregado, ele não pode ser anulado. | |
Ativo/sucesso | x | O lote foi promovido com sucesso do estágio para o principal e agora está disponível para consumo downstream. Nota: Ativo e Sucesso são usados alternadamente. |
Arquivado | O lote foi arquivado no armazenamento frio. | |
Com falha/Falha | Um estado terminal que resulta de uma configuração incorreta e/ou de dados incorretos. Um erro acionável é registrado junto com o lote para permitir que os clientes corrijam e reenviem os dados. Nota: Failed (Falha) e Failure (Falha) são usados alternadamente. | |
Inativo | x | O lote foi promovido com sucesso, mas foi revertido ou expirou. O lote não estará mais disponível para consumo downstream, mas os dados subjacentes permanecerão Principais até que tenham sido retidos, arquivados ou excluídos de alguma outra forma. |
Carregando | No momento, o cliente está gravando dados para o lote. O lote é não pronto para promoção, neste momento. | |
Carregado | O cliente concluiu a gravação de dados para o lote. O lote está pronto para promoção. | |
Retido | Os dados foram retirados do Principal e em um arquivo designado no Adobe Data Lake. | |
Armazenamento temporário | O cliente sinalizou com êxito o lote para promoção e os dados estão sendo preparados para consumo downstream. | |
Tentando novamente | O cliente sinalizou o lote para promoção, mas devido a um erro, o lote está sendo repetido por um serviço de Monitoramento de Lote. Esse estado pode ser usado para informar aos clientes que pode haver um atraso na assimilação dos dados. | |
Paralisado | O cliente sinalizou o lote para promoção, mas depois n tentativas feitas por um serviço de Monitoramento de Lote, a promoção do lote foi interrompida. |
Quando um lote está em "Preparo", significa que ele foi sinalizado com êxito para promoção e que os dados estão sendo preparados para consumo downstream.
Quando um lote está em "Tentando novamente", significa que a assimilação de dados do lote foi temporariamente interrompida devido a problemas intermitentes. Quando isso acontece, não é necessária a intervenção do cliente.
Quando um lote está em "Paralisado", significa que Data Ingestion Services O está tendo dificuldade para assimilar o lote e todas as tentativas foram esgotadas.
Quando um lote está em "Carregando", significa que a API CompleteBatch não foi chamada para promover o lote.
Quando o status do lote for "Ativo", ele será assimilado com êxito. Para descobrir o status do lote, siga as etapas detalhadas anterior.
Quando um lote falha, o motivo da falha pode ser identificado na variável errors
seção da carga útil. Exemplos de erros podem ser vistos abaixo:
"errors":[
{
"code":"106",
"description":"Dataset file is empty. Please upload file with data.",
"rows":[]
},
{
"code":"118",
"description":"CSV file contains empty header row.",
"rows":[]
}
]
Depois que os erros forem corrigidos, o lote poderá ser recarregado.
Em vez de excluir diretamente de Catalog, os lotes devem ser removidos utilizando qualquer um dos métodos abaixo indicados:
As seguintes métricas em nível de lote estão disponíveis para lotes no estado Ativo/Sucesso:
Métrica | Descrição |
---|---|
inputByteSize | O número total de bytes preparados para Data Ingestion Services para processar. |
inputRecordSize | O número total de linhas preparadas para Data Ingestion Services para processar. |
outputByteSize | O número total de bytes de saída por Data Ingestion Services para Data Lake. |
outputRecordSize | O número total de linhas geradas por Data Ingestion Services para Data Lake. |
partitionCount | O número total de partições gravadas em Data Lake. |
Há dois motivos pelos quais as métricas podem não estar disponíveis em seu lote:
Código de status | Descrição |
---|---|
106 | O arquivo de conjunto de dados está vazio. |
118 | O arquivo CSV contém uma linha de cabeçalho vazia. |
200 | O lote foi aceito para processamento e passará para um estado final, como Ativo ou Falha. Após o envio, o lote pode ser monitorado com o uso da GetBatch terminal. |
400 | Solicitação inválida. Retornado se houver partes ausentes ou sobrepostas em um lote. |