Validação de assimilação de streaming
A assimilação de streaming permite fazer upload de dados no Adobe Experience Platform usando endpoints de streaming em tempo real. As APIs de assimilação de streaming são compatíveis com dois modos de validação - síncrono e assíncrono.
Introdução
Este guia requer uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
- Experience Data Model (XDM) System: o quadro normalizado pelo qual Experience Platform organiza os dados de experiência do cliente.
- Streaming Ingestion: um dos métodos pelos quais os dados podem ser enviados para o Experience Platform.
Leitura de chamadas de API de amostra
Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O exemplo de JSON retornado nas respostas da API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de exemplo, consulte a seção sobre como ler chamadas de API de exemplo no Experience Platform guia de solução de problemas.
Coletar valores para cabeçalhos obrigatórios
Para fazer chamadas para Platform APIs, primeiro conclua o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todos os Experience Platform Chamadas de API, conforme mostrado abaixo:
- Autorização: Portador
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Todos os recursos em Experience Platform, incluindo as que pertencem à Schema Registry, são isolados em sandboxes virtuais específicas. Todas as solicitações para Platform As APIs exigem um cabeçalho que especifique o nome da sandbox em que a operação ocorrerá:
- x-sandbox-name:
{SANDBOX_NAME}
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho adicional:
- Tipo de conteúdo:
application/json
Cobertura de validação
Streaming Validation Service abrange a validação nas seguintes áreas:
- Intervalo
- Presença
- Enum
- Padrão
- Tipo
- Formato
Validação síncrona
A validação síncrona é um método de validação que fornece feedback imediato sobre por que uma assimilação falhou. No entanto, após a falha, os registros que falham na validação são descartados e impedidos de serem enviados para o downstream. Como resultado, a validação síncrona só deve ser usada durante o processo de desenvolvimento. Ao fazer a validação síncrona, os chamadores são informados sobre o resultado da validação do XDM e, se falhar, o motivo da falha.
Por padrão, a validação síncrona não está ativada. Para habilitá-lo, você deve transmitir o parâmetro de consulta opcional syncValidation=true
ao fazer chamadas de API. Além disso, a validação síncrona está disponível no momento apenas se o terminal de fluxo estiver no data center do VA7.
syncValidation
o parâmetro de consulta só está disponível para o endpoint de mensagem única e não pode ser usado para o endpoint do lote.Se uma mensagem falhar durante a validação síncrona, ela não será gravada na fila de saída, o que fornece feedback imediato para os usuários.
Formato da API
POST /collection/{CONNECTION_ID}?syncValidation=true
{CONNECTION_ID}
id
valor da conexão de streaming criada anteriormente.Solicitação
Envie a seguinte solicitação para assimilar dados na entrada de dados com validação síncrona:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{JSON_PAYLOAD}
Resposta
Com a validação síncrona ativada, uma resposta bem-sucedida inclui todos os erros de validação encontrados em sua carga:
{
"type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
"status": 400,
"title": "Invalid XDM Message Format",
"report": {
"message": "inletId: [6aca7aa2d87ebd6b2780ca5724d94324a14475f140a2b69373dd5c714430dfd4] imsOrgId: [7BF122A65C5B3FE40A494026@AdobeOrg] Message is invalid",
"cause": {
"_streamingValidation": [
{
"schemaLocation": "#",
"pointerToViolation": "#",
"causingExceptions": [
{
"schemaLocation": "#",
"pointerToViolation": "#",
"causingExceptions": [],
"keyword": "additionalProperties",
"message": "extraneous key [workEmail] is not permitted"
},
{
"schemaLocation": "#",
"pointerToViolation": "#",
"causingExceptions": [],
"keyword": "additionalProperties",
"message": "extraneous key [person] is not permitted"
},
{
"schemaLocation": "#/properties/_id",
"pointerToViolation": "#/_id",
"causingExceptions": [],
"keyword": "type",
"message": "expected type: String, found: Long"
}
],
"message": "3 schema violations found"
}
]
}
}
}
A resposta acima lista quantas violações de esquema foram encontradas e quais foram as violações. Por exemplo, essa resposta indica que as chaves workEmail
e person
não foram definidas no esquema e, portanto, não são permitidas. Também sinaliza o valor para _id
como incorreto, já que o esquema esperava um string
, mas uma long
foi inserido. Observe que, quando cinco erros forem encontrados, o serviço de validação stop processando essa mensagem. No entanto, outras mensagens continuarão sendo analisadas.
Validação assíncrona
A validação assíncrona é um método de validação que não fornece feedback imediato. Em vez disso, os dados são enviados para um lote com falha no Data Lake para evitar a perda de dados. Esses dados com falha podem ser recuperados posteriormente para análise adicional e repetição. Esse método deve ser usado na produção. A menos que solicitado de outra forma, a assimilação por transmissão opera no modo de validação assíncrono.
Formato da API
POST /collection/{CONNECTION_ID}
{CONNECTION_ID}
id
valor da conexão de streaming criada anteriormente.Solicitação
Envie a seguinte solicitação para assimilar dados na entrada de dados com validação assíncrona:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{JSON_PAYLOAD}
Resposta
Com a validação assíncrona ativada, uma resposta bem-sucedida retorna o seguinte:
{
"inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
"xactionId": "1555445493896:8600:8",
"receivedTimeMs": 1555445493932,
"syncValidation": {
"skipped": true
}
}
Observe como a resposta indica que a validação síncrona foi ignorada, pois não foi explicitamente solicitada.
Apêndice
Esta seção contém informações sobre o que os vários códigos de status significam para respostas para assimilação de dados.