工作方式：CMCI GraphQL API

CICS® 管理客户端接口（CMCI）为系统管理客户端提供了 GraphQL 应用编程接口（API），例如 IBM® CICS Explorer®.CMCI GraphQL API 通过 HTTP 支持。借助 GraphQL ，客户只需一次请求即可查询CICSplexes或区域中的多种 CICS 资源。在单个查询请求中，客户可以准确指定其所需的多个 CICS的数据，并明确表达 CICS固有关系。有关 GraphQL, 的更多信息，请参阅 GraphQL 简介。

注：

CICS Explorer 中的聚集功能也受 CICS TS 中的 CMCI GraphQL API 支持。有关更多信息，请参阅配置 CICS Explorer。
从 CICS TS 5.5, and in a single CICS region (SMSS) as of CICS TS 5.6 with APAR PH35122 开始，在 CICSPlex® SM 环境中支持 CMCI GraphQL API。
要在 CICS 中设置 CMCI GraphQL API，您需要在 CICSplex 的 WUI 区域或单个 CICS 区域内配置 CMCI JVM 服务器。有关说明，请参阅设置 CMCI。

什么是 GraphQL 查询?

简单的 GraphQL 查询请求如下所示:

图 1。请求 CICSplex 名称的简单查询

{
  cicsplexes {
    name
  }
}

查询的根目录是 cicsplexes 字段，用于查找 WUI 服务器连接到的所有 CICSplex。嵌套在 cicsplexes 字段中的 name 字段请求每个 CICSplex 的名称。

查询响应作为 JSON 对象返回，请求的数据包含在 data 字段的值中。响应的结构遵循查询中的结构。

图 2。对有关 CICSplex 名称的简单查询的响应

{
  "data": {
    "cicsplexes": [
      {
        "name": "CICSPLX01"
      },
      {
        "name": "CICSPLX02"
      }
    ]
  }
}

在 SMSS 区域中，GraphQL 查询的结构与此不同，看起来像这样：

图 3。请求 SMSS 区域名称的简单查询

{
  smssRegion {
    name  
  }
}

响应的结构类似于 CICSplex ，如下所示:

图 4：对有关 SMSS 地区名称的简单查询的答复

{
  "data": {
    "smssRegion": {
      "name": "IYCWENSS"
    }
  }
}

在 CICS TS 中， GraphQL API 支持:

基本系统拓扑 (CICSplex ，区域和系统组)
查询区域以获取其中安装的资源
查询 BAS 存储库和 CSD 存储库以获取定义
聚集和分组资源
浏览资源之间的链接

要检索更多信息，请向查询添加更多字段，包括嵌套字段。请参阅样本查询。

如何发出 GraphQL API 请求

GraphQL API 端点位于:

https://host:port/graphql

其中 host 和 port 是 CMCI JVM 服务器的主机名和端口号。

GraphQL API 接受 GET 和 POST 请求。

对于 GET 请求:

必须发送 Content-Type: application/json 头。查询由 query 查询参数提供。此操作由可选的 operationName 查询参数提供。

例如，图1中的简单查询可以通过URL 发送：

https://host:port/graphql?query={cicsplexes{name}}

同样，对于图3中的简单查询，GET请求与此类似，可通过URL 发送：

https://host:port/graphql?query={smssRegion{name}}

对于 POST 请求:

必须发送 Content-Type: application/json 头。请求主体必须是 JSON 编码的对象。

{
    "query": "query_body",
    "operationName": "operation_name"
}

其中，只有 query 字段是必填字段。

或者，可以在 POST 请求上发送 Content-Type: application/graphql 头。在这种情况下，请求的主体必须是 GraphQL 查询本身，并且不能指定操作名称。

请参阅样本查询以获取 GraphQL 查询的样本代码。

示例: CICS Explorer 的 CICSplex Explorer 视图

GraphQL API 可以在用户界面 (例如 CICS Explorer) 中提供更灵敏的体验。以 CICS Explorer 的 CICSplex Explorer 视图为例，请考虑 CICS Explorer 中需要哪些信息来构建 CICSplex Explorer 视图:

最基本的是，您需要知道环境中有哪些 CICSplex ，以及这些 CICSplex 中有哪些 CICS 区域。通过 REST API ，您必须发出多个请求:

询问环境中 CICSplex 的列表。
对于每个 CICSplex ，请求获取该 CICSplex 中区域的列表。

即使是这个简单的示例也表明，您必须发出的请求数量会随着您所要求的信息的复杂性而增加。当您考虑向混合中添加区域组以及这些区域组的成员时，甚至需要请求更多信息。

以下是如何在 GraphQL API 中请求填充 CICSplex Explorer 视图所需的信息:

{
  cicsplexes {
    name
    regions {
      name
    }
  }
}

以下是响应:

{
  "data": {
    "cicsplexes": [
      {
        "name": "DUMMY907",
        "regions": []
      },
      {
        "name": "CICSEXCD",
        "regions": [
          {
            "name": "IYCWEZW2"
          },
          {
            "name": "IYCWEZG1"
          },
          {
            "name": "IYCWEZW1"
          },
          {
            "name": "IYCWEZH1"
          },
          {
            "name": "IYCWEZI1"
          },
          {
            "name": "IYCWEZJ1"
          },
          {
            "name": "IYCWEZZ1"
          }
        ]
      }
    ]
  }
}

GraphQL在单个请求中提供您所需的所有数据，并明确显示CICS资源之间的关系。启用 CMCI 连接后，可大大缩短通过CICS Explorer检索信息所需的时间。它还支持CICS Explorer的聚合功能，以提供CICS资源的聚合和分组。

样本查询

您可以使用 GraphiQL, 在线 GraphQL 可视化编辑器来测试您的 GraphQL 查询或示例。 GraphiQL URL ：

https://host:port/graphiql

其中 host 和 port 是 CMCI JVM 服务器的主机名和端口号。

GraphiQL 提示:

GraphiQL 为 GraphQL 模式引用提供了自动完成和内置文档资源管理器。可以通过按 Ctrl + Space 来显示可用字段名称。
要在 GraphiQL 历史记录中轻松区分查询，您可以通过使用 query QueryName作为查询的前缀来指定唯一查询名称。

以下示例查询所有已连接 CICSplex 中所有区域的本地文件计数以及每个 CICSplex 和区域的名称。它还具有查询名称 LocalFilesInRegionsInCICSplexes。

query LocalFilesInRegionsInCICSplexes {
  cicsplexes {
    name
    regions {
      name
      cicsResources {
        locfile {
          count
        }
      }
    }
  }
}

您可以添加更多要查询的属性。此示例查询每个 CICSplex 中的所有 CICSplex 和所有区域。在每个区域中，它检索所有本地事务的 name， useCount和 status 字段。

{
  cicsplexes {
    name
    regions {
      name
      cicsResources {
        loctran {
          records {
            name
            useCount
            status
          }
        }
      }
    }
  }
}

您可以指定要查询的 CICSplex 或 CICS 区域。此示例查询 CICSplex PLEX1中的区域 AORRGN ，检索该区域中所有本地事务的 name， useCount和 status 字段。

{
  cicsplex(name: "PLEX1") {
    name
    region(name: "AORRGN") {
      name
      cicsResources {
        loctran {
          records {
            name
            useCount
            status
          }
        }
      }
    }
  }
}

除去 CICSplex 和区域规范，此示例将查询所有已连接的 CICSplex 以及这些 CICSplex 中所有本地事务的 name， useCount和 status 字段。

{
  cicsplexes {
    name
    cicsResources {
      loctran {
        records {
          name
          useCount
          status
        }
      }
    }
  }
}

此示例与先前示例类似，只是它使用过滤器仅检索以 CED开头的事务。

{
  cicsplexes {
    name
    cicsResources {
      loctran(filter: {name: {value: "CED*"}}) {
        records {
          name
          useCount
          status
        }
      }
    }
  }
}

您还可以查询 CICS 定义。此请求查询 CICSplex 数据存储库中所有文件定义的名称和更新属性。

{
  cicsplex(name: "PLEX1") {
    drep {
      cicsDefinitions {
        filedef {
          records {
            name
            update
          }
        }
      }
    }
  }
}

同样，此请求会在 CSD 中查询 CICSplex PLEX1中区域 AORRGN 的所有管道定义的名称。

{
  cicsplex(name: "PLEX1") {
    region(name: "AORRGN") {
      csd {
        cicsDefinitions {
          pipedef {
            records {
              name
            }
          }
        }
      }
    }
  }
}

此查询将对每个 CICSplex 中的所有本地文件进行聚集，按名称属性的公共值对它们进行分组，并检索每个聚集组中的聚集记录计数，每个组的名称以及每个组中的平均值，最小值和最大值 readCount 。

{
  cicsplexes {
    name
    cicsResources {
      locfile {
        groupBy(attribute: "name") {
          count
          aggregateRecord {
            name {
              value
            }
            readCount {
              average
              min
              max
            }
          }
        }
      }
    }
  }
}

下面的示例可以查询当前连接到 SMSS 区域的本地事务。它检索记录并显示每个 SMSS 区域名称下的名称、优先级、状态、跟踪、可清除性和死锁超时。

{
  smssRegion {
    name
    cicsResources{
      loctran{        
       records{
          name
          priority
          profile
          status
          tracing
          purgeability
          deadlockTimeout
        }
      }
    }
  }
}