Platform For AI:Queue service subscription and pushing

A assinatura e o push enviam dados prontos imediatamente ao cliente, o que reduz a latência causada por polling via Get API e diminui a carga no service de fila gerada por consultas frequentes. No entanto, esse recurso apresenta certa complexidade, pois envolve diversos conceitos adicionais. Este tópico descreve como utilizar a funcionalidade de assinatura e push do service de fila.

Consumer

Um consumer é um programa cliente que assina dados do service de fila. Quando o cliente utiliza a Watch API para solicitar dados, o service de fila cria um objeto consumer. Os parâmetros da API (como tamanho da janela e tags) tornam-se atributos desse consumer. Para visualizar o status do consumer, utilize a Attribute API. Exemplo:

[OK] Attributes: 
consumers.list.[0] : Id: default_group.u1, Index: 0, Pending: 0, Status: Complete, Idle: 2.091s, Window: 0, Slots: 0, AutoCommit: true
consumers.list.[1] : Id: default_group.u2, Index: 0, Pending: 0, Status: Complete, Idle: 1.124s, Window: 0, Slots: 0, AutoCommit: true
consumers.stats.total : 2

consumers.stats.total indica o número total de consumers. consumers.list representa a lista de consumers. A tabela a seguir descreve as colunas:

Ao utilizar a Watch API com a tag de dados, uma coluna adicional chamada Tags será exibida. Exemplo:

consumers.list.[0] : Id: ..., Pending: 0, ..., Window: ..., Tags: tags[foo=bar]

Essa coluna indica as tags de dados assinadas pelo consumer. Os dados são entregues ao consumer apenas quando atendem às condições especificadas.

Consumer group

Um consumer group é um conjunto de consumers que assinam o service de fila com as mesmas condições de filtro. Consumers dentro do mesmo grupo não podem ter nomes idênticos, mas consumers em grupos diferentes podem compartilhar o mesmo nome.

Dentro de um mesmo consumer group, os dados são distribuídos uniformemente entre os consumers. Entre grupos distintos, os dados são enviados via push em paralelo para os consumers de cada grupo. Por exemplo:

• Consumers no mesmo grupo recebem dados diferentes.

• Consumers em grupos diferentes recebem os mesmos dados.

Para visualizar o status do consumer no service de fila, utilize a Attribute API. Veja o exemplo abaixo:

groups.list.[0] : Id: default_group, Index: 0, Pending: 0, Delivered: 0, Consumers: 1
groups.list.[1] : Id: group, Index: 0, Pending: 0, Delivered: 1, Consumers: 0

groups.list corresponde à lista de consumers. A tabela a seguir detalha as colunas:

Não há limite para o número de consumer groups, mas eles não são limpos automaticamente. Após a criação, o status é mantido permanentemente.

Uso de consumers e consumer groups

Declare o consumer e o consumer group por meio de cabeçalhos HTTP na Watch API ou durante a inicialização do cliente no SDK. Também é possível obter a chave do cabeçalho HTTP usando a Attributes API.

meta.header.group : X-EAS-QueueService-Gid
meta.header.user : X-EAS-QueueService-Uid

Declare o ID do consumer e o ID do consumer group ao qual deseja ingressar utilizando, respectivamente, X-EAS-QueueService-Uid e X-EAS-QueueService-Gid.

Commit e Negative

O service de fila oferece suporte a dois métodos de consumo: Commit e Negative. Ambos operam sobre o Index dos dados, mas possuem semânticas distintas.

• Commit sinaliza que o consumer recebeu os dados e concluiu o processamento, permitindo o envio do próximo lote via push.

• Negative indica que o consumer recebeu os dados, mas não conseguiu processá-los. Nesse caso, o service de fila decide se deve enviar o próximo lote com base no código de erro. No modo Negative, declare a causa e o código de erro em texto para redirecionar os dados a outros consumers. A tabela abaixo lista os códigos de erro especiais tratados pelo service de fila:

  Code	Description
  Shutdown	Indica que o consumer está saindo e o service de fila deve interromper o envio de dados.

Rebalanceamento de dados

Em alguns cenários, pode não ser possível confirmar (commit) os dados:

• Durante uma atualização contínua (rolling update) do service de previsão, alguns consumers são encerrados, deixando dados em processamento sem confirmação.

• Ocorre um erro interno e o consumer falha.

• O consumer não consegue processar os dados recebidos e executa um commit do tipo Negative.

O service de fila redistribui os dados não processados para outros consumers. Esse mecanismo é chamado de rebalanceamento de dados. O rebalanceamento ocorre nas seguintes situações:

• Qualquer consumer entra no estado Exit.

• O consumer não recebe novos dados via push mesmo havendo espaço ocioso na janela.

O service de fila mantém um contador de entregas para cada dado. Sempre que os dados são rebalanceados e redistribuídos, esse contador é incrementado. Se, durante o rebalanceamento, o contador de entregas de um dado ultrapassar o número máximo permitido, o dado é tratado como dead letter. O service de fila então aplica a política de dead letter configurada. Por padrão, os dados são enviados para a tail queue.

Tail queue

A tail queue é uma fila auxiliar usada para armazenar dados não enviados aos consumers (como dead letters ou dados de controle personalizados). Trata-se de uma instância de fila dentro do próprio service de fila, com a mesma API disponível. Cada fila de entrada e saída possui sua própria tail queue.

Ao chamar a API, declare o acesso à tail queue adicionando o seguinte cabeçalho HTTP:

X-EAS-QueueService-Access-Rear: true