Invocación de las API REST del gestor de colas

IBM MQ proporciona un conjunto de API REST que ofrecen una forma sencilla de administrar, probar e interactuar con el gestor de colas a través de scripts, aplicaciones y programas. En esta sección, se proporcionarán los requisitos para llamar a las API en el gestor de colas de IBM, además de ejemplos que se pueden ejecutar directamente desde el terminal y que se pueden convertir fácilmente a otros lenguajes de programación.

Un gestor de colas de IBM tiene 2 API REST disponibles a las que puede llamar:

API REST de administración: le permite llevar a cabo acciones administrativas sobre el gestor de colas
API REST de mensajería: permite a las aplicaciones enviar y recibir mensajes

Hay alguna información importante al interactuar con el gestor de colas de IBM:

El puerto de escucha no es necesario en el URI para llamar a la API REST
El nombre de host para llamar al gestor de colas debe empezar por web-
La vía de acceso en el URI debe comenzar por /ibmmq/rest
La API REST es sensible a las mayúsculas y minúsculas; por ejemplo, si el gestor de colas se llama QM1 y utiliza la API REST de administración, en la vía de acceso del administrador debe especificar /qmgr/QM1/...

Autenticación del cliente para invocar solicitudes de API REST

Hay un par de maneras de autenticarse con el gestor de colas de IBM sobre REST.

La primera es utilizar la autenticación básica; es un método muy común que se utiliza para interactuar con el gestor de colas sobre REST, ya que es fácil de convertir a otros lenguajes y resulta excelente para realizar pruebas.

Para obtener más información sobre la utilización de la autenticación básica para autenticarse con el gestor de colas, consulte aquí.

Ejemplo: Autenticación con un gestor de colas de IBM utilizando la autenticación básica

Obtenga el nombre de usuario de MQ y la clave de API de la instancia de servicio en IBM Cloud y luego ejecute lo siguiente:
```
AUTH=`echo "<MQ_USERNAME>:<API_KEY>" | base64`
```
Los valores de MQ_USERNAME y API_KEY dependerán de la API REST a la que acceda:
- admin, debe añadir el usuario en el separador de permisos de usuario que le generará un nombre de usuario de MQ y utilizará la clave de API de la plataforma para IBM Cloud
- mensajería, debe crear un permiso de aplicación en la pestaña de permisos de aplicación y utilizar la clave de API y el nombre de usuario de MQ que genera

Pase el valor de AUTH en la cabecera de autenticación de las solicitudes:

curl -H "Authorization: Basic $AUTH" -H "ibm-mq-rest-csrf-token: value" https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v2/admin/qmgr/qm1

El segundo método es la autenticación basada en señales, que interactúa con la API REST de inicio de sesión que expone el gestor de colas. Esta API REST devuelve una cookie que se puede guardar en una variable en el script o en la aplicación, o bien en un archivo de texto sin formato que se puede utilizar en las solicitudes posteriores al gestor de colas.

Cuando termine de interactuar con el gestor de colas de IBM sobre REST, también se puede utilizar la API REST de inicio de sesión para revocar la señal de acceso, lo que requiere que el cliente recupere una nueva señal de acceso antes de realizar llamadas posteriores.

Para obtener más información sobre cómo utilizar la autenticación basada en señales para interactuar con el gestor de colas sobre REST, consulte aquí.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/login -H "Content-Type: application/json" --data "{\"username\":\"<MQ_USERNAME>\",\"password\":\"<API_KEY>\"}" -c cookiejar.txt

En las llamadas subsiguientes, pase el archivo cookiejar.txt como un parámetro para identificarse como usuario autenticado.

Administración del gestor de colas

La API REST de administración ofrece la posibilidad de administrar el gestor de colas, permitiéndole crear, recuperar, modificar y suprimir colas.

Encontrará la documentación de la API REST de administración aquí.

Ejemplo: Creación de una cola en un gestor de colas de IBM

Si ha autenticado mediante la autenticación basada en señales, apunte al lugar donde ha guardado la cookie para identificarse como usuario autenticado.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/admin/action/qmgr/QM1/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

A continuación, puede visualizar la cola creada ejecutando el mandato siguiente.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/admin/action/qmgr/QM1/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

Envío y recepción de mensajes

La API REST de mensajería le permite enviar y recuperar mensajes en la cola que desee dentro de un gestor de colas de IBM.

La documentación de la API REST de mensajería se puede encontrar aquí.

Colas no 'DEV.'

Si se ha creado una nueva cola cuyo nombre no empieza por 'DEV.' no se aplicarán los registros de autorización predefinidos. Por lo tanto, las aplicaciones no tendrán los permisos necesarios para enviar o recibir mensajes a esta cola. Revise la guía Asignación de acceso de usuario/grupo a una cola para obtener más información y los pasos necesarios para configurar el registro de autorización necesario para esta cola.

Ejemplo: Poner un mensaje en una cola de un gestor de colas de IBM

Si ha autenticado mediante la autenticación basada en señales, apunte al lugar donde ha guardado la cookie para identificarse como usuario autenticado.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/qm1/queue/TEST.QUEUE/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" --data "hello world" -b cookiejar.txt

Observe que de forma predeterminada, los mensajes enviados a través de la API REST de mensajería se tratarán como no persistentes, independientemente del valor de persistencia predeterminado configurado en la cola de destino. Para cambiar el comportamiento predeterminado, puede incluir una cabecera opcional ibm-mq-md-persistence que se debe especificar con uno de los siguientes valores:

persistent
nonPersistent

Para enviar un mensaje persistente, el ejemplo anterior tendría la siguiente forma:

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/qm1/queue/TEST.QUEUE/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" -H "ibm-mq-md-persistence: persistent" --data "hello world" -b cookiejar.txt

La lista completa de cabeceras de API REST de mensajería se puede encontrar aquí