Exportar (0) Imprimir
Expandir todo

Introducción al búfer de mensajes de Service Bus

Introducción al búfer de mensajes del Service Bus

ImportantImportante
La actual función Búferes de mensajes, incluido su protocolo de administración, seguirá admitiéndose para garantizar la compatibilidad con versiones anteriores. No obstante, se recomienda cambiar explícitamente el código de cliente para usar la nueva característica de cola. Para obtener más información, vea Colas, temas y suscripciones.

Los búferes de mensajes son pequeñas ubicaciones de caché temporales en las cuales se pueden almacenar los mensajes durante un breve período hasta que se recuperan. Resultan particularmente útiles en escenarios de modelo de programación web cuando no están disponibles enlaces de Service Bus de Windows Azure; por ejemplo, cuando el consumidor de mensajes se ejecuta en un equipo que no ejecuta Windows, o está implementado en Java. Las aplicaciones que usan HTTP y no requieren el SDK de Windows Azure pueden obtener acceso a los búferes de mensajes. En consecuencia, los búferes de mensajes permiten que desarrolladores web, programadores de dispositivos móviles y otros integren sus aplicaciones junto con Service Bus mediante la creación de consumidores de mensajes que usen solicitudes HTTP para sondear si hay mensajes.

Los búferes de mensajes usan el protocolo HTTP REST para exponer diversas operaciones en el búfer de mensaje, como crear un búfer de mensaje, enviar un mensaje al búfer y recuperar un mensaje del búfer. Estas operaciones se describen en la siguiente sección Protocolo del búfer de mensaje.

En el siguiente código de ejemplo se muestra cómo usar el protocolo REST para crear un búfer de mensaje, enviar y recuperar un mensaje del búfer de mensajes y finalmente eliminar el búfer de mensajes. En este ejemplo se usa System.Net.WebClient para enviar y recibir solicitudes HTTP. Para obtener un ejemplo de trabajo completo, vea el ejemplo PlainHttp en la carpeta de ejemplos SDK de Windows Azure debajo de ServiceBus\ExploringFeatures\MessageBuffer.

// Prompt the user for the service namespace and issuer key.
Console.Write("Please enter your Service Namespace: ");
string serviceNamespace = Console.ReadLine();
Console.Write("Please enter the key for the 'owner' issuer: ");
string ownerKey = Console.ReadLine();
// Create a GUID for the buffer name.
string bufferName = Guid.NewGuid().ToString("N");

// Construct the message buffer URI.
string messageBufferLocation = string.Format("http://{0}.servicebus.windows.net/{1}", serviceNamespace, bufferName);

// Get the AC token
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://{0}-sb.accesscontrol.windows.net/", serviceNamespace);
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "owner");
values.Add("wrap_password", ownerKey);
values.Add("wrap_scope", messageBufferLocation);
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
string response = Encoding.UTF8.GetString(responseBytes);

string token = Uri.UnescapeDataString(response.Split('&').Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase)).Split('=')[1]);

// Create the auth header from the token 
string authHeaderValue = string.Format("WRAP access_token=\"{0}\"", token);

// Create the message buffer policy.
string policy =
    "<entry xmlns=\"http://www.w3.org/2005/Atom\">" +
    "<content type=\"text/xml\">" +
    "<MessageBufferPolicy xmlns=\"http://schemas.microsoft.com/netservices/2009/05/servicebus/connect\"/>" +
    "</content>" +
    "</entry>";

// Create a message buffer.
client.BaseAddress = string.Format("https://{0}.servicebus.windows.net/{1}/", serviceNamespace, bufferName);
client.Headers[HttpRequestHeader.ContentType] = "application/atom+xml;type=entry;charset=utf-8";
client.Headers[HttpRequestHeader.Authorization] = authHeaderValue;
client.UploadData(String.Empty, "PUT", Encoding.UTF8.GetBytes(policy));
Console.WriteLine("Message buffer was created at '{0}'.", messageBufferLocation);

// Send a message to the message buffer.
client.Headers[HttpRequestHeader.ContentType] = "text/xml";
client.Headers[HttpRequestHeader.Authorization] = authHeaderValue;
client.UploadData("messages?timeout=20", "POST", Encoding.UTF8.GetBytes("<msg1>This is message #1</msg1>"));
Console.WriteLine("Message sent.");

// Retrieve message.
client.Headers[HttpRequestHeader.Authorization] = authHeaderValue;
string payload = Encoding.UTF8.GetString(client.UploadData("messages/head?timeout=20", "DELETE", new byte[0]));
Console.WriteLine("Retrieved the message '{0}'.", payload);

// Delete the message buffer.
client.Headers[HttpRequestHeader.Authorization] = authHeaderValue;
client.UploadData(String.Empty, "DELETE", new byte[0]);  
Console.WriteLine("Message buffer at '{0}' was deleted.", messageBufferLocation);

También puede usar búferes de mensajes a través de las API que proporciona el SDK de Windows Azure. Esto requiere que esté instalado el SDK de Windows Azure. Para obtener más información acerca del uso de búferes de mensajes con el SDK de Windows Azure, vea la sección Uso del búfer de mensajes con el SDK de Windows Azure más adelante en este tema.

Protocolo del búfer de mensaje

El protocolo del búfer de mensajes es un protocolo HTTP REST diseñado para seguir los principios de REST y ser simple y sencillo de entender. El objetivo es asegurarse de que los desarrolladores puedan usar fácilmente el protocolo de cualquier cliente sin precisar una biblioteca o SDK.

El protocolo se basa en el modelo de autorización HTTP del servicio Control de acceso para ayudarle a exigir el control de acceso sobre el búfer de mensajes. Esto significa que usa el mecanismo Simple Web Token (SWT) que se puede usar para recuperar un token mediante HTTP y después incrustarlo en una solicitud HTTP como encabezado. Este token incluye notificaciones que se usan para determinar si debe permitirse o no una operación.

El protocolo espera que el búfer de cada mensaje se encuentre en un URI único en el espacio de nombres de Service Bus. Entonces, este URI pasa a ser la raíz para un conjunto de recursos que representa la instancia del búfer de mensajes. Cada tipo de recurso tiene un URI único y un conjunto asociado de verbos HTTP para interactuar con él. Los URI están organizados de modo que ayuda a comunicar las relaciones lógicas entre los distintos tipos de recursos.

Los verbos usados para interactuar con búferes de mensajes modelados en comandos HTTP estándar. La lista siguiente es una lista de estos verbos:

  • POST/PUT: Se usa para crear nuevos recursos. POST se usa para crear una nueva instancia del recurso del mensaje. PUT se usa para crear o actualizar un recurso del búfer de mensajes. Al usar POST, la dirección del nuevo recurso se devuelve en la respuesta.

  • PUT: Se usa para actualizar un recurso existente.

  • DELETE: Se usa para eliminar un recurso existente.

  • GET: Se usa para recuperar una representación de un recurso. En este caso, se espera que GET represente una instantánea del recurso y se puede almacenar en caché cuando corresponda.

A continuación se muestra un resumen de los diferentes recursos del búfer de mensajes y los verbos asociados para cada recurso.

 

URI Recurso Operaciones

http://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}

Búfer de mensaje

PUT

Crea o actualiza el búfer de mensajes.

GET

Obtiene una directiva del búfer de mensajes.

DELETE

Elimina el búfer del mensaje junto con su directiva y todo el estado asociado.

http://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages

Almacén del búfer de mensaje

POST

Crea mensaje.

(Devuelve URI del mensaje.)

http://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/head

Primer mensaje desbloqueado

POST

Obtiene el primer mensaje desbloqueado y lo bloquea.

(Devuelve el contenido del mensaje, el URI del mensaje, la duración del bloqueo, el URI del bloqueo y el Id. del bloqueo.)

DELETE

Recupera el primer mensaje desbloqueado y lo elimina del búfer.

(Devuelve el contenido del mensaje.)

http://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{messageid}

Mensaje

DELETE

Elimina el mensaje. Admite la eliminación con el Id. de bloqueo.

http://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{messageid}/{lockid}

Bloqueo de mensaje

DELETE

Desbloquea el mensaje.

Detalles de solicitud/respuesta del protocolo del búfer de mensaje

En las siguientes tablas se enumeran los contenidos de las solicitudes y sus respuestas correspondientes para cada operación del búfer de mensajes.

Crear o actualizar un búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}

Verbo HTTP

PUT

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Content-Type: application/atom+xml;type=entry;charset=utf-8

Cuerpo de la solicitud

{policy-xml}

Por ejemplo:
<entry xmlns="http://www.w3.org/2005/Atom">
<content type="text/xml">
<MessageBufferPolicy xmlns="http://schemas.microsoft.com/netservices/2009/05/servicebus/connect">
<Authorization>[AuthorizationPolicy enum value]</Authorization>
<Discoverability>[DiscoverabilityPolicy enum value]</Discoverability>
<TransportProtection>[TransportProtectionPolicy enum value]</TransportProtection>
<ExpiresAfter>PTnHnMnS</ExpiresAfter>
<MaxMessageCount>nnn</MaxMessageCount>
<OverflowPolicy>[OverflowPolicy enum value]</OverflowPolicy>
</MessageBufferPolicy>
</content>
</entry>

Notas:
El intervalo de tiempo ExpiresAfter se desglosa en horas (H), minutos (M) y segundos (S). Sustituya n por la cantidad de tiempo correspondiente para cada unidad de tiempo.
Los valores de enumeración para las propiedades de la directiva son parte del espacio de nombres Microsoft.ServiceBus.

Cuerpo de la respuesta

{policy-xml}

Se devuelve la directiva del búfer de mensajes porque podría obtenerse de manera predeterminada alguna propiedad de directiva si el valor suministrado en la solicitud no es válido.

Código de estado HTTP esperado

201 Created: El búfer de mensajes se ha creado correctamente.
403 Forbidden: Cuota superada en el número de búferes de mensajes. Aumente la cuota de conexiones por solución.

Obtener una directiva del búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}

Verbo HTTP

GET

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Cuerpo de la respuesta

{policy-xml}

Código de estado HTTP esperado

200 OK: La directiva del búfer de mensajes se ha recuperado correctamente.

Eliminar un búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}

Verbo HTTP

DELETE

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Cuerpo de la respuesta

Vacío.

Código de estado HTTP esperado

200 OK: El búfer de mensajes se ha eliminado correctamente.

Enviar un mensaje a un búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages

Verbo HTTP

POST

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Content-Type: application/atom+xml;type=entry;charset=utf-8

Cuerpo de la solicitud

{message-payload}

Cuerpo de la respuesta

Vacío.

Código de estado HTTP esperado

201 Created: El mensaje se ha enviado correctamente.
408 Request Timeout: Se agotó el tiempo de espera de la solicitud. Vuelva a intentarlo.
400 Bad Request: La solicitud superó la cuota de remitentes pendientes al búfer. Vuelva a intentarlo más tarde.
410 Gone: El búfer de mensajes ya no existe. Vuelva a crear el búfer de mensajes y vuelva a intentarlo.

Recuperar un mensaje del búfer de mensajes (lectura destructiva)

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/head?timeout={timeout-in-seconds}

El parámetro timeout especifica la cantidad máxima de tiempo que esperará la solicitud de recuperación si un mensaje no se encuentra directamente disponible en el búfer de mensajes. El tiempo máximo que se puede especificar es de 2 minutos.

Verbo HTTP

DELETE

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Cuerpo de la respuesta

{message-payload}

Código de estado HTTP esperado

200 OK: El mensaje se ha recuperado correctamente.
204 No Content: No hay mensajes presentes en el búfer de mensajes.
400 Bad Request: Esta solicitud supera la cuota de destinatarios pendientes en el búfer. Vuelva a intentarlo más tarde.
410 Gone: El búfer de mensajes ya no se encuentra disponible.

Bloquear un mensaje en el búfer de mensajes (lectura no destructiva)

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/head?timeout={timeout-in-seconds}&lockduration={lockduration-in-secs}

El parámetro timeout especifica la cantidad máxima de tiempo que esperará esta solicitud si un mensaje no se encuentra directamente disponible en el búfer de mensajes. El tiempo máximo que se puede especificar es de 2 minutos.

El parámetro lockduration especifica el tiempo en segundos que está bloqueado el mensaje devuelto de modo que ningún otro consumidor pueda ver el mensaje. La duración máxima del bloqueo es de 5 minutos y la duración mínima, de 10 segundos.

Verbo HTTP

POST

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Encabezados de la respuesta

X-MS-MESSAGE-LOCATION: https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{message-id}
Este encabezado indica la ubicación del mensaje. Se necesita este URI para desbloquear o eliminar el mensaje. Para obtener más información, vea las tablas “Desbloquear un mensaje bloqueado” y “Eliminar un mensaje bloqueado del búfer de mensaje”.
X-MS-LOCK-ID: {lock-id}
Este encabezado proporciona el Id. de bloqueo del mensaje. Este Id. de bloqueo se necesita para eliminar el mensaje bloqueado. Para obtener más información, vea la tabla “Eliminar un mensaje bloqueado del búfer de mensaje”.
X-MS-LOCK-LOCATION: https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{message-id}/{lock-id}
Este encabezado indica la ubicación del bloqueo para el mensaje. Se necesita este URI para desbloquear el mensaje. Para obtener más información, vea la tabla “Desbloquear un mensaje bloqueado”.

Cuerpo de la respuesta

{message-payload}

Código de estado HTTP esperado

200 OK: El mensaje se ha leído y bloqueado correctamente.
204 No Content: No hay mensajes presentes en el búfer de mensajes.
400 Bad Request: Esta solicitud supera la cuota de destinatarios pendientes en el búfer. Vuelva a intentarlo más tarde.
410 Gone: El búfer de mensajes ya no se encuentra disponible.

Desbloquear un mensaje bloqueado (es decir, eliminar un bloqueo en un mensaje) en el búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{message-id}/{lock-id}

Verbo HTTP

DELETE

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Cuerpo de la respuesta

Vacío.

Código de estado HTTP esperado

200 OK: El mensaje se ha desbloqueado correctamente.
404 Not Found: No se ha encontrado ningún mensaje con el Id. de bloqueo especificado. Vuelva a intentarlo con un Id. de bloque válido.
410 Gone: El búfer de mensajes ya no se encuentra disponible.

Eliminar un mensaje bloqueado del búfer de mensaje

URI de recurso

https://{serviceNamespace}.servicebus.windows.net/{path}/{buffer}/messages/{message-id}?lockid={lock-id}

El parámetro lockid debe ser un Id. de bloqueo válido del valor del encabezado de respuesta “X-MS-LOCK-ID” devuelto en respuesta a una operación de lectura no destructiva. Para obtener más información, vea la tabla “Bloquear un mensaje en el búfer de mensaje”.

Verbo HTTP

DELETE

Encabezados de la solicitud

Autorización: WRAPv0.8 {token}

Cuerpo de la solicitud

Vacío.

Cuerpo de la respuesta

Vacío.

Código de estado HTTP esperado

200 OK: El mensaje se ha eliminado correctamente.
404 Not Found: No se ha encontrado ningún mensaje con el Id. de bloqueo especificado. Vuelva a intentarlo con un Id. de bloque válido.
410 Gone: El búfer de mensajes ya no se encuentra disponible.

Directiva del búfer de mensaje

La directiva del búfer de mensajes es un documento XML que define la semántica deseada para un búfer de mensajes. Debe incluir un documento de directiva del búfer de mensajes en la solicitud al crear una nueva instancia del búfer de mensajes. Más tarde podrá recuperar el documento de directiva del búfer de mensajes para determinar la semántica de un búfer de mensajes existente. También puede actualizar un documento de directiva del búfer de mensajes para renovar el tiempo de espera de expiración. Al hacer esta operación, deberá asegurarse de que las demás propiedades no cambien.

Para obtener más información sobre las propiedades de la directiva del búfer de mensajes que pueden configurarse, consulte la documentación para la clase MessageBufferPolicy.

Cuota del búfer de mensaje

De manera predeterminada, el búfer de mensajes puede contener hasta 10 mensajes. Puede modificar este límite a través de la propiedad MaxMessageCount en la clase MessageBufferPolicy. El número máximo de mensajes que puede alojar el búfer de mensajes es de 50.

Uso del búfer de mensajes con el SDK de Windows Azure

El SDK de Windows Azure proporciona un conjunto de API de cliente administradas que facilitan a los desarrolladores el uso de un búfer de mensajes. Están diseñadas para seguir estrechamente la semántica del protocolo y permitir el uso y configuración de búferes de mensajes. Estas API se exponen a través de las clases MessageBufferClient y MessageBufferPolicy.

Puede usar la clase MessageBufferClient para crear un nuevo búfer de mensajes o recuperar un objeto que, a continuación, podrá usar para interactuar con un búfer de mensajes existente. Proporciona métodos para operar directamente en el búfer de mensaje, tal como poner en cola los mensajes del búfer de mensajes y recuperar mensajes del búfer de mensajes. Para obtener más información, vea la documentación para la clase MessageBufferClient.

Puede usar la clase MessageBufferPolicy para configurar el búfer de mensaje, incluida la seguridad usada en él, su período de vigencia y su capacidad. Para obtener más información, vea la documentación para la clase MessageBufferPolicy.

En el siguiente código de ejemplo se muestra cómo configurar y crear un búfer de mensajes y enviar y recuperar mensajes del búfer de mensajes.

string serviceNamespace = "...";
MessageVersion messageVersion = MessageVersion.Soap12WSAddressing10;
string messageAction = "urn:Message";

// Configure credentials.
TransportClientEndpointBehavior behavior = new TransportClientEndpointBehavior();
behavior.CredentialType = TransportClientCredentialType.SharedSecret;
behavior.Credentials.SharedSecret.IssuerName = "...";
behavior.Credentials.SharedSecret.IssuerSecret = "...";

// Configure buffer policy.
MessageBufferPolicy policy = new MessageBufferPolicy
{
    ExpiresAfter = TimeSpan.FromMinutes(2.0d),
    MaxMessageCount = 100
};

// Create message buffer.
string bufferName = "MyBuffer";
Uri bufferLocation = new Uri("https://" + serviceNamespace + ".servicebus.windows.net/services/" + bufferName);
MessageBufferClient client = MessageBufferClient.CreateMessageBuffer(behavior, bufferLocation, policy, messageVersion);

// Send 10 messages.
for (int i = 0; i < 10; ++i)
{
    client.Send(Message.CreateMessage(messageVersion, messageAction, "Message #" + i));
}

Message message;
string content;

// Retrieve a message (destructive read).
message = client.Retrieve();
content = message.GetBody<string>();
message.Close();

Console.WriteLine("Retrieve message content: {0}", content);

// Retrieve a message (peek/lock).
message = client.PeekLock();
content = message.GetBody<string>();

Console.WriteLine("PeekLock message content: {0}", content);

// Delete previously locked message.
client.DeleteLockedMessage(message);
message.Close();

// If no more messages are retrieved within the ExpiresAfter time span,
// the buffer will automatically be deleted...

ImportantImportante
Dado que el contenido del búfer de mensajes se almacena en la memoria activa, no hay ninguna garantía firme sobre tolerancia a errores o fiabilidad. Si se bloquea el servidor que hospeda un búfer de mensaje, es posible que pierda mensajes. En caso de bloqueo de un servidor, no perderá necesariamente el propio búfer: el conocimiento del búfer, incluida la configuración de la directiva, está distribuido entre varios servidores y puede recuperarse. No obstante, se perderán los mensajes que haya en el búfer en el momento del bloqueo. En consecuencia, si está diseñando una aplicación que requiera un elevado grado de fiabilidad de los mensajes, recomendamos que proporcione redundancia y recuperación de mensajes por otras vías.

Adiciones de comunidad

Mostrar:
© 2014 Microsoft