Operación de IBM MQ de forma remota a través de API REST

Las aplicaciones IBM MQ tradicionalmente se conectan mediante una biblioteca cliente de MQ y utilizan la Message Queue Interface para interactuar con el gestor de colas. Los administradores utilizan mandatos MQSC, PCF, la consola web de IBM MQ o IBM MQ Explorer. Todas estas interfaces siguen siendo importantes, pero no son la única forma de trabajar con un gestor de colas.

IBM MQ también proporciona API que se pueden invocar a través de HTTP interactuando con el servidor mqweb. Son útiles cuando una herramienta de automatización, un portal de operaciones, un script de diagnóstico o una aplicación pueden hablar HTTPS, pero no deben incorporar una instalación de cliente MQ.

Este artículo crea un laboratorio que utiliza dos API relacionadas pero distintas:

El laboratorio crea sesiones administrativas y de aplicaciones separadas, almacena sus cookies LTPA, crea y cambia una cola, intercambia mensajes, inspecciona la profundidad de la cola, interpreta errores y cierra sesión. Cada solicitud se origina en un contenedor de herramientas independiente. El cliente REST no tiene acceso de shell, sistema de archivos o MQI al Administrador de colas.

Consideraciones de laboratorio: La imagen de IBM MQ Advanced for Developers y su certificado web generado son adecuados para un ejercicio de estación de trabajo desechable. Los comandos utilizan curl --insecure porque el contenedor de herramientas no confía en el certificado generado. La automatización de la producción debe validar el certificado del servidor mqweb, proteger las credenciales y las cookies, asignar identidades de alcance limitado y restringir el acceso a la red al puerto 9443.

1. Dos API detrás de un punto final HTTPS

La consola web y las API REST se ejecutan en el servidor mqweb, que es un servidor WebSphere Liberty. El escucha HTTPS predeterminado escucha en el puerto 9443 y el prefijo API de la versión 3 es:

https://host:9443/ibmmq/rest/v3

Las dos API realizan un trabajo diferente bajo este prefijo.

Las funciones administrativas comienzan con:

/admin

Las capacidades de procesamiento de mensajes comienzan con:

/messaging

Por ejemplo, estas son diferentes operaciones:

GET  /ibmmq/rest/v3/admin/qmgr/RESTQM
POST /ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message

Mientras la primera llamada pregunta a mqweb por el estado del Administrador de colas, la segunda pone un mensaje de MQ. Compartir HTTP y la infraestructura de autenticación no hace que las operaciones de administración y mensajería sean equivalentes.

Esta distinción también es importante en términos de autorización. Una identidad puede tener permiso para iniciar sesión en mqweb, pero aún no tiene las autoridades MQ necesarias para utilizar una cola. Por otra parte, una autoridad MQ por sí sola no otorga acceso a la funcionalidad del servidor mqweb.

2. Autenticación, cookies y protección CSRF

IBM MQ da soporte a la autenticación básica HTTP, la autenticación de certificados de cliente y mecanismos de autenticación basados ​​en tokens para autenticar la API REST. Esta práctica de laboratorio utiliza autenticación de token para que la contraseña se envíe una vez en lugar de repetirse con cada solicitud.

El cliente publica credenciales para:

POST /ibmmq/rest/v3/login

Si la autenticación se realiza correctamente, mqweb devuelve un token LTPA en una cookie y el cliente envía esta cookie con solicitudes posteriores. La vida útil predeterminada del token es finita y configurable, por lo que un cliente de automatización debe poder iniciar sesión nuevamente después de su vencimiento.

Las solicitudes que cambian de estado también incluyen el encabezado:

ibm-mq-rest-csrf-token: lab

El valor no es secreto y puede ser cualquier valor, incluido un valor vacío. Su presencia es la protección requerida por mqweb para operaciones como POST, PATCH y DELETE y no reemplaza la autenticación.

El flujo resultante es:

Utilice siempre HTTPS para que TLS proteja las credenciales para una solicitud de inicio de sesión durante la transferencia de datos.

3. Requisitos de laboratorio

Su máquina necesita tener:

• Docker Engine o Docker Escritorio
• Docker Compositor v2
• Al menos 4 GB de memoria libre
• Acceso a Internet para icr.io y Docker Hub
• Un host AMD64 Linux o Docker Desktop en Apple Silicon con emulación AMD64

El laboratorio utiliza estas imágenes:

icr.io/ibm-messaging/mq:10.0.0.0-r2
alpine:3.22

La imagen MQ tiene licencia para uso exclusivo en desarrollo. Aceptar su licencia en el archivo Compose no otorga derechos de producción.

4. Crea el proyecto

Cree un directorio vacío para el laboratorio:

mkdir -p "$HOME/mq-rest-api-lab/client" \
         "$HOME/mq-rest-api-lab/secrets"
cd "$HOME/mq-rest-api-lab"

Cree los archivos de contraseña utilizados como secretos de Docker:

printf '%s' 'AdminPassw0rd!' > secrets/mqAdminPassword
printf '%s' 'AppPassw0rd!' > secrets/mqAppPassword
chmod 600 secrets/mqAdminPassword secrets/mqAppPassword

La contraseña de la aplicación no es crítica en esta práctica de laboratorio, pero la imagen del desarrollador espera credenciales para ambas identidades de desarrollo predefinidas.

5. Construya el contenedor de herramientas REST

El contenedor de herramientas solo proporciona curl, jq y un shell. Crear client/Dockerfile:

cat > client/Dockerfile <<'DOCKERFILE'
FROM alpine:3.22

RUN apk add --no-cache curl jq

WORKDIR /work
ENTRYPOINT ["/bin/sh", "-c"]
CMD ["sleep infinity"]
DOCKERFILE

El uso de un contenedor separado demuestra que cada operación atraviesa la red Compose a través de HTTPS. No se ejecuta nada con docker compose exec mq después de la verificación de preparación del contenedor.

6. Configurar el entorno Docker

Crear compose.yaml:

cat > compose.yaml <<'YAML'
services:
  mq:
    image: icr.io/ibm-messaging/mq:10.0.0.0-r2
    platform: linux/amd64
    environment:
      LICENSE: accept
      MQ_QMGR_NAME: RESTQM
      MQ_DEV: "true"
    secrets:
      - mqAdminPassword
      - mqAppPassword
    ports:
      - "9443:9443"
    volumes:
      - qmdata:/mnt/mqm
    healthcheck:
      test: ["CMD-SHELL", "dspmq -m RESTQM | grep -q 'STATUS(Running)'"]
      interval: 5s
      timeout: 5s
      retries: 40

  rest-client:
    build:
      context: ./client
    profiles: ["tools"]
    command: ["sleep infinity"]
    volumes:
      - ./client:/work
    depends_on:
      mq:
        condition: service_healthy

volumes:
  qmdata:

secrets:
  mqAdminPassword:
    file: ./secrets/mqAdminPassword
  mqAppPassword:
    file: ./secrets/mqAppPassword
YAML

El perfil de herramientas mantiene el contenedor del cliente fuera de una inicialización dirigida únicamente al Administrador de colas. Later sections enable the profile because all REST requests are executed in this container.

7. Inicie IBM MQ y espere mqweb

Iniciar el administrador de colas:

docker compose up -d mq
docker compose ps

Espere hasta que la verificación de estado del Administrador de colas sea exitosa:

until [ "$(docker inspect \
  --format='{{.State.Health.Status}}' \
  mq-rest-api-lab-mq-1 2>/dev/null)" = "healthy" ]; do
  docker compose ps
  sleep 5
done

Inicie el contenedor de herramientas:

docker compose --profile tools up -d rest-client

Es posible que el Administrador de colas se recupere un poco antes de que mqweb esté listo. Espere una respuesta HTTPS:

until docker compose exec rest-client sh -lc '
  curl --silent --insecure --output /dev/null \
       https://mq:9443/ibmmq/rest/v3/login
'; do
  sleep 15
done

Abra el explorador interactivo de API REST

IBM MQ puede publicar una interfaz Swagger que lista los recursos REST, métodos HTTP, parámetros, cuerpos de solicitud, códigos de respuesta y esquemas disponibles. También proporciona controles Prueba para realizar las operaciones.

La página web es:

https://localhost:9443/api/explorer/

Esta es la página de descubrimiento de API pública expuesta por Liberty. Es la página más útil para descubrir operaciones mientras se trabaja en el artículo y cubre más que el pequeño conjunto de indicaciones seleccionadas para esta práctica de laboratorio. El punto final protegido /ibm/api/explorer/ también está registrado, pero con la configuración de seguridad mqweb de este contenedor puede fallar durante la autenticación. Por lo tanto, utilice la página de descubrimiento público para obtener documentación.

API Discovery es una característica funcionalmente estabilizada de Liberty: todavía está disponible, pero IBM ya no está comprometida con su desarrollo y mejora. No está habilitado en la configuración mqweb predeterminada del contenedor.

El contenedor en ejecución lee su configuración de Liberty de la ruta de datos de MQ en /var/mqm, no de la plantilla de imagen en /opt/mqm. Exporte el archivo mqwebuser.xml activo al proyecto:

docker compose exec -T mq \
  cat /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml \
  > mqwebuser.xml

test -s mqwebuser.xml
head -n 5 mqwebuser.xml

El uso de docker compose exec -T evita caracteres pseudo-terminales en la salida y aquí es más confiable que copiar el archivo con docker compose cp. El comando test detiene la secuencia si la exportación no produce un archivo que no esté vacío.

El archivo generado por el contenedor no contiene un elemento <featureManager>. Agregue este elemento justo antes de la etiqueta de cierre </server>. El reemplazo opera en la propia etiqueta, por lo que también funciona cuando <server> y </server> están en la misma línea:

awk '
  !inserted && /<\/server>/ {
    sub(/<\/server>/,
        "  <featureManager>\n" \
        "    <feature>apiDiscovery-1.0</feature>\n" \
        "  </featureManager>\n" \
        "</server>")
    inserted=1
  }
  { print }
  END {
    if (!inserted) exit 1
  }
' mqwebuser.xml > mqwebuser.xml.updated &&
mv mqwebuser.xml.updated mqwebuser.xml

El movimiento del archivo solo se producirá si awk encuentra </server> y se completa correctamente. Confirme que el nuevo recurso y el elemento circundante estén presentes y que el recurso solo aparezca una vez:

grep -n -C 2 'apiDiscovery-1.0' mqwebuser.xml
test "$(grep -c 'apiDiscovery-1.0' mqwebuser.xml)" -eq 1

Vuelva a escribir la configuración actualizada a través de un shell que se ejecuta dentro del contenedor. Esto es importante porque el contenedor se asigna internamente al directorio de datos de MQ.

docker compose exec -T mq sh -c \
  'cat > /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml' \
  < mqwebuser.xml

Verifique el archivo instalado antes de reiniciar mqweb:

docker compose exec mq sh -lc '
  grep -n -C 2 "apiDiscovery-1.0" \
    /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml
'

Reinicie el contenedor MQ para que su punto de entrada inicie y continúe monitoreando mqweb con la configuración actualizada.

docker compose restart mq

mq_ready=0

for attempt in $(seq 1 24); do
  if docker compose exec mq dspmq |
       grep -q 'STATUS(Running)' &&
     docker compose exec mq dspmqweb |
       grep -q "Server 'mqweb' is running"; then
    mq_ready=1
    break
  fi
  sleep 15
done

if [ "$mq_ready" -ne 1 ]; then
  docker compose ps -a
  docker compose logs --tail 100 mq
  false
fi

Confirme que Liberty haya instalado la característica:

docker compose logs mq |
  grep 'CWWKF0012I' |
  tail -n 1 |
  grep 'apiDiscovery-1.0'

No continúe a menos que el comando final imprima una lista de recursos que contenga apiDiscovery-1.0.

No utilice la página del Explorador como verificación de preparación. Cuando API Discovery no está disponible, una ruta de navegador desconocida puede regresar a MQ Console y aún devolver HTTP 200. En su lugar, permita a mqweb hasta dos minutos para que el punto final público /api/docs/ esté disponible y requiera un documento Swagger que contenga swagger y paths:

api_ready=0

for attempt in $(seq 1 24); do
  if docker compose exec rest-client sh -lc '
    curl --silent --show-error --fail --insecure \
         https://mq:9443/api/docs/ |
    jq --exit-status ".swagger and .paths" >/dev/null
  '; then
    api_ready=1
    break
  fi
  sleep 15
done

if [ "$api_ready" -ne 1 ]; then
  docker compose exec mq dspmqweb
  docker compose logs --tail 100 mq
  false
fi

Ahora abra https://localhost:9443/api/explorer/ en el navegador. Amplíe las secciones administrativas y de mensajería para ver las operaciones utilizadas más adelante en el laboratorio.

La misma descripción de Swagger 2 está disponible como JSON:

https://localhost:9443/api/docs/

Este documento es útil para importar la API a herramientas compatibles o inspeccionar su funcionamiento y definiciones de esquema mediante programación:

docker compose exec -T rest-client sh -lc '
  curl --silent --insecure https://mq:9443/api/docs/ |
  jq ".info, (.paths | keys[])"
'

El API Explorer público expone documentación, no acceso inseguro a MQ. Las solicitudes a las API REST, tanto administrativas como de mensajería, aún requieren autenticación, funcionalidad mqweb aplicable, autoridad de objeto MQ y protección CSRF cuando sea necesario. Las siguientes secciones utilizan solicitudes curl autenticadas para que estos requisitos sigan siendo explícitos.

Confirme la versión de MQ:

docker compose exec mq dspmqver

El resultado debería identificar IBM MQ 10.0.0.0.

8. Inicie sesión y almacene el token LTPA

Inicie sesión como administrador:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie-jar cookies.txt \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/login |
  jq .
' <<'JSON'
{
  "username": "admin",
  "password": "AdminPassw0rd!"
}
JSON

--cookie-jar cookies.txt almacena la cookie devuelta por mqweb. Inspeccione su estructura:

docker compose exec -T rest-client sh -lc '
  awk "/^#/ { next } NF { print \$1, \$3, \$6 }" cookies.txt
'

Ver inicio de sesión actual:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       https://mq:9443/ibmmq/rest/v3/login |
  jq .
'

La respuesta identifica al usuario autenticado y sus roles mqweb.

Trate cookies.txt como una credencial. Cualquiera que obtenga un token LTPA válido podrá actuar a través de esta sesión hasta que caduque o sea invalidado.

El administrador pertenece a la funcionalidad administrativa mqweb, pero la API REST del sistema de mensajería requiere la funcionalidad MQWebUser. Cree una sesión de aplicación separada:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie-jar app-cookies.txt \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/login |
  jq .
' <<'JSON'
{
  "username": "app",
  "password": "AppPassw0rd!"
}
JSON

Mantenga identidades separadas en todo el laboratorio:

9. Inspeccionar el administrador de colas

Enumere los administradores de colas visibles para el servidor mqweb:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       https://mq:9443/ibmmq/rest/v3/admin/qmgr |
  jq .
'

Obtenga el estado de RESTQM:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       "https://mq:9443/ibmmq/rest/v3/admin/qmgr/RESTQM?attributes=*" |
  jq .
'

Las rutas REST distinguen entre mayúsculas y minúsculas. RESTQM y restqm no son lo mismo.

El recurso del Administrador de colas es un recurso administrativo. La API de IBM MQ v3 maneja muchos cambios administrativos a nivel de objeto de manera diferente: expone una representación JSON de MQSC a través de un punto final.

10. Crea una cola con JSON MQSC

La URL de MQSC versión 3 es:

/admin/action/qmgr/{qmgrName}/mqsc

Crear cola DEV.REST.REQUESTS. La imagen MQ del desarrollador otorga autoridad MQ a la identidad de la aplicación en el espacio de nombres DEV.**:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq .
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "define",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS",
  "parameters": {
    "replace": "yes",
    "descr": "Queue created through the administrative REST API",
    "maxdepth": 100
  }
}
JSON

Una respuesta exitosa tiene:

{
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}

La respuesta completa también contiene una entrada en commandResponse. Siempre revisa los códigos. Mostrar JSON es útil durante el aprendizaje, pero la automatización siempre debe probar el éxito de la operación.

Mostrar atributos de la cola seleccionada:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq ".commandResponse[].parameters"
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "descr",
    "maxdepth",
    "put",
    "get"
  ]
}
JSON

Este no es un esquema JSON privado arbitrario inventado por el laboratorio. El comando, el calificador, los parámetros y los parámetros de respuesta se correlacionan con conceptos MQSC.

11. Cambiar la cola

Aumente la profundidad máxima de la cola:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq .
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "alter",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS",
  "parameters": {
    "maxdepth": 200,
    "descr": "Queue managed through IBM MQ REST API v3"
  }
}
JSON

Repita la solicitud de visualización de la sección anterior y confirme que maxdepth ahora es 200.

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq ".commandResponse[].parameters"
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "descr",
    "maxdepth",
    "put",
    "get"
  ]
}
JSON

Para una automatización repetible, prefiera comandos que converjan a un estado deseado. La opción replace hace que la configuración inicial sea conveniente en un laboratorio desechable, pero reemplazar un objeto de producción existente sin comparar sus atributos actuales puede anular la configuración prevista.

12. Publicar mensajes con la API REST de mensajería

La función de mensaje es:

/messaging/qmgr/{qmgrName}/queue/{queueName}/message

Coloque un documento JSON persistente con una caducidad de dos minutos:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --dump-header put.headers \
       --output /dev/null \
       --write-out "HTTP %{http_code}\n" \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json;charset=utf-8" \
       --header "ibm-mq-md-persistence: persistent" \
       --header "ibm-mq-md-expiry: 120000" \
       --header "ibm-mq-md-priority: 7" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message
' <<'JSON'
{
  "orderId": "ORD-1001",
  "status": "created",
  "source": "mq-rest-api-lab"
}
JSON

El cuerpo de la solicitud REST se convierte en el cuerpo del mensaje MQ. Las respuestas POST exitosas no tienen cuerpo de respuesta. El laboratorio almacena los encabezados de respuesta e imprime el estado HTTP.

Inspeccione los encabezados MQ devueltos por mqweb:

docker compose exec rest-client sh -lc '
  grep -i "^ibm-mq-" put.headers
'

Los encabezados incluyen identificadores asignados al mensaje.

Pon un segundo mensaje de texto plano:

docker compose exec rest-client sh -lc '
  curl --silent --show-error --insecure \
       --output /dev/null \
       --write-out "HTTP %{http_code}\n" \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: text/plain;charset=utf-8" \
       --data "second message" \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message
'

La API REST de intercambio de mensajes acepta cuerpos basados ​​en texto. Un tipo de contenido JSON no transforma IBM MQ en un Registro de esquema ni valida el documento con un contrato de aplicación.

13. Inspeccionar administrativamente la profundidad de la cola

Utilice MQSC con representación JSON para obtener el estado de la cola:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq ".commandResponse[].parameters"
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qstatus",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "curdepth",
    "ipprocs",
    "opprocs"
  ]
}
JSON

La profundidad esperada actual es 2.

14. Explorar la lista de mensajes

Explore los metadatos de los mensajes sin eliminarlos:

docker compose exec rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/messagelist |
  tee messagelist.json |
  jq .
'

La matriz messages contiene información resumida, como identificadores de mensajes, identificadores de correlación cuando están presentes y formato. No contiene el cuerpo de cada mensaje.

Confirme que la navegación no consumió nada repitiendo la solicitud de estado de la cola. La profundidad debe seguir siendo 2.

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq ".commandResponse[].parameters"
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qstatus",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "curdepth",
    "ipprocs",
    "opprocs"
  ]
}
JSON

Navegar por una cola de producción con muchos mensajes no sustituye a un índice de aplicación o una consulta empresarial. Puede resultar costoso y los ID de mensajes son identificadores operativos, no claves comerciales. El uso de IBM MQ como base de datos es un antipatrón bien conocido.

15. Navegar por el cuerpo de un mensaje

Utilice GET en el recurso de mensaje para devolver un mensaje coincidente sin eliminarlo:

docker compose exec rest-client sh -lc '
  curl --silent --show-error --insecure \
       --dump-header browse.headers \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Accept: application/json" \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message
'

El cuerpo de la respuesta contendrá la carga útil del mensaje y los encabezados de la respuesta describirán sus metadatos MQ. Verifique nuevamente la profundidad de la cola: aún debería ser 2.

Al recibir o navegar, la API REST de mensajería admite mensajes con formato MQSTR y JMS TextMessage. Los formatos binarios o específicos de la aplicación requieren un cliente IBM MQ u otra capa de integración que los comprenda.

16. Recibir un mensaje y eliminarlo

Utilice DELETE en el mismo recurso para obtener y eliminar un mensaje:

docker compose exec rest-client sh -lc '
  curl --silent --show-error --insecure \
       --dump-header receive.headers \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Accept: application/json" \
       --request DELETE \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message
'

Repita la solicitud de estado de la cola. La profundidad esperada ahora es 1.

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq ".commandResponse[].parameters"
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qstatus",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "curdepth",
    "ipprocs",
    "opprocs"
  ]
}
JSON

La recepción destructiva se realiza bajo SYNCPOINT mediante la implementación REST. Una respuesta HTTP exitosa significa que la operación REST está completa, pero la aplicación consumidora sigue siendo responsable de la integridad de un extremo a otro: no debe perder datos después de que MQ haya eliminado el mensaje.

Crea una estrategia de idempotencia. Una interrupción de la red puede dejar a la aplicación sin estar segura de si una solicitud ha llegado al servidor. Reintentar ciegamente un mensaje POST puede crear duplicados. Reintentar ciegamente una recepción destructiva puede recuperarse y eliminar el siguiente mensaje.

17. Comprender los errores REST y MQ

Hay dos niveles de éxito:

1. La solicitud HTTP llegó y fue procesada por mqweb.
2. La operación MQ subyacente fue exitosa.

Demuestre la diferencia mostrando una cola que no existe:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --output missing-queue.json \
       --write-out "HTTP %{http_code}\n" \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc

  jq . missing-queue.json
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qlocal",
  "name": "DOES.NOT.EXIST"
}
JSON

El estado HTTP puede ser 200 porque mqweb envió correctamente la acción MQSC y devolvió su resultado. El JSON informa fallas al devolver valores como:

{
  "overallCompletionCode": 2,
  "overallReasonCode": 3008
}

Una respuesta de comando individual también puede contener el código de motivo MQ 2085, MQRC_UNKNOWN_OBJECT_NAME.

Una automatización que solo verifica curl --fail no nota este fallo. Verifique el estado del transporte y los datos de finalización de MQ:

docker compose exec rest-client sh -lc '
  jq -e "
    .overallCompletionCode == 0 and
    ([.commandResponse[].completionCode] | all(. == 0))
  " missing-queue.json
'

El comando sale deliberadamente de un valor distinto de cero.

Otras fallas, como URL con formato incorrecto, JSON no válido, fallas de autenticación o funciones faltantes en puntos finales REST dedicados, pueden generar respuestas HTTP 4xx o 5xx con un mensaje MQWB. Preservar el cuerpo de respuesta al diagnosticarlos.

18. Cree código auxiliar MQSC REST reutilizable

Las opciones repetidas de curl facilitan cometer errores. Crear client/mqsc-rest.sh:

cat > client/mqsc-rest.sh <<'SH'
#!/bin/sh
set -eu

BASE_URL=${MQ_REST_BASE_URL:-https://mq:9443/ibmmq/rest/v3}
QMGR=${MQ_QMGR:-RESTQM}
COOKIE_FILE=${MQ_COOKIE_FILE:-cookies.txt}

if [ "$#" -ne 1 ]; then
  echo "usage: $0 payload.json" >&2
  exit 2
fi

payload=$1
response=$(mktemp)
trap 'rm -f "$response"' EXIT

http_code=$(
  curl --silent --show-error --insecure \
       --output "$response" \
       --write-out "%{http_code}" \
       --cookie "$COOKIE_FILE" \
       --header "ibm-mq-rest-csrf-token: automation" \
       --header "Content-Type: application/json" \
       --data @"$payload" \
       "$BASE_URL/admin/action/qmgr/$QMGR/mqsc"
)

cat "$response" | jq .

case "$http_code" in
  2??) ;;
  *)
    echo "HTTP request failed with status $http_code" >&2
    exit 1
    ;;
esac

jq -e '
  .overallCompletionCode == 0 and
  ([.commandResponse[].completionCode] | all(. == 0))
' "$response" >/dev/null
SH

chmod +x client/mqsc-rest.sh

Cree una carga útil de visualización:

cat > client/display-queue.json <<'JSON'
{
  "type": "runCommandJSON",
  "command": "display",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS",
  "responseParameters": [
    "descr",
    "maxdepth"
  ]
}
JSON

Ejecute el código auxiliar:

docker compose exec rest-client \
  ./mqsc-rest.sh display-queue.json

El código auxiliar comprueba el éxito de HTTP y MQ por separado. Una autorización de producción también debe:

• Renovar una sesión caducada
• Validar el certificado del servidor.
• Evite registrar secretos y valores de cookies
• Aplicar tiempos de espera de solicitud
• Sólo reintente las operaciones que se puedan repetir de forma segura
• Emitir información de auditoría estructurada.
• Distinguir advertencias de fallas cuando un comando puede regresar

19. Eliminar la cola del laboratorio

La cola todavía contiene un mensaje. Una eliminación normal debería fallar a menos que se vacíe la cola o la eliminación la borre explícitamente. Reciba el mensaje restante:

docker compose exec rest-client sh -lc '
  curl --silent --show-error --insecure \
       --output /dev/null \
       --cookie app-cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --request DELETE \
       https://mq:9443/ibmmq/rest/v3/messaging/qmgr/RESTQM/queue/DEV.REST.REQUESTS/message
'

Eliminar cola vacía:

docker compose exec -T rest-client sh -lc '
  curl --silent --show-error --insecure \
       --cookie cookies.txt \
       --header "ibm-mq-rest-csrf-token: lab" \
       --header "Content-Type: application/json" \
       --data @- \
       https://mq:9443/ibmmq/rest/v3/admin/action/qmgr/RESTQM/mqsc |
  jq .
' <<'JSON'
{
  "type": "runCommandJSON",
  "command": "delete",
  "qualifier": "qlocal",
  "name": "DEV.REST.REQUESTS"
}
JSON

No haga que PURGE sea el comportamiento predeterminado de una herramienta de limpieza de producción.

20. Salir

Invalide ambas sesiones LTPA:

docker compose exec rest-client sh -lc '
  for cookie in cookies.txt app-cookies.txt; do
    curl --silent --show-error --insecure \
         --output /dev/null \
         --write-out "$cookie: HTTP %{http_code}\n" \
         --cookie "$cookie" \
         --cookie-jar "$cookie" \
         --header "ibm-mq-rest-csrf-token: lab" \
         --request DELETE \
         https://mq:9443/ibmmq/rest/v3/login
  done
'

Eliminar archivos de cookies locales:

rm -f client/cookies.txt client/app-cookies.txt

El cierre de sesión explícito reduce la duración de una sesión que ya no es necesaria. Esto no elimina la necesidad de proteger la cookie mientras está activa.

21. Consideraciones sobre el diseño de producción

22. Solución de problemas

El contenedor MQ finaliza durante la inicialización

Inspeccione los diagnósticos de arranque completos:

docker compose ps -a
docker compose logs --tail 200 mq

Confirme que ambos archivos secretos existan, contengan contraseñas de al menos ocho caracteres y que Docker Compose pueda leerlos.

El puerto 9443 ya está en uso

Es posible que todavía se esté ejecutando otro laboratorio:

docker ps --format 'table {{.Names}}\t{{.Ports}}'

Detenga el otro proyecto o cambie la asignación del lado del host, por ejemplo "9444:9443". Los contenedores de este laboratorio siguen usando https://mq:9443`; sólo las solicitudes del host utilizan el puerto modificado.

Iniciar sesión devuelve 401

Para comprobar:

• La contraseña en secrets/mqAdminPassword
• Que el Administrador de colas se creó después de proporcionar el secreto actual
• El nombre de usuario exacto en minúsculas admin
• Si un archivo de cookies antiguo confunde la prueba

Al cambiar las credenciales iniciales, elimine el volumen desechable y vuelva a crear el Administrador de colas.

Se rechazó una solicitud de modificación.

Asegúrese de que la solicitud incluya:

ibm-mq-rest-csrf-token: any-value

Confirme también que la cookie de sesión esté presente y no haya caducado.

curl informa un error de certificado

Esto es lo esperado si elimina --insecure cuando utiliza el certificado generado por la imagen del desarrollador. La solución de producción correcta es confiar en la CA emisora ​​y utilizar un certificado cuyo asunto coincida con el nombre de host, y no restaurar --insecure.

HTTP 200 contiene un error de MQ

Esto es lo esperado para una acción MQSC que mqweb ha enviado correctamente. Inspeccionar:

overallCompletionCode
overallReasonCode
commandResponse[].completionCode
commandResponse[].reasonCode

Trate los resultados de HTTP y MQ como capas separadas.

Explorar o recibir devoluciones no hay mensajes utilizables

La API REST de mensajería puede explorar o recibir solo formatos de texto compatibles, como MQSTR y JMS TextMessage. Inspeccione la lista de mensajes y considere si otra aplicación ha colocado un formato binario o específico de la aplicación.

23. Lo que muestra el laboratorio

El laboratorio estableció un modelo operativo basado en HTTP para IBM MQ:

• mqweb autenticó un cliente remoto y emitió un token de sesión LTPA
• La API REST administrativa expuso el estado del Administrador de colas
• El punto final de acción MQSC versión 3 creó, vio, cambió y eliminó una cola
• API REST de mensajería coloca, explora y recibe mensajes de texto destructivamente
• Estado de la cola de acciones de mensajes conectado a la observación administrativa.
• El éxito de HTTP y el éxito del comando MQ se han validado de forma independiente
• El cliente no necesitaba bibliotecas cliente MQ ni acceso a archivos del Administrador de colas

Las API REST no son un reemplazo universal para MQI, PCF o MQSC. Son otra interfaz controlada, particularmente útil para herramientas orientadas a web, automatización, portales operativos y mensajería de texto sin formato.

24. Documentación de IBM

• La consola IBM MQ y REST API
• Usando REST administrativo API
• Comandos MQSC formateados en JSON
• Usando la mensajería REST API
• Colocar un mensaje con la mensajería REST API
• Navegando por una lista de mensajes
• Autenticación API REST basada en token
• Consola IBM MQ y seguridad API REST
• Descubrimiento de API REST y Swagger UI

25. Limpieza

Detenga ambos contenedores y elimine el volumen del Administrador de colas:

cd "$HOME/mq-rest-api-lab"
docker compose --profile tools down -v

Eliminar carpeta del proyecto:

cd "$HOME"
rm -rf "$HOME/mq-rest-api-lab"