Enviar y consumir mensajes

La recepción es una concesión temporal. El consumidor debe confirmar después de procesar correctamente. Si se detiene o la concesión vence antes, otro consumidor puede recibir. Diseñe la operación para tolerar esa reentrega.

Enviar y recibir

Console
API
CLI
Go

Abra la cola y seleccione Send message para publicar manualmente. La pestaña Messages permite inspeccionar sin concesión. Ejecute consumidores mediante la API; inspeccionar no es procesar.

Envíe un mensaje a la cola:

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

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

HTTP 201 devuelve un result con el ID del mensaje. Reciba trabajo con:

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

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

HTTP 200 devuelve un array messages. Cada mensaje incluye cuerpo, atributos, receipt_handle, receive_count y visible_at. Menos de diez mensajes, incluso ninguno, es un resultado válido.

Guarde las solicitudes JSON de la pestaña API, en orden, como request-1.json, request-2.json. Defina QUEUE_ID con el UUID del recurso. Use su cuenta y región configuradas.

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

Guarde las solicitudes JSON de la pestaña API, en orden, como request-1.json, request-2.json. Defina QUEUE_ID con el UUID del recurso. Configure credenciales, cuenta y región mediante las variables de entorno del 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 o ampliar la concesión

Después de procesar correctamente, elimine con el recibo actual:

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

La confirmación devuelve HTTP 204. El recibo pertenece a un intento de recepción; el ID del mensaje no basta. Codifique el recibo para URL al construir la solicitud y no lo registre como metadato inofensivo. Si necesita más tiempo, actualice la visibilidad antes del vencimiento:

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

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

El timeout cuenta desde el cambio de visibilidad. Cero vuelve a hacer disponible el mensaje. No use un recibo antiguo tras otra recepción; no puede confirmar ni ampliar la concesión de otro consumidor.

Atributos, tamaño y lotes

Los mensajes aceptan hasta 20 atributos. Los nombres tienen 1–256 bytes y los valores hasta 1.024 bytes. Tipos: String, Number o Binary; los valores son cadenas en el transporte, con base64 estándar para Binary. Cuerpo y atributos juntos deben caber en max_message_bytes, hasta 256 KiB. Las operaciones por lotes de envío, eliminación y visibilidad aceptan hasta diez entradas con ID propios únicos para correlacionar resultados. Compruebe cada entrada y repita solo los fallos. El éxito HTTP no implica el éxito de todas las entradas.

Retraso, long polling y recepciones vacías

El retraso de la cola se aplica antes de la primera entrega. Las colas estándar permiten sustituirlo con delay_seconds; FIFO usa el retraso de la cola y rechaza sustituciones por mensaje. Un mensaje retrasado aún no se ha concedido, a diferencia de uno en proceso. Use wait_time_seconds hasta 20 para long polling o configure receive_wait_time_seconds en la cola. El timeout HTTP debe superar la espera. Un resultado vacío puede indicar ausencia de mensajes disponibles, mensajes retrasados o concedidos, o un grupo FIFO bloqueado.

Inspección, purga y diagnóstico

La inspección lee datos sin cambiar la visibilidad ni el recuento de recepciones y exige permiso propio. Ayuda al diagnóstico, pero no reserva mensajes para procesarlos. La purga elimina mensajes, incluidas concesiones activas. Eliminar la cola elimina la cola y sus mensajes. Ninguna de estas operaciones sustituye la confirmación del procesamiento. Siga Metrics: profundidad y antigüedad crecientes sugieren consumidores rezagados; recepciones repetidas sugieren fallos o concesiones cortas. Inspeccione receive_count y los registros y configure una cola de mensajes no entregados. Las muestras ausentes son huecos de observación, no colas vacías.

Primeros pasos

Productos

Plataforma

Ayuda

Enviar y consumir mensajes

Enviar y recibir

Confirmar o ampliar la concesión

Atributos, tamaño y lotes

Retraso, long polling y recepciones vacías

Inspección, purga y diagnóstico

​Enviar y recibir

​Confirmar o ampliar la concesión

​Atributos, tamaño y lotes

​Retraso, long polling y recepciones vacías

​Inspección, purga y diagnóstico

Enviar y recibir

Confirmar o ampliar la concesión

Atributos, tamaño y lotes

Retraso, long polling y recepciones vacías

Inspección, purga y diagnóstico