Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 2 章 与 Data Grid REST API 交互

借助 Data Grid REST API，您可以监控、维护和管理 Data Grid 部署，并提供对数据的访问。

2.1. 创建和管理缓存
复制链接

创建和管理数据网格缓存，并对数据执行操作。

2.1.1. 创建缓存
复制链接

使用 payload 中包含 XML 或 JSON 配置的 POST 请求，在 Data Grid 集群中创建命名的缓存。 

POST /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap
Expand
表 2.1. Headers
标头必需/可选参数

Content-Type

必需

为 Data Grid 配置有效负载设置 MediaType ； application/xml 或 application/json。

标记

可选

用于设置 AdminFlags

参考

2.1.1.1. XML 配置
复制链接

XML 格式的数据网格配置必须符合架构并包括：

  • <Infinispan& gt; root 元素。
  • <cache-container&gt; 定义。

XML 配置示例

<infinispan>
    <cache-container>
        <distributed-cache name="myCache" mode="SYNC">
          <encoding media-type="application/x-protostream"/>
          <memory max-count="1000000" when-full="REMOVE"/>
        </distributed-cache>
    </cache-container>
</infinispan>
Copy to Clipboard Toggle word wrap

2.1.1.2. JSON 配置
复制链接

以 JSON 格式的数据网格配置：

  • 仅要求缓存定义。

  • 必须遵循 XML 配置的结构。

    • XML 元素成为 JSON 对象。
    • XML 属性成为 JSON 字段。

JSON 配置示例

{
  "distributed-cache": {
    "name": "myCache",
    "mode": "SYNC",
    "encoding": {
      "media-type": "application/x-protostream"
      },
    "memory": {
      "max-count": 1000000,
      "when-full": "REMOVE"
    }
  }
}
Copy to Clipboard Toggle word wrap

2.1.2. 验证缓存
复制链接

检查带有 HEAD 请求的 Data Grid 集群中是否有缓存。 

HEAD /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap

2.1.3. 使用模板创建缓存
复制链接

通过 POST 请求和 ?template= 参数，从 Data Grid 模板创建缓存。 

POST /rest/v2/caches/{cacheName}?template={templateName}
Copy to Clipboard Toggle word wrap
提示

2.1.4. 检索缓存配置
复制链接

使用 GET 请求检索数据网格缓存配置。 

GET /rest/v2/caches/{name}?action=config
Copy to Clipboard Toggle word wrap
Expand
表 2.2. Headers
标头必需/可选参数

accept

可选

设置所需格式以返回内容。支持的格式为 application/xml 和 application/json。默认为 application/json。如需更多信息，请参阅 Accept。

2.1.5. 将缓存配置转换为 JSON
复制链接

使用有效的 XML 配置和 ?action=toJSON 参数调用 POST 请求。Data Grid 使用配置等效的 JSON 表示来响应。 

POST /rest/v2/caches?action=toJSON
Copy to Clipboard Toggle word wrap

2.1.6. 检索所有缓存详情
复制链接

调用 GET 请求，以重新检查数据网格缓存的所有详细信息。 

GET /rest/v2/caches/{name}
Copy to Clipboard Toggle word wrap

Data Grid 提供 JSON 响应，如下所示： 

{
  "stats": {
    "time_since_start": -1,
    "time_since_reset": -1,
    "hits": -1,
    "current_number_of_entries": -1,
    "current_number_of_entries_in_memory": -1,
    "total_number_of_entries": -1,
    "stores": -1,
    "off_heap_memory_used": -1,
    "data_memory_used": -1,
    "retrievals": -1,
    "misses": -1,
    "remove_hits": -1,
    "remove_misses": -1,
    "evictions": -1,
    "average_read_time": -1,
    "average_read_time_nanos": -1,
    "average_write_time": -1,
    "average_write_time_nanos": -1,
    "average_remove_time": -1,
    "average_remove_time_nanos": -1,
    "required_minimum_number_of_nodes": -1
  },
  "size": 0,
  "configuration": {
    "distributed-cache": {
      "mode": "SYNC",
      "transaction": {
        "stop-timeout": 0,
        "mode": "NONE"
      }
    }
  },
  "rehash_in_progress": false,
  "bounded": false,
  "indexed": false,
  "persistent": false,
  "transactional": false,
  "secured": false,
  "has_remote_backup": false,
  "indexing_in_progress": false,
  "statistics": false
}
Copy to Clipboard Toggle word wrap
  • 统计 缓存的当前统计信息。
  • 缓存估计大小。
  • 配置 缓存配置。
  • 当重新哈希正在进行时，rehash_in_progress true。
  • indexing_in_progress true （索引正在进行时）。
  • 启用过期时 绑定。
  • 如果缓存被索引，则 索引为 true。
  • 如果缓存持久，则为 persistent true。
  • 如果缓存 事务，则事务处理为 true。
  • 如果缓存被保护，则 安全 true。
  • 如果缓存有远程备份，则 has_remote_backup true。

2.1.7. 添加条目
复制链接

使用 POST 请求向缓存添加条目。 

POST /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

前面的请求使用 cacheKey 键将有效负载或请求正文放在 cacheName 缓存中。请求会替换已经存在的任何数据，并在应用 Time-To-Live 和 Last-Modified 值时更新它们。

如果指定键已存在值，则 POST 请求会返回 HTTP CONFLICT 状态，且不会修改值。要更新值，您应该使用 PUT 请求。请参阅 替换条目。

Expand
表 2.3. Headers
标头必需/可选参数

Key-Content-Type

可选

为请求中的键设置内容类型。如需更多信息，请参阅 Key-Content-Type。

Content-Type

可选

为键值设置 MediaType。

timeToLiveSeconds

可选

设置条目自动删除前的秒数。如果没有设置此参数，Data Grid 将使用配置中的默认值。如果您设置了负值，则该条目永远不会被删除。

maxIdleTimeSeconds

可选

设置条目可以闲置的秒数。如果在最大闲置时间过后没有对条目发生读取或写入操作，该条目将会被自动删除。如果没有设置此参数，Data Grid 将使用配置中的默认值。如果您设置了负值，则该条目永远不会被删除。

标记

可选

用于添加条目的标记。如需更多信息，请参阅 标记。

注意

标志 标头也适用于涉及缓存数据操作的所有其他操作，

注意

如果 timeToLiveSeconds 和 maxIdleTimeSeconds 的值为 0，则 Data Grid 将使用配置中的默认 lifespan 和 maxIdle 值。

如果 只有 maxIdleTimeSeconds 的值为 0， 则数据网格会使用：

  • 配置中的默认 maxIdle 值。
  • 如果没有传递值，则 timeToLiveSeconds 的值作为请求参数或值 -1。

如果 只有 timeToLiveSeconds 的值为 0， 则数据网格会使用：

  • 配置中的 默认 lifespan 值。
  • 如果没有传递值，则作为请求参数或值 -1 的 maxIdle 值。

2.1.8. 替换条目
复制链接

将缓存中的条目替换为 PUT 请求。 

PUT /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

如果指定键已存在值，PUT 请求会更新该值。如果您不想修改现有值，请使用返回 HTTP CONFLICT 状态的 POST 请求，而不是修改值。请参阅 添加值。

2.1.9. 通过密钥检索数据
复制链接

使用 GET 请求检索特定密钥的数据。 

GET /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

服务器在给定密钥 cacheKey 下返回来自给定缓存 cacheName 的数据，在响应正文中返回数据。响应包含与 MediaType 协商对应的 Content-Type 标头。

注意

浏览器也可以直接访问缓存，如内容交付网络(CDN)。Data Grid 为每个条目返回一个唯一的 ETag，以及 Last-Modified 和 Expires 标头字段。

这些字段提供有关您的请求中返回数据状态的信息。eTags 允许浏览器和其他客户端仅请求更改的数据，从而节省带宽。

Expand
表 2.4. Headers
标头必需/可选参数

Key-Content-Type

可选

为请求中的键设置内容类型。默认为 application/x-java-object; type=java.lang.String。如需更多信息，请参阅 Key-Content-Type。

accept

可选

设置所需格式以返回内容。如需更多信息，请参阅 Accept。

提示

在查询字符串中附加 extended 参数来获取更多信息： 

GET /rest/v2/caches/{cacheName}/{cacheKey}?extended
Copy to Clipboard Toggle word wrap

前面的请求返回自定义标头：

  • cluster-Primary-Owner 返回密钥的主所有者的节点名称。
  • cluster-Node-Name 返回处理请求的服务器的 JGroups 节点名称。
  • cluster-Physical-Address 返回处理请求的服务器的物理 JGroups 地址。

2.1.10. 检查 Entries Exist
复制链接

验证 HEAD 请求是否存在特定的条目。 

HEAD /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

前面的请求只返回标头字段，以及您与该条目存储相同的内容。例如，如果您存储了 String，请求会返回一个 String。如果您存储了二进制、base64 编码的、blob 或序列化 Java 对象，则 Data Grid 不会序列化请求中的内容。

注意

HEAD 请求也支持 扩展 参数。

Expand
表 2.5. Headers
标头必需/可选参数

Key-Content-Type

可选

为请求中的键设置内容类型。默认为 application/x-java-object; type=java.lang.String。如需更多信息，请参阅 Key-Content-Type。

2.1.11. 删除条目
复制链接

使用 DELETE 请求从缓存中删除条目。 

DELETE /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap
Expand
表 2.6. Headers
标头必需/可选参数

Key-Content-Type

可选

为请求中的键设置内容类型。默认为 application/x-java-object; type=java.lang.String。如需更多信息，请参阅 Key-Content-Type。

2.1.12. 删除缓存
复制链接

使用 DELETE 请求从 Data Grid 集群中删除缓存。 

DELETE /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap

2.1.13. 从缓存检索所有密钥
复制链接

调用 GET 请求，以检索 JSON 格式的缓存中的所有密钥。 

GET /rest/v2/caches/{cacheName}?action=keys
Copy to Clipboard Toggle word wrap
Expand
表 2.7. 请求参数
参数必需/可选值

batch-size

可选

在检索密钥时指定内部批处理大小。默认值为 1000。

2.1.14. 清除缓存
复制链接

要从缓存中删除所有数据，请使用 ?action=clear 参数调用 POST 请求。 

POST /rest/v2/caches/{cacheName}?action=clear
Copy to Clipboard Toggle word wrap

2.1.15. 获取缓存大小
复制链接

使用 GET 请求和 ?action=size 参数在整个集群中检索缓存的大小。 

GET /rest/v2/caches/{cacheName}?action=size
Copy to Clipboard Toggle word wrap

2.1.16. 获取缓存统计
复制链接

获取使用 GET 请求缓存的运行时统计信息。 

GET /rest/v2/caches/{cacheName}?action=stats
Copy to Clipboard Toggle word wrap

2.1.17. 查询缓存
复制链接

对带有 GET 请求和 ?action=search&query 参数的缓存执行 Ickle 查询。 

GET /rest/v2/caches/{cacheName}?action=search&query={ickle query}
Copy to Clipboard Toggle word wrap

Data Grid 使用查询点击进行响应，如下所示： 

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 12
    }
  } ]
}
Copy to Clipboard Toggle word wrap
  • total_results 显示查询的结果总数。
  • hits 是来自查询的数组。

  • hit 是与查询匹配的对象。

    提示

    如果使用 Select 子句，则 hits 可以包含所有字段或字段子集。

Expand
表 2.8. 请求参数
参数必需/可选值

query

必需

指定查询字符串。

max_results

可选

设置要返回的结果数。默认值为 10。

offset

可选

指定要返回的第一个结果的索引。默认值为 0。

query_mode

可选

指定 Data Grid 服务器如何执行查询。值是 FETCH 和 BROADCAST。默认值为 FETCH。

要使用请求的正文而不是指定查询参数，请按如下所示调用 POST 请求： 

POST /rest/v2/caches/{cacheName}?action=search
Copy to Clipboard Toggle word wrap

以下示例显示了请求正文中的查询： 

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}
Copy to Clipboard Toggle word wrap

2.1.18. 重新索引数据
复制链接

使用 POST 请求和 ?action=mass-index&mode={mode} 参数重新索引缓存中的所有数据。 

POST  /v2/caches/{cacheName}/search/indexes?action=mass-index&mode={mode}
Copy to Clipboard Toggle word wrap

mode 参数的值如下：

  • 只有重新索引操作完成后，sync 才会返回 200 响应。
  • async 立即返回 200 的响应，重新索引操作继续在集群中运行。您可以使用 Index Statistics REST 调用来检查状态。

2.1.19. 清除索引
复制链接

使用 POST 请求和 ?action=clear 参数从缓存中删除所有索引。 

POST  /v2/caches/{cacheName}/search/indexes?action=clear
Copy to Clipboard Toggle word wrap

2.1.20. 检索索引统计
复制链接

使用 GET 请求，获取缓存中的索引信息。 

GET /v2/caches/{cacheName}/search/indexes/stats
Copy to Clipboard Toggle word wrap

Data Grid 提供 JSON 响应，如下所示： 

{
    "indexed_class_names": ["org.infinispan.sample.User"],
    "indexed_entities_count": {
        "org.infinispan.sample.User": 4
    },
    "index_sizes": {
        "cacheName_protobuf": 14551
    },
    "reindexing": false
}
Copy to Clipboard Toggle word wrap
  • indexed_class_names 提供缓存中存在的索引的类名称。对于 Protobuf，该值始终为 org.infinispan.query.remote.impl.indexing.ProtobufValueWrapper。
  • indexed_entities_count 提供每个类索引的实体数。
  • index_sizes 为缓存中的每个索引提供大小（以字节为单位）。
  • 重新索引 指示是否为缓存执行重新索引操作。如果值为 true，则缓存中 启动 MasssIndexer。

2.1.21. 检索查询统计
复制链接

使用 GET 请求，获取有关在缓存中运行的查询的信息。 

GET /v2/caches/{cacheName}/search/query/stats
Copy to Clipboard Toggle word wrap

Data Grid 提供 JSON 响应，如下所示： 

{
    "search_query_execution_count":20,
    "search_query_total_time":5,
    "search_query_execution_max_time":154,
    "search_query_execution_avg_time":2,
    "object_loading_total_time":1,
    "object_loading_execution_max_time":1,
    "object_loading_execution_avg_time":1,
    "objects_loaded_count":20,
    "search_query_execution_max_time_query_string": "FROM entity"
}
Copy to Clipboard Toggle word wrap
  • search_query_execution_count 提供已运行的查询数量。
  • search_query_total_time 提供查询所花费的总时间。
  • search_query_execution_max_time 提供查询所花费的最长时间。
  • search_query_execution_avg_time 提供平均查询时间。
  • object_loading_total_time 提供查询执行后从缓存加载对象的总时间。
  • object_loading_execution_max_time 提供加载对象执行的最大时间。
  • object_loading_execution_avg_time 提供载入对象执行的平均时间。
  • objects_loaded_count 提供载入的对象计数。
  • search_query_execution_max_time_query_string 提供执行较慢的查询。

2.1.22. 清除 Query Statistics
复制链接

通过 POST 请求和 ?action=clear 参数重置运行时统计信息。 

POST /v2/caches/{cacheName}/search/query/stats?action=clear
Copy to Clipboard Toggle word wrap

2.1.23. 列出缓存
复制链接

列出具有 GET 请求的 Data Grid 集群中的所有可用缓存。 

GET /rest/v2/caches/
Copy to Clipboard Toggle word wrap

2.1.24. 带有缓存的跨站点操作
复制链接

使用 Data Grid REST API 执行跨站点复制操作。

2.1.24.1. 获取所有备份位置的状态
复制链接

使用 GET 请求检索所有备份位置的状态。 

GET /v2/caches/{cacheName}/x-site/backups/
Copy to Clipboard Toggle word wrap

Data Grid 以 JSON 格式为每个备份位置的状态响应，如下例所示： 

{
  "NYC": "online",
  "LON": "offline"
}
Copy to Clipboard Toggle word wrap
Expand
表 2.9. 返回的状态
值描述

online

本地集群中的所有节点都有一个带有备份位置的跨站点视图。

离线

本地集群中没有带有备份位置的跨站点视图。

mixed

本地集群中的某些节点具有带有备份位置的跨站点视图，本地集群中的其他节点没有跨站点视图。响应表示每个节点的状态。

2.1.24.2. 获取特定备份位置的状态
复制链接

使用 GET 请求检索备份位置的状态。 

GET /v2/caches/{cacheName}/x-site/backups/{siteName}
Copy to Clipboard Toggle word wrap

Data Grid 以 JSON 格式通过站点中的每个节点状态进行响应，如下例所示： 

{
  "NodeA":"offline",
  "NodeB":"online"
}
Copy to Clipboard Toggle word wrap
Expand
表 2.10. 返回的状态
值描述

online

节点在线。

离线

节点离线。

失败

无法检索状态。远程缓存可以在请求期间关闭或发生网络错误。

2.1.24.3. 执行备份位置离线
复制链接

通过 POST 请求和 ?action=take-offline 参数使备份位置离线。 

POST /v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline
Copy to Clipboard Toggle word wrap

2.1.24.4. 使备份位置在线
复制链接

使用 ?action=bring-online 参数在线启动备份位置。 

POST /v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online
Copy to Clipboard Toggle word wrap

2.1.24.5. 将状态推送到备份位置
复制链接

使用 ?action=start-push-state 参数将缓存状态推送到备份位置。 

POST /v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state
Copy to Clipboard Toggle word wrap

2.1.24.6. 取消状态传输
复制链接

使用 ?action=cancel-push-state 参数取消状态传输操作。 

POST /v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state
Copy to Clipboard Toggle word wrap

2.1.24.7. 获取状态传输状态
复制链接

使用 ?action=push-state-status 参数检索状态传输操作的状态。 

GET /v2/caches/{cacheName}/x-site/backups?action=push-state-status
Copy to Clipboard Toggle word wrap

Data Grid 以 JSON 格式为每个备份位置的状态进行响应，如下例所示： 

{
   "NYC":"CANCELED",
   "LON":"OK"
}
Copy to Clipboard Toggle word wrap
Expand
表 2.11. 返回的状态
值描述

发送

状态传输到备份位置正在进行。

确定

状态传输成功完成。

ERROR

出现错误，状态为 transfer。检查日志文件。

取消

状态转移取消正在进行。

2.1.24.8. 清除状态传输状态
复制链接

使用 ?action=clear-push-state-status 参数发送站点的清除状态传输状态。 

POST /v2/caches/{cacheName}/x-site/local?action=clear-push-state-status
Copy to Clipboard Toggle word wrap

2.1.24.9. 修改获取离线条件
复制链接

如果满足某些条件，站点将处于离线状态。修改离线参数，以控制备份位置自动离线的时间。

流程

  1. 检查配置了 GET 请求和 take-offline-config 参数的离线参数。 

    GET /v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config
    Copy to Clipboard Toggle word wrap

    Data Grid 响应包括 after_failures 和 min_wait 字段，如下所示： 

    {
  "after_failures": 2,
  "min_wait": 1000
}
    Copy to Clipboard Toggle word wrap

  2. 修改 取 PUT 请求正文中的离线参数。 

    PUT /v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config
    Copy to Clipboard Toggle word wrap

2.1.24.10. 从接收站点取消状态传输
复制链接

如果两个备份位置之间的连接中断，您可以在接收推送的站点上取消状态传输。

从远程站点取消状态传输，并使用 ?action=cancel-receive-state 参数保留本地缓存的当前状态。 

POST /v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-receive-state
Copy to Clipboard Toggle word wrap

2.1.25. 滚动升级
复制链接

在 Data Grid 集群间执行缓存数据的滚动升级

2.1.25.1. 同步数据
复制链接

使用 POST 请求和 ?action=sync-data 参数将源集群的数据同步到目标集群： 

POST /v2/caches/{cacheName}?action=sync-data
Copy to Clipboard Toggle word wrap

当操作完成后，Data Grid 使用复制到目标集群的条目总数进行响应。

2.1.25.2. 断开源集群
复制链接

将数据同步到目标集群后，使用 POST 请求和 ?action=disconnect-source 参数断开与源集群的连接： 

POST /v2/caches/{cacheName}?action=disconnect-source
Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部