GET /v1/reports/{id}.
GET /v1/streaming/events descreve o contrato em formato legível por máquina. Esta página cobre o lado do consumidor: o que o manifesto informa, o que chega pela rede e o que cada evento carrega.
A operação de manifesto
Eventos de streaming retorna o catálogo estático de eventos. Essa operação exige autenticação como qualquer outra. Ela responde com
Cache-Control: no-store e responde independentemente de este deploy publicar eventos ou não. Leia-a na inicialização para conferir se o seu consumidor e o Reporter concordam quanto ao contrato.
A resposta expõe a identidade da aplicação e o catálogo:
Roteamento no broker
O manifesto não revela um tópico nem a topologia do broker. Vincule sua fila ao exchange nomeado por
RABBITMQ_REPORT_EVENTS_EXCHANGE. Cada mensagem usa a chave da definição de evento ao pé da letra como sua routing key AMQP: report.finished, deadline.delivery_reverted, incluindo os sublinhados.
O catálogo de eventos
Existem doze definições de evento nos dois modos de execução.
Esse canal é apenas para publicação. O Reporter emite esses eventos e não consome nenhum deles.
Entrega
Todo evento do manifesto tem a classe
fact. O perfil de entrega na tabela acima seleciona sua política de entrega.
Por isso, um evento com o perfil de entrega
Critical nunca publica diretamente no broker. O Reporter grava o evento no outbox de streaming durável do Mongo depois do commit do estado de negócio, e um dispatcher o reproduz depois de uma interrupção do broker.
A gravação do estado e a inserção no outbox são operações separadas, não uma única transação atômica da aplicação. Essa lacuna é uma janela de falha: uma queda ou uma inserção com falha no outbox depois do commit do estado perde o evento. Nenhuma conciliação o recupera. A perda deixa apenas um log de erro e uma métrica. Depois que a linha está no outbox, o dispatcher faz novas tentativas até a entrega.
A política solicita tratamento de dead-letter para falhas roteáveis, mas as rotas atuais do RabbitMQ não fornecem um destino DLQ explícito. Essa falha é exposta e registrada em log, sem cópia forense em dead-letter.
A emissão acontece depois do commit e nunca faz o trabalho falhar. Um problema de publicação não transforma um relatório armazenado em um relatório com erro.
O envelope CloudEvents
As mensagens trafegam no modo binário do CloudEvents, versão 1.0. Os atributos de contexto viajam como headers da mensagem.
O Reporter marca as mensagens como persistentes. Um deploy single-tenant também registra um valor de tenant, então um único consumidor lida com os dois formatos de deploy com o mesmo código.
O que um payload carrega
As chaves do payload são em
snake_case, diferente da superfície REST em camelCase. Um corpo de report.finished:
artifact_object_key é a chave exata do objeto informada pelo storage depois da gravação, não um caminho que se recomenda que os consumidores reconstruam. No modo single-tenant, ela tem a forma reports/<templateId>/<reportId>.<format>. O modo multi-tenant prefixa o mesmo caminho com o segmento do tenant. Use o valor ao pé da letra.
Se você validar o segmento de tenant, compare-o com o tenant vinculado à sua subscription autenticada, não com outro campo da mesma mensagem. Uma chave vazia em report.finished ou report.partial é uma violação de contrato. Baixar um relatório continua sendo a forma aceita para buscar um relatório no estado Finished.
report.partial adiciona section_failures e failed_section_count junto com os mesmos campos de artefato. Uma chave resolvível não significa que o relatório está completo. Encaminhe a entrega regulatória apenas a partir de report.finished, e decodifique estritamente o campo status em vez de usar a presença da chave como discriminador.
report.errored substitui os campos de artefato por error_code e error_summary. A ausência de um campo de artefato não prova que nenhum objeto foi gravado: o storage pode ter sucesso antes que a persistência do status terminal falhe, deixando um objeto que nenhum evento nomeia. Os dois campos de erro vêm de um vocabulário fixo: report_generation_failed, report_generation_timeout ou report_generation_canceled. Cada código tem um resumo fixo. O texto bruto do erro nunca trafega na rede, então um payload não pode vazar uma query, uma connection string ou dados de tenant. Ramifique a lógica com base em error_code.
Habilitando a publicação de eventos
A publicação de eventos é uma escolha de deploy, definida com
STREAMING_ENABLED. Ao ativá-la, o Reporter exige mais três configurações na inicialização:
Quando a publicação está desativada,
STREAMING_CLOUDEVENTS_SOURCE pode ficar sem valor definido. Se estiver definida, ainda deve ser exatamente reporter. O Reporter rejeita qualquer outro valor não vazio na inicialização, mesmo com a publicação desativada. Quando a publicação está ativada, o Reporter também se recusa a iniciar se qualquer uma das três configurações estiver em branco, então um deploy malconfigurado falha na inicialização em vez de descartar eventos silenciosamente.
Próximos passos
Reporter REST API
As 28 operações, autenticação, paginação e erros.
Referência da API
A operação de manifesto de streaming, com seu formato de resposta completo.
Variáveis de ambiente
Todas as configurações por trás das superfícies de streaming, exchange e modo de execução.
O que é o Reporter?
Templates, relatórios, prazos e onde eles se encaixam.