Request structure, response structure, and examples of the operation for consuming messages in ApsaraMQ for RocketMQ - ApsaraMQ for RocketMQ: Central de Documentação do Alibaba Cloud

Recupere mensagens de um tópico do ApsaraMQ for RocketMQ via HTTP. O broker retorna até 16 mensagens por solicitação no formato XML. Cada mensagem inclui o corpo, um resumo MD5, um receipt handle para confirmação, timestamps e atributos.

Solicitação

GET /topics/<TopicName>/messages?ns=<instance-id>&consumer=<group-id>&tag=<tag>&numOfMessages=<count>&waitseconds=<seconds> HTTP/1.1

Importante

O comprimento total da linha de solicitação não deve exceder 1.024 caracteres.

Parâmetros

Parâmetro	Obrigatório	Descrição
TopicName	Sim	Nome do tópico de onde consumir as mensagens.
ns	Condicional	ID da instância. Obrigatório para instâncias com namespaces. Verifique a página Instance Details no console do ApsaraMQ for RocketMQ para determinar se sua instância possui namespace. Para mais informações, consulte Usar instâncias.
consumer	Sim	ID do grupo de consumidores.
tag	Não	Tag da mensagem para filtragem. Omita este parâmetro para recuperar todas as mensagens. Separe múltiplas tags com barras verticais duplas (`	`). Exemplo: `TagA	TagB`.
numOfMessages	Sim	Número máximo de mensagens a retornar. Valores válidos: 1 a 16.
waitseconds	Não	Tempo limite de long polling em segundos. Valores válidos: 0 a 30. Defina como `0` ou omita para usar short polling. Consulte Long polling vs. short polling.

Corpo da solicitação

Nenhum.

Tipos de instância

O ApsaraMQ for RocketMQ possui dois tipos de instâncias:

Instância padrão -- Sem namespace. Os nomes dos recursos devem ser globalmente únicos.
Nova instância -- Com namespace. Os nomes dos recursos precisam ser únicos apenas dentro da instância.

Long polling vs. short polling

O parâmetro waitseconds controla como o broker lida com solicitações quando não há mensagens disponíveis.

Modo	Comportamento
Long polling (`waitseconds` > 0)	O broker mantém a solicitação aberta até que uma mensagem chegue ou o tempo limite expire.
Short polling (`waitseconds` = 0 ou omitido)	O broker responde imediatamente, mesmo sem mensagens disponíveis. O cliente precisa fazer polling repetidamente.

Importante

O short polling gera um alto volume de respostas vazias quando nenhuma mensagem está sendo produzida, e cada resposta incorre em taxas de chamada de API. Utilize long polling com um valor maior para waitseconds a fim de reduzir custos.

Resposta

Sucesso (HTTP 200)

O broker retorna um ou mais elementos <Message> em XML. Cada elemento contém os seguintes campos:

Parâmetro	Tipo	Descrição
MessageId	String	ID exclusivo da mensagem.
MessageBodyMD5	String	Hash MD5 do corpo da mensagem.
MessageBody	String	Conteúdo do corpo da mensagem.
ReceiptHandle	String	Handle para confirmar a mensagem. Passe este handle à operação de confirmação (exclusão) para validar o consumo. Uso único -- expira em `NextConsumeTime`. Um novo handle é emitido em cada nova tentativa.
PublishTime	String	Hora de publicação da mensagem. Timestamp UNIX em milissegundos.
FirstConsumeTime	String	Hora do primeiro consumo da mensagem. Timestamp UNIX em milissegundos.
NextConsumeTime	String	Hora em que a mensagem fica disponível para nova tentativa. Timestamp UNIX em milissegundos.
ConsumedTimes	String	Número de tentativas de consumo.
MessageTag	String	Tag da mensagem.
Properties	String	Atributos da mensagem serializados no formato chave-valor. Consulte Formato das propriedades da mensagem.

Nota

Via HTTP, mensagens não ordenadas são submetidas a nova tentativa a cada 5 minutos, enquanto mensagens ordenadas são submetidas a nova tentativa a cada 1 minuto. Cada mensagem pode ter até 288 tentativas.

Formato das propriedades da mensagem

O campo Properties utiliza o formato key1:value1|key2:value2|key3:value3.

Chave	Tipo	Descrição
KEYS	String	Chave da mensagem.
__STARTDELIVERTIME	Long	Horário de entrega agendada para uma mensagem agendada. Timestamp UNIX em milissegundos.
__TransCheckT	Long	Atraso antes da primeira verificação de status de transação para uma mensagem transacional, em segundos. Valores válidos: 10 a 300.

Nenhuma mensagem disponível (HTTP 404)

Se não houver mensagens disponíveis, o broker retorna HTTP 404 com o código de erro MessageNotExist. Este é um comportamento esperado, não um erro.

Parâmetro	Tipo	Descrição
Code	String	Código de erro. `MessageNotExist` indica ausência de mensagens disponíveis.
Message	String	Mensagem de erro.
RequestId	String	ID da solicitação.
HostId	String	Host que enviou a solicitação.

Exemplos de resposta

Mensagens disponíveis

<?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>

Nenhuma mensagem disponível

<?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>