调用队列管理器 REST API

IBM MQ 提供了一组 REST API，使用这些 API 通过脚本、应用程序和程序来管理和测试队列管理器以及与队列管理器进行交互十分简单。在此部分中，将提供对 IBM 队列管理器调用 API 的需求，以及可以直接从终端运行并轻松转换为其他编程语言的示例。

IBM 队列管理器有 2 个 REST API 可供调用：

管理 REST API - 允许对队列管理器执行管理操作
消息传递 REST API - 允许应用程序发送和接收消息

与 IBM 队列管理器交互时，有几条重要信息:

URI 中不需要侦听器端口就可调用 REST API
用于调用队列管理器的主机名应该以 web- 开头
URI 中路径的开头应该为 /ibmmq/rest
REST API 区分大小写-例如，如果您的队列管理器称为 QM1，并且您使用的是管理 REST API，那么在 admin 的路径中应该执行 /qmgr/QM1/..。

认证客户机以调用 REST API 请求

有多种方法可通过 REST 向 IBM 队列管理器进行认证。

第一种方法是使用基本认证，这是用于通过 REST 与队列管理器进行交互的非常常用的方法，因为可轻松转换为其他语言，并且非常适合测试。

有关使用基本认证向队列管理器进行认证的更多信息，请参阅此处。

示例: 使用基本认证向 IBM 队列管理器进行认证

从 IBM Cloud 的服务实例中获取您的 MQ 用户名和 API 密钥，然后运行以下操作：
```
AUTH=`echo "<MQ_USERNAME>:<API_KEY>" | base64`
```
MQ_USERNAME 和 API_KEY 将取决于您要访问的 REST API:
- admin，您需要在用户许可权选项卡中添加用户，这将生成 MQ 用户名并将平台 API 密钥用于 IBM Cloud
- 消息传递，您需要在“应用程序许可权”选项卡中创建应用程序许可权，并使用 API 密钥及其为您生成的 MQ 用户名

在请求的 Authorization 头中传递 AUTH 的值：

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

第二种方法是基于令牌的认证，与队列管理器公开的登录 REST API 进行交互。此 REST API 将返回一个 cookie，可保存到脚本/应用程序中的变量中，或者保存在纯文本文件中，以供对队列管理器发出的后续请求使用。

完成通过 REST 与 IBM 队列管理器进行的交互后，还可以使用登录 REST API 来撤销访问令牌，这需要客户机在发出后续调用之前，先检索新的访问令牌。

有关如何使用基于令牌的认证来通过 REST 与队列管理器进行交互的更多信息，请参阅此处。

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

在后续调用中，将 cookiejar.txt 文件作为参数传递，以将您自己标识为已认证的用户。

管理队列管理器

管理 REST API 支持管理队列管理器，允许创建、检索、修改和删除队列。

管理 REST API 文档可以在此处找到。

示例: 在 IBM 队列管理器中创建队列

如果您已使用基于令牌的认证进行认证，请指向存储 cookie 的位置，以将您自己标识为已认证的用户。

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

然后，可以通过运行以下命令来显示创建的队列。

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

发送和接收消息

通过消息传递 REST API，可以在 IBM 队列管理器中的所需队列上发送和检索消息。

可以在此处找到消息传递 REST API 文档。

非 "DEV." 队列

如果已创建名称不以 "DEV" 开头的新队列，那么预定义的授权记录将不适用。因此，应用程序将不具有向此队列发送或接收消息所需的许可权。请查看分配对队列的用户/组访问权指南，以获取更多信息以及配置此队列所需的授权记录所需的步骤。

示例: 在 IBM 队列管理器中的队列上放置消息

如果您已使用基于令牌的认证进行认证，请指向存储 cookie 的位置，以将您自己标识为已认证的用户。

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

请注意，缺省情况下，通过消息传递 REST API 发送的任何消息都将被视为非持久消息，而不管目标队列配置的缺省持久性设置如何。要更改缺省行为，可以包含可选头 ibm-mq-md-persistence，该头必须指定为以下某个值：

持久
nonPersistent

要发送持久消息，上面的示例将采用以下格式：

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

可以在此处找到消息传递 REST API 头的完整列表