Enviando e consumindo mensagens

O recebimento é uma concessão temporária. O consumidor deve confirmar após processar com sucesso. Se parar ou a concessão vencer antes, outro consumidor pode receber. Projete a operação para tolerar essa reentrega.

Enviar e receber

Console
API
CLI
Go

Abra a fila e selecione Send message para publicar manualmente. A aba Messages permite inspecionar sem concessão. Execute consumidores pela API; inspecionar não é processar.

Envie uma mensagem para a fila:

POST /v1/queues/{queue_id}/messages
Content-Type: application/json

{
  "body": "{\"order_id\":\"A-1001\"}",
  "attributes": {
    "event": { "type": "String", "value": "order.paid" }
  }
}

HTTP 201 retorna um result com o ID da mensagem. Receba trabalho com:

POST /v1/queues/{queue_id}/messages/receive
Content-Type: application/json

{
  "max_messages": 10,
  "wait_time_seconds": 20,
  "visibility_timeout_seconds": 60
}

HTTP 200 retorna um array messages. Cada mensagem inclui corpo, atributos, receipt_handle, receive_count e visible_at. Menos de dez mensagens, inclusive nenhuma, é um resultado válido.

Salve as solicitações JSON da aba API, em ordem, como request-1.json, request-2.json. Defina QUEUE_ID com o UUID do recurso. Use sua conta e região configuradas.

basaltic queue message send "$QUEUE_ID" --from-file request-1.json
basaltic queue message receive "$QUEUE_ID" --from-file request-2.json

Salve as solicitações JSON da aba API, em ordem, como request-1.json, request-2.json. Defina QUEUE_ID com o UUID do recurso. Configure credenciais, conta e região pelas variáveis de ambiente do SDK.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	basaltic "github.com/basaltic-sh/sdk-go"
	"github.com/basaltic-sh/sdk-go/queue"
)

func readJSON(path string, value any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}
	return json.Unmarshal(data, value)
}

func run() error {
	ctx := context.Background()
	cfg, err := basaltic.NewConfig(ctx)
	if err != nil {
		return err
	}
	client := queue.New(cfg)
	var request1 queue.SendMessageRequest
	if err := readJSON("request-1.json", &request1); err != nil {
		return err
	}
	result1, err := client.SendMessage(ctx, os.Getenv("QUEUE_ID"), &request1)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result1)
	var request2 queue.ReceiveRequest
	if err := readJSON("request-2.json", &request2); err != nil {
		return err
	}
	result2, err := client.ReceiveMessages(ctx, os.Getenv("QUEUE_ID"), &request2)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result2)
	return nil
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

Confirmar ou estender a concessão

Após processar com sucesso, exclua com o recibo atual:

DELETE /v1/queues/{queue_id}/messages?receipt_handle={url_encoded_receipt_handle}

A confirmação retorna HTTP 204. O recibo pertence a uma tentativa de recebimento; o ID da mensagem não basta. Codifique o recibo para URL ao montar a solicitação e não o registre como metadado inofensivo. Se precisar de mais tempo, atualize a visibilidade antes do vencimento:

POST /v1/queues/{queue_id}/messages/visibility
Content-Type: application/json

{
  "receipt_handle": "the-current-receipt-handle",
  "visibility_timeout_seconds": 120
}

O timeout conta desde a alteração de visibilidade. Zero disponibiliza a mensagem novamente. Não use um recibo antigo após novo recebimento; ele não pode confirmar nem estender a concessão de outro consumidor.

Atributos, tamanho e lotes

Mensagens aceitam até 20 atributos. Nomes têm 1–256 bytes e valores até 1.024 bytes. Tipos: String, Number ou Binary; valores são strings no transporte, com base64 padrão para Binary. Corpo e atributos juntos precisam caber em max_message_bytes, até 256 KiB. Operações em lote de envio, exclusão e visibilidade aceitam até dez entradas com IDs próprios exclusivos para correlacionar resultados. Verifique cada entrada e repita somente as falhas. Sucesso HTTP não implica sucesso de todas as entradas.

Atraso, long polling e recebimentos vazios

O atraso da fila se aplica antes da primeira entrega. Filas padrão permitem substituir com delay_seconds; FIFO usa o atraso da fila e rejeita substituições por mensagem. Uma mensagem atrasada ainda não foi concedida, ao contrário de uma em processamento. Use wait_time_seconds até 20 para long polling ou configure receive_wait_time_seconds na fila. O timeout HTTP deve ser maior que a espera. Um resultado vazio pode indicar ausência de mensagens disponíveis, mensagens atrasadas ou concedidas, ou um grupo FIFO bloqueado.

Inspeção, limpeza e diagnóstico

A inspeção lê dados sem mudar a visibilidade ou a contagem de recebimentos e exige permissão própria. Ajuda no diagnóstico, mas não reserva mensagens para processamento. A limpeza remove mensagens, inclusive concessões ativas. Excluir a fila remove a fila e suas mensagens. Nenhuma dessas operações substitui a confirmação de processamento. Acompanhe Metrics: profundidade e idade crescentes sugerem consumidores atrasados; recebimentos repetidos sugerem falhas ou concessões curtas. Inspecione receive_count e os logs e configure uma fila de mensagens não entregues. Amostras ausentes são lacunas de observação, não filas vazias.

Primeiros passos

Produtos

Plataforma

Ajuda

Enviando e consumindo mensagens

Enviar e receber

Confirmar ou estender a concessão

Atributos, tamanho e lotes

Atraso, long polling e recebimentos vazios

Inspeção, limpeza e diagnóstico

​Enviar e receber

​Confirmar ou estender a concessão

​Atributos, tamanho e lotes

​Atraso, long polling e recebimentos vazios

​Inspeção, limpeza e diagnóstico

Enviar e receber

Confirmar ou estender a concessão

Atributos, tamanho e lotes

Atraso, long polling e recebimentos vazios

Inspeção, limpeza e diagnóstico