Extraiga mensajes de un topic de ApsaraMQ for RocketMQ mediante HTTP. El broker devuelve hasta 16 mensajes por solicitud en formato XML. Cada mensaje incluye el cuerpo del mensaje, un hash MD5, un identificador de recibo (receipt handle) para la confirmación, marcas de tiempo y atributos del mensaje.
Solicitud
GET /topics/<TopicName>/messages?ns=<instance-id>&consumer=<group-id>&tag=<tag>&numOfMessages=<count>&waitseconds=<seconds> HTTP/1.1La longitud total de la línea de solicitud no debe superar los 1024 caracteres.
Parámetros
|
Parámetro |
Obligatorio |
Descripción |
||||
|
TopicName |
Sí |
Nombre del topic del que se consumirán los mensajes. |
||||
|
ns |
Condicional |
ID de la instancia. Es obligatorio para las instancias que tienen namespaces. Revise la página Instance Details en la consola de ApsaraMQ for RocketMQ para comprobar si su instancia cuenta con un namespace. Para obtener más información, consulte Use instances. |
||||
|
consumer |
Sí |
ID del grupo de consumidores. |
||||
|
tag |
No |
Etiqueta del mensaje para filtrar. Omítala para extraer todos los mensajes. Separe varias etiquetas con barras verticales dobles ( |
`). Ejemplo: |
TagB`. |
||
|
numOfMessages |
Sí |
Número máximo de mensajes que se devolverán. Valores válidos: de 1 a 16. |
||||
|
waitseconds |
No |
Tiempo de espera del sondeo largo (long polling), en segundos. Valores válidos: de 0 a 30. Establezca este valor en |
Cuerpo de la solicitud
Ninguna.
Tipos de instancia
ApsaraMQ for RocketMQ cuenta con dos tipos de instancias:
Instancia predeterminada: no tiene namespace. Los nombres de los recursos deben ser únicos a nivel global.
Instancia nueva: tiene un namespace. Los nombres de los recursos solo necesitan ser únicos dentro de la instancia.
Sondeo largo frente a sondeo corto
El parámetro waitseconds controla cómo procesa el broker las solicitudes cuando no hay mensajes disponibles.
|
Modo |
Comportamiento |
|
Sondeo largo ( |
El broker mantiene abierta la solicitud hasta que llega un mensaje o transcurre el tiempo de espera. |
|
Sondeo corto ( |
El broker responde de inmediato, incluso si no hay mensajes disponibles. El cliente debe enviar solicitudes repetidas. |
El sondeo corto genera un volumen alto de respuestas vacías cuando no se producen mensajes, y cada respuesta implica API call fees. Use el sondeo largo con un valor mayor de waitseconds para reducir costos.
Respuesta
Éxito (HTTP 200)
El broker devuelve uno o varios elementos <Message> en formato XML. Cada elemento contiene los campos a continuación:
|
Parámetro |
Tipo |
Descripción |
|
MessageId |
String |
ID único del mensaje. |
|
MessageBodyMD5 |
String |
Hash MD5 del cuerpo del mensaje. |
|
MessageBody |
String |
Contenido del cuerpo del mensaje. |
|
ReceiptHandle |
String |
Identificador para confirmar el mensaje. Pase este identificador a la operación de confirmación (eliminación) para confirmar el consumo. Es de un solo uso y caduca en |
|
PublishTime |
String |
Hora de publicación del mensaje. Marca de tiempo UNIX en milisegundos. |
|
FirstConsumeTime |
String |
Hora del primer consumo del mensaje. Marca de tiempo UNIX en milisegundos. |
|
NextConsumeTime |
String |
Hora en la que el mensaje queda disponible para reintentos. Marca de tiempo UNIX en milisegundos. |
|
ConsumedTimes |
String |
Número de reintentos de consumo. |
|
MessageTag |
String |
Etiqueta del mensaje. |
|
Properties |
String |
Atributos del mensaje serializados en formato clave-valor. Consulte Formato de las propiedades del mensaje. |
Mediante HTTP, los mensajes no ordenados se reintentan cada 5 minutos y los mensajes ordenados cada minuto. Cada mensaje admite hasta 288 reintentos.
Formato de las propiedades del mensaje
El campo Properties utiliza el formato key1:value1|key2:value2|key3:value3.
|
Clave |
Tipo |
Descripción |
|
KEYS |
String |
Clave del mensaje. |
|
__STARTDELIVERTIME |
Long |
Hora de entrega programada para un mensaje diferido. Marca de tiempo UNIX en milisegundos. |
|
__TransCheckT |
Long |
Retraso, en segundos, antes de la primera comprobación del estado de una transacción para un mensaje transaccional. Valores válidos: de 10 a 300. |
Sin mensajes disponibles (HTTP 404)
Si no hay mensajes disponibles, el broker devuelve HTTP 404 con el código de error MessageNotExist. Este es el comportamiento esperado y no un error.
|
Parámetro |
Tipo |
Descripción |
|
Code |
String |
Código de error. |
|
Message |
String |
Mensaje de error. |
|
RequestId |
String |
ID de la solicitud. |
|
HostId |
String |
Host que envió la solicitud. |
Respuestas de ejemplo
Mensajes disponibles
<?xml version="1.0" ?>
<Messages xmlns="http://mq.aliyuncs.com/doc/v1">
<Message>
<MessageId>1E057D5E6EAD42A579937046FE17****</MessageId>
<MessageBodyMD5>0CC175B9C0F1B6A831C399E26977****</MessageBodyMD5>
<MessageBody>a</MessageBody>
<ReceiptHandle>1E057D5E6EAD42A579937046FE17****-MTI5N****</ReceiptHandle>
<PublishTime>1571742900759</PublishTime>
<FirstConsumeTime>1571742902463</FirstConsumeTime>
<NextConsumeTime>1571743202463</NextConsumeTime>
<ConsumedTimes>1</ConsumedTimes>
<MessageTag>Tag</MessageTag>
<Properties>KEYS:MessageKey|__BORNHOST:30.5.**.**|</Properties>
</Message>
<Message>
<MessageId>1E057D5E6EAD42A579937046FE17****</MessageId>
<MessageBodyMD5>0CC175B9C0F1B6A831C399E26977****</MessageBodyMD5>
<MessageBody>a</MessageBody>
<ReceiptHandle>1E057D5E6EAD42A579937046FE17****-MTI5N****</ReceiptHandle>
<PublishTime>1571742900759</PublishTime>
<FirstConsumeTime>1571742902463</FirstConsumeTime>
<NextConsumeTime>1571743202463</NextConsumeTime>
<ConsumedTimes>1</ConsumedTimes>
<MessageTag>Tag</MessageTag>
<Properties>KEYS:MessageKey|__BORNHOST:30.5.**.**|</Properties>
</Message>
</Messages>Sin mensajes disponibles
<?xml version="1.0" ?>
<Error xmlns="http://mq.aliyuncs.com/doc/v1">
<Code>MessageNotExist</Code>
<Message>Message not exist.</Message>
<RequestId>5DAEE3FF463541AD6E0322EB</RequestId>
<HostId>http://123.mqrest.cn-hangzhou.aliyuncs.com</HostId>
</Error>