GET
Use the HTTP GET method with the channel resource to request information about channels.
Note: This resource URL is available only in version 1 of the REST API. To query channels using version 2 of the REST API, use the /admin/action/qmgr/{qmgrName}/mqsc resource.The information that is returned is similar to the information returned by the Inquire Channel and Inquire Channel Status PCF commands, and the DISPLAY CHANNEL and DISPLAY CHSTATUS MQSC commands.
Note: On z/OS, the channel initiator must be running before we use the channel resource with the HTTP GET method specifying the status parameter. Note: The REST API supports only the following channels:- Channels that have a transport type of TCP.
- Sender, receiver, server, requester, cluster-sender, and cluster-receiver channels.
Other channels are not returned.
- Resource URL
- Optional query parameters
- Request headers
- Request body format
- Security requirements
- Response status codes
- Response headers
- Response body format
- Examples
Resource URL
https://host:port/ibmmq/rest/v1/admin/qmgr/{qmgrName}/channel/{channelName}
- qmgrName
- Specifies the name of the queue manager on which to query the channels.
- channelName
- Optionally specifies the name of a channel to query. This channel must exist on the specified queue manager.
We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.
Optional query parameters
- attributes={object,...|*|object.attributeName,...}
-
- object,...
- Specifies a comma-separated list of JSON objects that contain related channel configuration attributes to return.
- *
- Specifies all attributes.
- object.attributeName,...
- Specifies a comma-separated list of channel configuration attributes to return.
- status={*|currentStatus|savedStatus|currentStatus.attributeName,savedStatus.attributeName,...}
-
- *
- Specifies that all savedStatus and currentStatus attributes are returned.
- currentStatus
- Specifies that all currentStatus attributes are returned.
- savedStatus
- Specifies that all savedStatus attributes are returned.
- currentStatus.attributeName,savedStatus.attributeName,...
- Specifies a comma-separated list of current status and saved status attributes to return.
- filter=filterValue
- Specifies a filter for the channel definitions that are returned.
- name=name
- This query parameter cannot be used if we specify a channel name in the resource URL.
- type=type
- Specifies the type of channel to return information about.
- queueSharingGroupDisposition=disposition
- This parameter is only available on z/OS.
Request headers
The following headers must be sent with the request:
- Authorization
- This header must be sent if we are using basic authentication. For more information, see Use HTTP basic authentication with the REST API.
The following headers can optionally be sent with the request:
- ibm-mq-rest-gateway-qmgr
- This header specifies the queue manager that is to be used as the gateway queue manager. The gateway queue manager is used to connect to a remote queue manager. For more information, see Remote administration using the REST API.
Request body format
None.
Security requirements
The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.
If token based security is used, the LTPA token that is used to authenticate the user must be provided with the request as a cookie. For more information about token-based authentication, see Use token-based authentication with the REST API.
The security principal of the caller must be granted the ability to issue the following PCF commands for the specified queue manager:- If the status query parameter is not specified:
- For the channel that is specified by the {channelName} portion of the resource URL, or for channels that match the specified query parameters, authority to issue the MQCMD_INQUIRE_CHANNEL PCF command must be granted.
- If the status query parameter is specified:
- For the channel that is specified by the {channelName} portion of the resource URL, or for channels that match the specified query parameters, authority to issue the MQCMD_INQUIRE_CHANNEL PCF command must be granted.
- For the channel that is specified by the {channelName} portion of the resource URL, or for channels that match the specified query parameters, authority to issue the MQCMD_INQUIRE_CHSTATUS PCF command must be granted.
A principal has display authority if the principal can issue one or both of the MQCMD_INQUIRE_CHANNEL and MQCMD_INQUIRE_CHSTATUS PCF commands. If the principal has display authority for only some of the channels that are specified by the resource URL and query parameters, then the array of channels that is returned from the REST request is limited to those channels that the principal has authority to display. No information is returned about channels that cannot be displayed. If the principal does not have display authority for any of the channels that are specified by the resource URL and query parameters, an HTTP status code of 403 is returned.
On Multiplatforms, if the attribute currentStatus.monitoring.messagesAvailable is to be returned, authority to issue the MQCMD_INQUIRE_Q on the transmission queues used by cluster sender channels is required.
On UNIX, Linux, and Windows, we can
grant authority to security principals to use IBM MQ resources by using the setmqaut command. For more information, see setmqaut (grant or
revoke authority).
On z/OS, see Set up security on z/OS.
Response status codes
- 200
- Channel information retrieved successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Channel does not exist.
- 500
- Server issue or error code from IBM MQ.
- 503
- Queue manager not running.
Response headers
The following headers are returned with the response:
- Content-Type
- This header is returned with a value of application/json;charset=utf-8.
- ibm-mq-rest-gateway-qmgr
- This header is returned if a remote queue manager is specified in the resource URL. The value of this header is the name of the queue manager that is used as the gateway queue manager.
Response body format
The response is in JSON format in UTF-8 encoding. The response contains an outer JSON object that contains a single JSON array called channel. Each element in the array is a JSON object that represents information about a channel. Each of these JSON objects contains the following attributes:
- name
- String.
- type
- String.
The following objects can be included in the JSON object that represents information about a channel. Which objects and attributes are returned depends on the URL that was specified for the request:
- sender
- Contains attributes that are related to sender channels.
- server
- Contains attributes that are related to server channels.
- requester
- Contains attributes that are related to requester channels.
- clusterSender
- Contains attributes that are related to cluster sender channels.
- clusterReceiver
- Contains attributes that are related to cluster receiver channels.
- clusterRouting
- Contains attributes that are related to the routing of messages in a cluster.
- connectionManagement
- Contains attributes that are related to connection management including:
- A JSON array of connection objects that are labeled connectionManagement, which contain host and port information
- longRetry and shortRetry objects, containing count and interval attributes
- compression
- Contains attributes that are related to compression
- dataCollection
- Contains attributes that are related to monitoring and statistics
- exits
- Contains exit objects and arrays of exit objects, each containing:
- Exit name attribute
- User data attribute
- extended
- Contains attributes that are related to extended channel properties, such as data conversion, and sequence numbers.
- failedDelivery
- Contains attributes that are related to message delivery failure, such as retry options.
- general
- Contains attributes that are related to general channel properties, such as the description of the channel.
- batch
- Contains attributes that are related to message batches.
- queueSharingGroup
- Contains attributes that are related to queue sharing groups on z/OS.
- receiverSecurity
- Contains attributes that are related to security for receiving channels.
- transmissionSecurity
- Contains attributes that are related to transmission security and encryption.
For more information, see Response body attributes for channels.
If a damaged object is found, and the REST request did not specify a channel name within the resource URL, an extra JSON array that is called damaged is returned. This JSON array contains a list of the objects that are damaged, specifying the object names. If the REST request specifies a channel name within the resource URL, but the object is damaged, an error is returned.
If an error occurs, the response body contains an error message. For more information, see REST API error handling.
Examples
- The following example lists all channels on the queue manager QM1.
The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/channel
The following JSON response is returned:{ "channel": [{ "name": "RECEIVER.CHL", "type": "receiver" }, { "name": "SENDER.CHL", "type": "sender", "sender": { "connection": [{ "host":"example.com", "port": "1414" }], "transmissionQueueName": "XMIT.Q" } }, { "name": "SERVER.CHL", "type": "server", "server": { "transmissionQueueName": "XMIT.Q" } }, { "name": "REQUESTER.CHL", "type": "requester", "requester": { "connection": [{ "host": "example.com", "port": 1414 }] } }, { "name": "CLUSSDR.CHL", "type": "clusterSender", "clusterSender": { "connection": [{ "host": "example.com", "port": 1414 }], "clusterName": "CUSTER1" } }, { "name": "CLUSRCVR.CHL", "type": "clusterReceiver", "clusterReceiver": { "connection": [{ "host": "example.com", "port": 1414 }], "clusterName": "CUSTER1" } }] } - The following example lists all receiver channels on the queue manager QM1, showing
their connection retry attempts information. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QMGR2/channel?type=sender&attributes=connectionManagement.shortRetry,connectionManagement.longRetry
The following JSON response is returned:{ "channel": [{ "name": "SENDER.CHL", "type": "sender", "connectionManagement": { "longRetry": { "count": 999999999, "interval": 1200 }, "shortRetry": { "count": 10, "interval": 60 } }, "sender": { "connection": [{ "host": "example.com", "port": 1414 }], "transmissionQueueName": "XMIT.Q" }, { "name": "SYSTEM.DEF.SENDER", "type": "sender", "connectionManagement": { "longRetry": { "count": 999999999, "interval": 1200 }, "shortRetry": { "count": 10, "interval": 60 } }, "sender": { "connection": [], "transmissionQueueName": "" }] } - The following example lists some status attributes for the channel CHL1, on channel
manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/channel/CHL1?status=currentStatus.timestamps,currentStatus.batch.currentMessages,savedStatus.batch.currentMessages
The following JSON response is returned:{ "channel": [{ "name": "CHL1", "type": "sender", "currentStatus": [{ "inDoubt": false, "state": "running", "batch": { "currentMessages": 10 }, "timestamps": { "lastMessage": "2017-10-02T09:17:42.314Z", "started": "1993-12-31T23:59:59.000Z" } }], "savedStatus": [{ "inDoubt": false, "batch": { "currentMessages": 5 } }, { "inDoubt": false, "batch": { "currentMessages": 7 } }] }] } -
The following example shows how to get all information, including current status and saved status, for the channel CHL2 on queue manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/channel/CHL2?attributes=*&status=*
-
The following example shows how to get all channel configuration and status information for channels that are currently running, for the queue manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/channel?attributes=*&status=*&filter=currentStatus.state:equalTo:running
- Response body attributes for channels
When you receive the response body from using the HTTP verb GET with the channel object to request information about channels, attributes for the channels are returned within named JSON objects.
Parent topic: /admin/qmgr/{qmgrName}/channel