Operando o IBM MQ remotamente com suas APIs REST

Os aplicativos IBM MQ tradicionalmente se conectam a uma biblioteca cliente MQ e usam a Message Queue Interface. Os administradores geralmente usam MQSC, PCF, IBM MQ Console ou IBM MQ Explorer. Essas interfaces continuam importantes, mas não são a única maneira de trabalhar com um gerenciador de filas.

O IBM MQ também fornece APIs HTTP por meio do servidor mqweb. Eles são úteis quando uma ferramenta de automação, portal de operações, script de diagnóstico ou aplicativo leve pode falar HTTPS, mas não deve transportar uma instalação do cliente MQ.

Este artigo cria um laboratório que usa duas APIs relacionadas, mas distintas:

O laboratório cria sessões administrativas e de aplicativos separadas, armazena seus cookies LTPA, cria e altera uma fila, troca mensagens, inspeciona a profundidade da fila, interpreta erros e efetua logout. Cada solicitação se origina em um contêiner de ferramentas separado. O cliente REST não possui acesso shell, sistema de arquivos ou MQI ao gerenciador de filas.

Considerações de laboratório: a imagem do IBM MQ Advanced for Developers e seu certificado da web gerado são adequados para um exercício de estação de trabalho descartável. Os comandos usam curl --insecure porque o certificado gerado não é confiável para o contêiner de ferramentas. A automação de produção deve validar o certificado do servidor mqweb, proteger credenciais e cookies, atribuir identidades com escopo restrito e restringir o acesso à rede à porta 9443.

1. Duas APIs atrás de um endpoint HTTPS

O IBM MQ Console e as APIs REST são executados no servidor mqweb WebSphere Liberty. O listener HTTPS padrão é a porta 9443 e o prefixo da API da versão 3 é:

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

As duas APIs realizam trabalhos diferentes sob esse prefixo.

Os recursos administrativos começam com:

/admin

Os recursos de mensagens começam com:

/messaging

Por exemplo, estas são operações diferentes:

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

Enquanto o primeiro solicita ao mqweb o status do gerenciador de filas, o segundo coloca uma mensagem do MQ. Compartilhar a infraestrutura HTTP e de autenticação não torna a administração e as mensagens equivalentes.

A distinção também importa para autorização. Uma identidade pode ter permissão para efetuar login no mqweb, mas ainda não possui as autoridades MQ necessárias para entrar ou sair de uma fila. Por outro lado, uma autoridade MQ não concede por si só uma função mqweb.

2. Autenticação, cookies e proteção CSRF

O IBM MQ suporta autenticação básica HTTP, autenticação de certificado de cliente e autenticação baseada em token para a API REST. Este laboratório usa autenticação de token para que a senha seja enviada uma vez, em vez de repetida a cada solicitação.

O cliente publica credenciais para:

POST /ibmmq/rest/v3/login

Se a autenticação for bem-sucedida, o mqweb retornará um token LTPA em um cookie e o cliente enviará esse cookie com solicitações posteriores. O tempo de vida do token padrão é finito e pode ser configurado, portanto, um cliente de automação deve poder efetuar login novamente após a expiração.

Solicitações que mudam de estado também carregam o cabeçalho:

ibm-mq-rest-csrf-token: lab

O valor não é secreto e pode ser qualquer valor, inclusive um valor vazio. Sua presença é a proteção exigida pelo mqweb para operações como POST, PATCH e DELETE e não substitui a autenticação.

O fluxo resultante é:

Sempre use HTTPS para que as credenciais em uma solicitação de login sejam protegidas por TLS durante o trânsito.

3. Requisitos de laboratório

Use uma máquina de revelação descartável com:

• Docker Engine ou Docker Desktop
• Docker Compor v2
• Pelo menos 4 GB de memória livre
• Acesso à Internet para icr.io e Docker Hub
• Um host Linux AMD64 ou Docker Desktop em silício Apple com emulação AMD64

O laboratório fixa estas imagens:

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

A imagem MQ é licenciada apenas para uso em desenvolvimento. Aceitar sua licença no arquivo Compose não concede direitos de produção.

4. Crie o projeto

Crie um diretório de laboratório vazio:

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

Crie os arquivos de senha usados ​​como segredos do Docker:

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

A senha do aplicativo não é fundamental neste laboratório, mas a imagem do desenvolvedor espera credenciais para ambas as identidades de desenvolvimento predefinidas.

5. Construa o contêiner de ferramentas REST

O contêiner de ferramentas fornece apenas curl, jq e um shell. Crie o 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

O uso de um contêiner separado prova que cada operação atravessa a rede do Compose por HTTPS. Nada é executado com docker compose exec mq após a verificação de prontidão.

6. Defina o ambiente Docker

Crie 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

O perfil de ferramentas mantém o contêiner do cliente fora de uma inicialização somente do gerenciador de filas. As seções posteriores habilitam o perfil porque todas as solicitações REST são executadas nesse contêiner.

7. Inicie o IBM MQ e aguarde mqweb

Inicie o gerenciador de filas:

docker compose up -d mq
docker compose ps

Aguarde até que a verificação de funcionamento do gerenciador de filas seja bem-sucedida:

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

O Compose deriva o nome do contêiner do diretório do projeto. Se você usou outro nome de diretório, confie em docker compose ps ou use esta verificação mais simples:

until docker compose exec mq \
  dspmq -m RESTQM 2>/dev/null | grep -q 'STATUS(Running)'; do
  sleep 5
done

Inicie o contêiner de ferramentas:

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

O gerenciador de filas pode ficar íntegro pouco antes de mqweb estar pronto. Aguarde uma resposta 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 o REST API Explorer interativo

O IBM MQ pode publicar uma interface Swagger que lista os recursos REST, métodos HTTP, parâmetros, corpos de solicitação, códigos de resposta e esquemas disponíveis. Ele também fornece controles Experimente para enviar operações do navegador.

A página é:

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

Esta é a página pública de descoberta de API exposta pelo Liberty. É a página mais útil para descobrir operações enquanto se trabalha no artigo e abrange mais do que o pequeno conjunto de solicitações selecionadas para este laboratório. O terminal /ibm/api/explorer/ protegido também é registrado, mas com a configuração de segurança mqweb deste contêiner ele pode falhar durante a autenticação; use a página de descoberta pública para a documentação.

O API Discovery é um recurso estabilizado do Liberty: ele permanece disponível, mas a IBM não o desenvolve mais como um recurso estratégico. Ele não está ativado na configuração mqweb padrão do contêiner.

O contêiner em execução lê sua configuração do Liberty no caminho de dados do MQ em /var/mqm, não no modelo de imagem em /opt/mqm. Exporte o arquivo mqwebuser.xml ativo para o projeto:

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

Usar docker compose exec -T evita caracteres pseudoterminais na saída e é mais confiável aqui do que copiar o arquivo com docker compose cp. O comando test também interrompe a sequência se a exportação não produzir um arquivo não vazio.

O arquivo gerado pelo contêiner não contém um elemento <featureManager>. Adicione um gerenciador de recursos completo imediatamente antes da tag de fechamento </server>. A substituição opera na própria tag, portanto também funciona quando <server> e </server> estão na mesma linha:

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

A movimentação ocorrerá somente se awk localizar </server> e for concluído com êxito. Confirme se o novo recurso e o elemento circundante estão presentes e se o recurso aparece apenas uma vez:

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

Escreva a configuração atualizada de volta por meio de um shell em execução dentro do contêiner. Isto é importante porque o contêiner mapeia o diretório de dados do MQ internamente

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

Verifique o arquivo instalado antes de reiniciar o mqweb:

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

Reinicie o contêiner MQ para que seu ponto de entrada inicie e continue supervisionando o mqweb com a configuração atualizada.

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 se o Liberty instalou o recurso:

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

Não continue a menos que o comando final imprima uma lista de recursos contendo apiDiscovery-1.0.

Não use a própria página do Explorer como verificação de prontidão. Quando o API Discovery não está disponível, um caminho de navegador desconhecido pode retornar ao MQ Console e ainda retornar HTTP 200. Em vez disso, permita que o mqweb tenha até dois minutos para disponibilizar o terminal público /api/docs/ e exija um documento Swagger contendo swagger e 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

Agora abra https://localhost:9443/api/explorer/ em um navegador. Expanda as seções administrativas e de mensagens para ver as operações usadas posteriormente no laboratório.

A mesma descrição do Swagger 2 está disponível como JSON:

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

Esse documento é útil para importar a API para ferramentas compatíveis ou inspecionar sua operação e definições de esquema de forma programática:

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

O API Explorer público expõe documentação, e não acesso não seguro ao MQ. As solicitações para as APIs REST administrativas e de mensagens ainda precisam de autenticação, da função mqweb aplicável, da autoridade do objeto MQ e da proteção CSRF quando necessário. As seções a seguir usam solicitações curl autenticadas para que esses requisitos permaneçam explícitos.

Confirme a versão do MQ:

docker compose exec mq dspmqver

A saída deve identificar o IBM MQ 10.0.0.0.

8. Faça login e armazene o token LTPA

Faça login como administrador do desenvolvedor:

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 armazena o cookie retornado pelo mqweb. Inspecione sua estrutura:

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

Consulte o login atual:

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

A resposta identifica o usuário autenticado e suas funções mqweb.

Trate cookies.txt como uma credencial. Qualquer pessoa que obtiver um token LTPA válido poderá atuar como essa sessão até que ela expire ou seja invalidada.

O administrador pertence à função administrativa mqweb, mas a API REST do sistema de mensagens requer a função MQWebUser. Crie uma sessão de aplicativo 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

Mantenha as identidades separadas em todo o laboratório:

9. Inspecione o gerenciador de filas

Listar gerenciadores de filas visíveis para 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 .
'

Status da solicitação para 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 .
'

Os caminhos REST diferenciam maiúsculas de minúsculas. RESTQM e restqm não são intercambiáveis.

O recurso do gerenciador de filas é um recurso administrativo. A API do IBM MQ v3 manipula muitas mudanças administrativas no nível do objeto de maneira diferente: ela expõe uma representação JSON do MQSC por meio de um terminal de ação.

10. Crie uma fila com JSON MQSC

A URL de ação do MQSC versão 3 é:

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

Crie a fila DEV.REST.REQUESTS. A imagem do desenvolvedor concede autoridade MQ à identidade do aplicativo sob o namespace 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

Uma resposta bem-sucedida tem:

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

A resposta completa também contém uma entrada em commandResponse. Sempre examine os códigos; imprimir JSON é útil durante o aprendizado, mas a automação deve garantir o sucesso.

Exibir atributos da fila selecionada:

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 não é um esquema JSON privado arbitrário inventado pelo laboratório. O comando, o qualificador, os parâmetros e os parâmetros de resposta são mapeados para conceitos do MQSC.

11. Altere a fila

Aumente a profundidade máxima da fila:

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 a solicitação de exibição da seção anterior e confirme se maxdepth agora é 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 automação repetível, prefira comandos que convirjam para um estado desejado. A opção replace torna a definição inicial conveniente em um laboratório descartável, mas substituir um objeto de produção existente sem comparar seus atributos atuais pode apagar a configuração intencional.

12. Coloque mensagens com a API REST de mensagens

O recurso da mensagem é:

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

Coloque um documento JSON persistente com expiração de dois 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

O corpo da solicitação se torna o corpo da mensagem do MQ. As respostas POST bem-sucedidas não possuem corpo de resposta. O laboratório armazena os cabeçalhos de resposta e imprime o status HTTP.

Inspecione os cabeçalhos do MQ retornados pelo mqweb:

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

Os cabeçalhos incluem identificadores atribuídos à mensagem.

Coloque uma segunda mensagem de texto simples:

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
'

A API REST de mensagens aceita corpos baseados em texto. Um tipo de conteúdo JSON não transforma o IBM MQ em um registro de esquema nem valida o documento em relação a um contrato de aplicativo.

13. Inspecione a profundidade da fila administrativamente

Use JSON MQSC para solicitar o status da fila:

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

A profundidade atual esperada é 2.

14. Navegue pela lista de mensagens

Navegue pelos metadados das mensagens sem removê-las:

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 .
'

A matriz messages contém informações resumidas, como identificadores de mensagens, identificadores de correlação quando presentes e formato. Ele não contém o corpo de cada mensagem.

Confirme se a navegação não consumiu nada repetindo a solicitação de status da fila. A profundidade deve permanecer 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 em uma grande fila de produção não substitui um índice de aplicativo ou uma consulta comercial. Pode ser caro e os IDs das mensagens são identificadores operacionais, e não chaves comerciais. Usar o IBM MQ como banco de dados é um antipadrão bem conhecido.

15. Navegue pelo corpo de uma mensagem

Use GET no recurso de mensagem para retornar uma mensagem correspondente sem removê-la:

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
'

O corpo da resposta é a primeira carga útil da mensagem e os cabeçalhos de resposta descrevem seus metadados do MQ. Verifique novamente a profundidade da fila: ainda deve ser 2.

Ao receber ou navegar, a API REST de mensagens suporta mensagens formatadas MQSTR e JMS TextMessage. Os formatos binários ou específicos do aplicativo requerem um cliente IBM MQ ou outra camada de integração que os compreenda.

16. Receba uma mensagem de forma destrutiva

Use DELETE no mesmo recurso para recuperar e remover uma mensagem:

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 a solicitação de status da fila. A profundidade esperada agora é 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

O recebimento destrutivo é executado no ponto de sincronização pela implementação REST. Uma resposta HTTP bem-sucedida significa que a operação REST foi concluída, mas o aplicativo consumidor ainda possui o problema mais difícil de ponta a ponta: ele não deve perder os dados depois que o MQ tiver removido a mensagem.

Para processamento de negócios, crie uma estratégia de idempotência. Uma interrupção na rede pode deixar o chamador sem saber se uma solicitação chegou ao servidor. Tentar novamente cegamente uma mensagem POST pode criar duplicatas; tentar novamente cegamente um recebimento destrutivo pode retornar a próxima mensagem.

17. Entenda os erros REST e MQ

Existem duas camadas de sucesso:

1. A solicitação HTTP alcançou e foi processada pelo mqweb.
2. A operação subjacente do MQ foi bem-sucedida.

Demonstre a distinção exibindo uma fila que não 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

O status HTTP pode ser 200 porque mqweb enviou com êxito a ação MQSC e retornou seu resultado. O JSON relata falha por meio de valores como:

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

Uma resposta de comando individual também pode conter o código de razão do MQ 2085, MQRC_UNKNOWN_OBJECT_NAME.

A automação que verifica apenas curl --fail não perceberia essa falha. Verifique o status do transporte e os dados de conclusão do MQ:

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

O comando sai deliberadamente de um valor diferente de zero.

Outras falhas, como URLs malformadas, JSON inválido, falhas de autenticação ou recursos ausentes em terminais REST dedicados, podem produzir respostas HTTP 4xx ou 5xx com uma mensagem MQWB. Preserve o corpo da resposta ao diagnosticá-los.

18. Construa um auxiliar MQSC REST reutilizável

Opções repetidas de curl facilitam os erros. Crie 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

Crie uma carga de exibição:

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

Execute o auxiliar:

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

O auxiliar verifica o sucesso do HTTP e do MQ separadamente. Uma versão de produção também deve:

• Renovar uma sessão expirada
• Validar o certificado do servidor
• Evite registrar segredos e valores de cookies
• Aplicar tempos limite de solicitação
• Tente novamente apenas operações que possam ser repetidas com segurança
• Emitir informações de auditoria estruturadas
• Distinguir avisos de falhas quando um comando pode retornar

19. Exclua a fila do laboratório

A fila ainda contém uma mensagem. Uma exclusão normal deverá falhar, a menos que a fila seja esvaziada ou a exclusão a limpe explicitamente. Receba a mensagem 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
'

Exclua a fila vazia:

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

Não torne PURGE o comportamento padrão de uma ferramenta de limpeza de produção. As mensagens em uma fila inesperada são evidências e possivelmente dados comerciais.

20. Sair

Invalide ambas as sessões 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
'

Remova os arquivos de cookies locais:

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

O logout explícito reduz o tempo de vida de uma sessão que não é mais necessária. Isso não elimina a necessidade de proteger o cookie enquanto ele estiver ativo.

21. Considerações sobre design de produção

22. Solução de problemas

O contêiner MQ é encerrado durante a inicialização

Inspecione o diagnóstico completo de inicialização:

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

Confirme se ambos os arquivos secretos existem, contêm senhas de pelo menos oito caracteres e podem ser lidos pelo Docker Compose.

A porta 9443 já está alocada

Outro laboratório ainda pode estar em execução:

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

Pare o outro projeto ou altere o mapeamento do lado do host, por exemplo "9444:9443". Os contêineres deste laboratório continuam usando https://mq:9443`; apenas solicitações do host usam a porta alterada.

Login retorna 401

Verificar:

• A senha em secrets/mqAdminPassword
• Que o gerenciador de filas foi criado após o fornecimento do segredo atual
• O nome de usuário exato em minúsculas admin
• Se um arquivo cookie antigo está confundindo o teste

Ao alterar as credenciais iniciais, remova o volume descartável e recrie o gerenciador de filas.

Uma solicitação de modificação foi rejeitada

Certifique-se de que a solicitação inclua:

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

Confirme também se o cookie da sessão está presente e não expirou.

curl relata um erro de certificado

Isso é esperado se você remover --insecure ao usar o certificado gerado pela imagem do desenvolvedor. A correção de produção correta é confiar na CA emissora e usar um certificado cujo assunto corresponda ao nome do host, e não restaurar --insecure.

HTTP 200 contém uma falha no MQ

Isso é esperado para uma ação do MQSC que o mqweb enviou com êxito. Inspecionar:

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

Trate os resultados HTTP e MQ como camadas separadas.

Navegar ou receber não retorna nenhuma mensagem utilizável

A API REST de mensagens pode navegar ou receber apenas formatos de texto suportados, como MQSTR e JMS TextMessage. Inspecione a lista de mensagens e considere se outro aplicativo colocou um formato binário ou específico do aplicativo.

23. O que o laboratório mostra

O laboratório estabeleceu um modelo operacional baseado em HTTP para o IBM MQ:

• mqweb autenticou um cliente remoto e emitiu um token de sessão LTPA
• A API REST administrativa expôs o status do gerenciador de filas
• O endpoint de ação do MQSC versão 3 criou, exibiu, alterou e excluiu uma fila
• A API REST de mensagens colocou, navegou e recebeu mensagens de texto de forma destrutiva
• Status da fila de ações de mensagens conectadas à observação administrativa
• O sucesso do HTTP e o sucesso do comando MQ foram validados de forma independente
• O cliente não precisava de bibliotecas do cliente MQ ou acesso ao arquivo do gerenciador de filas

As APIs REST não são um substituto universal para MQI, PCF ou MQSC. Eles são outra interface controlada, particularmente útil para ferramentas orientadas para a web, automação, portais operacionais e mensagens de texto simples.

24. Documentação IBM

• O IBM MQ Console e REST API
• Usando o REST administrativo API
• comandos MQSC formatados em JSON
• Usando o REST API de mensagens
• Colocando uma mensagem com o REST de mensagens API
• Navegando em uma lista de mensagens
• Autenticação de API REST baseada em token
• IBM MQ Console e segurança da API REST
• descoberta de API REST e Swagger UI

25. Limpeza

Pare os dois contêineres e remova o volume do gerenciador de filas:

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

Remova o projeto descartável quando ele não for mais necessário:

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