Recupere mensagens de um tópico do ApsaraMQ for RocketMQ via http. O broker retorna até 16 mensagens por requisição no formato XML. Cada mensagem inclui o corpo da mensagem, um hash MD5, um identificador de recebimento para confirme, timestamps e atributos da mensagem.
Requisição
GET /topics/<TopicName>/messages?ns=<instance-id>&consumer=<group-id>&tag=<tag>&numOfMessages=<count>&waitseconds=<seconds> HTTP/1.1O comprimento total da linha de requisição não deve exceder 1.024 caracteres.
Parâmetros
|
Parâmetro |
Obrigatório |
Descrição |
||||
|
TopicName |
Sim |
Nome do tópico de onde as mensagens serão consumidas. |
||||
|
ns |
Condicional |
ID da instância. Obrigatório para instâncias que possuem namespaces. Verifique a página Instance Details no console do ApsaraMQ for RocketMQ para determinar se a sua instância possui um namespace. Para mais informações, consulte Use instances. |
||||
|
consumer |
Sim |
ID do grupo de consumidores. |
||||
|
tag |
Não |
Tag da mensagem para filtragem. Omita para buscar todas as mensagens. Separe múltiplas tags com barras verticais duplas ( |
`). Exemplo: |
TagB`. |
||
|
numOfMessages |
Sim |
Número máximo de mensagens a serem retornadas. Valores válidos: 1 a 16. |
||||
|
waitseconds |
Não |
Tempo limite de long polling em segundos. Valores válidos: 0 a 30. Defina como |
Corpo da requisição
Nenhum.
Tipos de instância
O ApsaraMQ for RocketMQ possui dois tipos de instâncias:
Instância padrão -- Não possui namespace. Os nomes dos recursos devem ser globalmente únicos.
Nova instância -- Possui 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 as requisições quando não há mensagens disponíveis.
|
Modo |
Comportamento |
|
Long polling ( |
O broker mantém a requisição aberta até que uma mensagem chegue ou o tempo limite expire. |
|
Short polling ( |
O broker responde imediatamente, mesmo que não haja mensagens disponíveis. O cliente precisa fazer requisições repetidamente. |
O short polling gera um alto volume de respostas vazias quando nenhuma mensagem está sendo produzida, e cada resposta incorre em API call fees. Utilize o 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 único da mensagem. |
|
MessageBodyMD5 |
String |
Hash MD5 do corpo da mensagem. |
|
MessageBody |
String |
Conteúdo do corpo da mensagem. |
|
ReceiptHandle |
String |
Identificador para confirme o recebimento da mensagem. Passe este identificador à operação de confirme (exclua) e confirme o consumo. Uso único -- expira em |
|
PublishTime |
String |
Horário em que a mensagem foi publicada. Timestamp UNIX em milissegundos. |
|
FirstConsumeTime |
String |
Horário em que a mensagem foi consumida pela primeira vez. Timestamp UNIX em milissegundos. |
|
NextConsumeTime |
String |
Horário 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. |
Via HTTP, as mensagens não ordenadas passam por nova tentativa de consumo a cada 5 minutos, enquanto as mensagens ordenadas passam por nova tentativa a cada 1 minuto. Cada mensagem pode ser submetida a até 288 tentativas de consumo.
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. |
|
Message |
String |
Mensagem de erro. |
|
RequestId |
String |
ID da requisição. |
|
HostId |
String |
Host que enviou a requisição. |
Respostas de exemplo
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>