Documentación de Oracle Cloud Infrastructure

Uso de STOMP para la gestión de mensajes

Utilice el protocolo de mensajes STOMP para publicar, consumir y gestionar los mensajes de una cola.

Visión general

STOMP es un protocolo de mensajería abierto que puede aumentar la eficiencia de producción y consumo, porque la autenticación se realiza una vez por conexión, en lugar de una vez por solicitud. El servicio Queue soporta las especificaciones STOMP 1.0, 1.1 y 1.2. Puede utilizar tanto STOMP como REST para publicar y consumir en la misma cola.

Consulte las siguientes secciones para obtener detalles sobre cómo Queue admite STOMP:

Nota

La cola no soporta cabeceras ni transacciones personalizadas (marcos STOMP BEGIN/COMMIT/ABORT). Queue devuelve un marco ERROR y cierra la conexión si se utiliza BEGIN/COMMIT/ABORT.

Conexión y autenticación

Los clientes pueden utilizar el marco CONNECT o STOMP para conectarse al servicio Queue en el punto final de los mensajes en el puerto 61613. Para obtener instrucciones detalladas sobre cómo buscar el punto final de los mensajes de una cola, consulte Punto final de mensajes.

La autenticación con el protocolo STOMP utiliza tokens de autenticación. Los tokens de autenticación deben estar codificados en base64. Puede generar tokens en la página de detalles de usuario de la consola. Consulte Trabajar con tokens de autenticación para obtener más información.

Consejo

Cree un grupo o un usuario dedicado y otórgueles el permiso para gestionar colas en el compartimento o el arrendamiento adecuado. A continuación, genere un token de autenticación para el usuario que ha creado y utilícelo en la configuración del cliente STOMP. Consulte Políticas de Queue y Ejemplos de políticas para obtener más información sobre los permisos necesarios para la gestión de colas.

SEND

Utilice el marco SEND para producir mensajes. Puede incluir las siguientes cabeceras en el marco SEND:

  • destination: (necesario) OCID (identificador de Oracle Cloud) de la cola en la que publicar los mensajes. Opcionalmente, puede incluir un ID de canal para publicar en el canal especificado. Por ejemplo:

    <queue_OCID>/<channel_ID>
  • receipt: (opcional) si el marco SEND contiene una cabecera receipt, Queue envía un marco RECEIPT al cliente tras la publicación correcta o un marco ERROR al producirse un error.
    Nota

    Si falta la cabecera receipt, el servicio Queue no envía un marco RECEIPT, pero podría seguir enviando un marco ERROR por error.

La cabecera transaction y las cabeceras personalizadas no están soportadas. Queue envía un marco ERROR y cierra la conexión si se incluyen encabezados no soportados.

SUBSCRIBE

Utilice el marco SUBSCRIBE para consumir mensajes. El marco SUBSCRIBE es igual a una solicitud de sondeo largo GetMessages. Los mensajes recibidos en el destino suscrito se entregan al cliente como marcos MESSAGE de la cola. Puede incluir las siguientes cabeceras en el marco SUBSCRIBE:

  • destination: (necesario) OCID (identificador de Oracle Cloud) de la cola de la que se consumirán mensajes. Opcionalmente, puede incluir un filtro de canal para consumir desde el canal o canales especificados. Por ejemplo:

    <queue_OCID>/<channel_ID_filter>
    Nota

    Para obtener más información sobre el filtrado, consulte Selección de mensajes.
  • id: (necesario) identifica la suscripción. El cliente debe transferir el mismo identificador en un marco UNSUBSCRIBE para parar el consumo de mensajes.
  • ack: (necesario) solo está soportado el valor client-individual. Esto significa que un marco ACK solo suprime el mensaje identificado en el marco ACK y no todos los mensajes entregados anteriormente.
  • visibility: tiempo durante el cual los mensajes consumidos solo estarán visibles para el cliente que realiza la solicitud. Si se suprime la cabecera, el servicio Queue utiliza el timeout de visibilidad por defecto de la cola.

Al producirse un error, el servicio Queue devuelve un marco ERROR y cierra la conexión.

UNSUBSCRIBE

Utilice el marco UNSUBSCRIBE para evitar que el cliente de STOMP reciba mensajes de la cola. Incluya el siguiente encabezado en el marco:

  • id: (necesario) identifica la suscripción que se va a parar. Este identificador se ha utilizado en el marco SUBSCRIBE correspondiente.

ACK/NACK

Utilice el marco ACK para suprimir un mensaje después de que se haya recibido y procesado. Un marco ACK solo suprime el mensaje identificado por la cabecera id.

Utilice el marco NACK para notificar a Queue que el mensaje no se ha procesado correctamente. El marco NACK actualiza la visibilidad del mensaje para que sea visible de inmediato para otros consumidores.

Ambos marcos aceptan la siguiente cabecera según la versión del protocolo:

  • id: (necesario para STOMP v1.2) identificador del mensaje que se va a suprimir o actualizar.
  • message-id: (necesario para STOMP v1.1 o 1.0) identificador del mensaje que se va a suprimir o actualizar.

MESSAGE

El marco MESSAGE transmite mensajes de suscripciones al cliente de STOMP. Un marco MESSAGE contiene las siguientes cabeceras:

  • message-id:
    • Para STOMP v1.2: identificador único interno del mensaje. Solo se utiliza para la depuración.
    • Para STOMP v1.1 y v1.0: recibo de mensaje que se utilizará con los marcos ACK y NACK.
  • subscription: identificador que se utiliza en el marco SUBSCRIBE.
  • destination: OCID (identificador de Oracle Cloud) de la cola que contenía los mensajes y un ID de canal opcional para publicar en un canal especificado. Por ejemplo:
    <queue_OCID>/<channel_ID>
  • ack: solo para STOMP v.1.2, la recepción del mensaje.
  • content-type: tipo de carga útil, en este caso, plain/text.
  • content-length: longitud de la carga útil o del mensaje.
  • expire-after: tiempo de caducidad del mensaje en milisegundos desde el tiempo epoch.
  • visible-after: tiempo de visibilidad del mensaje en milisegundos desde el tiempo epoch.
  • delivery-count: número de veces que se ha entregado este mensaje
  • oci-message-id : identificador de mensaje interno.

Un marco MESSAGE contiene la carga útil del mensaje como cuerpo del marco.

RECEIPT

El servicio Queue envía un marco RECEIPT al cliente de STOMP después de que el servicio haya procesado correctamente un marco SEND que solicitaba una recepción. Un marco RECEIPT incluye una cabecera receipt-id con un valor que coincide con la cabecera de recibo del marco SEND.

Un marco RECEIPT es un acuse de recibo de que el servidor ha procesado el marco de cliente correspondiente. Debido a que STOMP se basa en flujos, la recepción también es una confirmación acumulativa de que el servidor ha recibido todos los marcos anteriores. Sin embargo, es posible que estos marcos anteriores aún no se hayan procesado completamente. Si el cliente se desconecta, los marcos recibidos anteriormente deben seguir siendo procesados por el servidor.

DISCONNECT

Utilice el marco DISCONNECT para desconectar o cerrar la conexión al servicio Queue. Se pararán todas las suscripciones asociadas a la conexión. Puede incluir la siguiente cabecera en el marco:

  • receipt: (opcional) Queue enviará un marco RECEIPT al cliente de STOMP después de que todos los marcos anteriores con una cabecera receipt se hayan procesado correctamente. Utilice la cabecera receipt para las desconexiones normales.

ERROR

Queue puede enviar marcos ERROR si algo falla. Después de enviar el marco ERROR, Queue cierra la conexión. El marco ERROR puede contener las siguientes cabeceras:

  • message: descripción breve del error. El cuerpo contiene información más detallada.
  • receipt-id: valor de la cabecera receipt, si el marco que provocó el error incluía una cabecera receipt.
  • content-type: tipo de carga útil, si el cuerpo contiene más detalles del mensaje de error.
  • content-length: longitud de la carga útil o detalles del mensaje de error.

El cuerpo del marco ERROR contiene información detallada sobre el error.