Mensagem com bloqueio de inspeção (leitura não destrutiva)

  • Artigo

Essa operação recupera e bloqueia atomicamente uma mensagem de uma fila ou assinatura para processamento. Não é garantido que a mensagem seja entregue a outros receptores (apenas na mesma fila ou assinatura) durante o período de bloqueio especificado na descrição da fila/assinatura. Quando o bloqueio expirar, a mensagem se tornará disponível para outros receptores. Para concluir o processamento da mensagem, o receptor deve emitir um comando de exclusão com o bloqueio de ID recebido dessa operação. Para abandonar o processamento da mensagem e desbloqueá-la para outros receptores, um comando Desbloquear Mensagem deve ser emitido; caso contrário, o período de duração do bloqueio pode expirar.

Essa operação deve ser usada em aplicativos que exigem garantias de entrega do tipo At-Least-Once. Se o receptor não excluir a mensagem antes que o processamento seja bem-sucedido, essa operação garantirá que outro receptor seja capaz de tentar processar depois que o período de duração do bloqueio expirar.

Solicitação

Método URI da solicitação Versão de HTTP
POST http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head

ou

http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head|HTTP/1.1

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais. Além das propriedades listadas, o cabeçalho pode conter propriedades personalizadas. Consulte o exemplo.

Cabeçalho da solicitação Descrição
Autorização Especifique um dos seguintes valores de token:
  • Token JWT (Token Web JSON) do Azure Active Directory (Azure AD).
    Exemplo: Authorization: Bearer <Azure AD JWT token>.
    Para obter informações sobre como gerar um token Azure AD, consulte Autenticar de um aplicativo.
  • Um token SAS.
    Exemplo: Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>.
    Para obter informações sobre como gerar um token SAS, consulte Gerar um token de Assinatura de Acesso Compartilhado e Gerar token SAS.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e o corpo de resposta.

Códigos de resposta

Código Descrição
201 Mensagem recuperada e bloqueada com êxito.
204 Não há mensagens disponíveis no período de tempo limite especificado.
400 Solicitação inválida.
401 Falha de autorização.
410 A fila ou assinatura especificada não existe.
500 Erro interno.

Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de Resposta Descrição
Content-Type Defina como application/atom+xml;type=entry;charset=utf-8.
Location O URI da mensagem bloqueada. Você pode usar esse URI para desbloquear ou excluir a mensagem.
BrokerProperties Codificado BrokerProperties em JSON da mensagem recebida. A LockToken propriedade representa a ID de bloqueio da mensagem retornada. A SequenceNumber propriedade representa o número de sequência da mensagem retornada.

Corpo da resposta

O corpo da resposta é o corpo da mensagem recuperada.

Exemplo

A seguinte solicitação HTTP bloqueia e retorna a mensagem de uma fila:

POST https://your-namespace.servicebus.windows.net/HttpClientSampleQueue/messages/head?timeout=60 HTTP/1.1  
Authorization: SharedAccessSignature sr=your-namespace&sig=Fg8yUyR4MOmXfHfj55f5hY4jGb8x2Yc%2b3%2fULKZYxKZk%3d&se=1404256819&skn=RootManageSharedAccessKey  
Host: your-namespace.servicebus.windows.net  
Content-Length: 0

O Barramento de Serviço retorna a resposta a seguir. A mensagem contém as propriedades personalizadas Priority e Customer:

HTTP/1.1 201 Created  
Transfer-Encoding: chunked  
Content-Type: application/atom+xml;type=entry;charset=utf-8  
Location: https://your-namespace.servicebus.windows.net/httpclientsamplequeue/messages/2/7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547  
Server: Microsoft-HTTPAPI/2.0  
BrokerProperties: {"DeliveryCount":1,"EnqueuedSequenceNumber":0,"EnqueuedTimeUtc":"Wed, 02 Jul 2014 01:32:27 GMT","Label":"M1","LockToken":"7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547","LockedUntilUtc":"Wed, 02 Jul 2014 01:33:27 GMT","MessageId":"31907572164743c38741631acd554d6f","SequenceNumber":2,"State":"Active","TimeToLive":10}  
Priority: "High"  
Customer: "12345,ABC"  
Date: Wed, 02 Jul 2014 01:32:27 GMT  
  
12  
This is a message.  
0

Consulte Também

Exemplo de Cliente HTTP de Barramento de Serviço