A Carol permite efetuar o consumo de dados do Data Subscription. Esse recurso permite sincronizar dados da Carol para outros ambientes através de uma arquitetura similar ao Web Hook.
Nesta arquitetura, você registra na Carol o seu endpoint preparado para receber os dados da Carol, e quando esse Data Model receber novos registros, atualizações ou eliminação de dados, uma mensagem será enviada ao seu endpoint propagando a ação ocorrida na plataforma Carol.
Esse recurso deve ser utilizado em casos especificos, sendo que normalmente o consumo dos dados na plataforma Carol através de comandos SQL já é suficiente para vários cenários.
Neste capítulo da documentação vamos efetuar os seguintes passos:
Para habilitar o Data Subscription, você deve incluir o endpoint que estará preparado para processar as mensagens enviadas pela Carol. Para isso, abra o módulo Data Model e vá na opção Option e depois Data Subscription:
Na tela que abrir, você poderá efetuar ajustes em Subscriptions existentes ou adicionar novas. Um Data Model pode ter várias subscriptions enviando os dados para endereços diferentes.
Para adicionar uma subscription, você deve informar os seguintes parâmetros:
Propriedade | Descrição |
---|---|
Subscription Name | Nome da subscrição. Deverá ser úncio por Data Model e ele é obrigatório. Este é utilizado como identificador. |
Connector | O conector relacionado ao consumo dos dados. Parâmetro obrigatório. |
Start date & time | Data de início para o recebimento dos dados, este é utilizado para determinar a carga inicial a ser enviada. |
Content-Encoding | Encoding dos dados, podendo sere GZIP ou SNAPPY. |
Webhook URL | A URL do Webhook que vai receber os dados. Essa URL aponta para o endpoint que está preparado para receber requisições POST conforme o content-encoding definido acima. |
Max Batch Size | O tamanho máximo de eventos/registros que será enviado para a URL acima. Batches menores são esperados, sendo que as mensagens são enviadas de forma online. Uma sugestão de valor é 700 ou 1000 mensagens. Quanto maior melhor, e deve haver preocupação quanto ao tempo da URL em processar esses dados antes de alcançar timeout. |
Max in Flight | Número de envio paralelo que pode ocorrer. Neste caso, se o Max Batch estiver definido com 1000 e o Max in Flight estiver com 5, a URL poderá receber, no total, 5000 mensagens paralelamente. Um valor recomendado é 2, ou acima. Atentar se o endpoint acima está preparado para escalar se receber mensagens simultaneamente. |
Max Retries | Este parâmetro define a quantidade máxima de tentativas para entregar a mesma mensagem antes de descartar a mensagem. Este parâmetro é para evitar a Carol tentando entregar repetidamente a mensagem sem o recebimento de ACK (será discutido mais abaixo). Valor padrão 10. |
Headers | Caso seja necessário algum header para o endpoint acima, este deverá estar especificado nesta lista. |
Exemplo de configuração:
Com essa configuração estamos preparados para receber dados da Carol. Agora é necessário o processamento de dados na plataforma para que os dados sejam recebidos.
Simulador Endpoint
Você pode utilizar o http://pipedream.com/ para simular a criação de um endpoint e executar os testes descritos neste capítulo.
A Carol efetua o envio de mensagens no formato abaixo:
{ "messageId": "2453103412224342", "publishedAt": "2021-05-28T22:38:56.188538Z", "records": [ { "mdmCounterForEntity": 1622241532763000, "mdmCreated": "2021-05-28T22:38:52.763Z", "mdmDeleted": false, "mdmEntityTemplateId": "eec1dd50a14546a6894e7636ba03f62f", "mdmEntityType": "apinvoiceaccountingGolden", "mdmGoldenFieldAndValues": { "amount": 1000, "account_id": "f768115f14863655f390e996d125699b", "invoice_id": "40b090c2867f26aa6f13918430e5a58c", "invoiceaccounting_id": "00434889e9627d466ecf4f40da482921", "_orgid": "1728332a9cddf2f391aa7b48a23255e2", "costcenter_id": "be1f4298cd0eb0733a7c92bb3a8ae034" }, "mdmId": "d3f1c0cf246bf087ff001a1d98dc4125", "mdmLastUpdated": "2021-05-28T22:38:52.763Z", "mdmMasterCount": 1, "mdmPreviousIds": [], "mdmTenantId": "3895e1c66df14611bc017a69594a3894" } ], "subscriptionId": "624bccd237c44ddc883bbc7689c4bd83", "subscriptionName": "apinvoiceaccounting", "subscriptionType": "GOLDEN", "tenantId": "3895e1c66df14611bc017a69594a3894" }
Observações sobre a mensagem recebida:
Feature Flag Propagação de Mensagens de eliminação
A propagação de mensagens quando registros são eliminados eram feitos pelo parâmetro "mdmSubscriptionDeletesEnabled". Porém o mesmo foi removido da plataforma, uma vez que uma vez deletados, a plataforma envia por padrão esta mensagem de notificação de deletados.
Formas de responder mensagens recebidas (ACK):
Respondendo ACK para todos os registros recebidos:
{ "ack": true }
Respondendo ACK e informando registros que devem ser reenviados:
{ "ack": true, "redeliverRecordIds": [ "{golden_record_id_1}", "{golden_record_id_2}" ] }
Respondendo ACK falso e informando o motivo:
{ "ack": false, "message": "Failed constraint xyz" }
Você pode monitorar o envio de mensagens pelo Data Subscription através do Carol Insights Studio, pelo link: https://carol.ai/insights/dashboard/102
Informações disponíveis:
É possível customizar a query para filtrar dados em especifico e facilitar o processo de debug.
O repositório abaixo possui um exemplo implementado em NodeJS que abre uma API para receber mensagens do Data Subscription.
https://github.com/totvslabs/caroljs/
Se você tiver alguma dúvida ou sugestão, você pode enviar através do projteto no Github.
Agora você deve praticar o ciclo de vida dos dados na Carol, desde o processo de injestão de dados até o consumo através de recursos SQL ou Data Subscription. Se tiver alguma dúvida, abra um chamado no Zendesk.