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

第 2 章 与 Data Grid REST API 交互

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

注意

默认情况下，Data Grid REST API 操作在成功时返回 200 (OK)。但是，当某些操作被成功处理时，它们会返回 HTTP 状态代码，如 204 或 202，而不是 200。

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

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

2.1.1. 创建缓存
复制链接

使用 POST 请求在有效负载中包含 XML 或 JSON 配置，在 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。

标记

OPTIONAL

用于设置 AdminFlags

2.1.1.1. 缓存配置
复制链接

您可以使用 XML、JSON 和 YAML 格式创建声明性缓存配置。

所有声明性缓存都必须符合 Data Grid 模式。JSON 格式的配置必须遵循 XML 配置的结构，元素对应于对象和属性对应于字段。

重要

Data Grid 将字符限制为缓存名称或缓存模板名称的最大 255 个。如果您超过这个字符限制，Data Grid 服务器可能会立即停止，而不会发出异常消息。编写 succinct 缓存名称和缓存模板名称。

重要

文件系统可能会对文件名的长度设置限制，因此请确保缓存的名称不会超过这个限制。如果缓存名称超过文件系统的命名限制，则常规操作或对该缓存的初始操作可能会失败。编写 succinct 缓存名称和缓存模板名称。

分布式缓存

XML

<distributed-cache owners="2"
                   segments="256"
                   capacity-factor="1.0"
                   l1-lifespan="5000"
                   mode="SYNC"
                   statistics="true">
  <encoding media-type="application/x-protostream"/>
  <locking isolation="REPEATABLE_READ"/>
  <transaction mode="FULL_XA"
               locking="OPTIMISTIC"/>
  <expiration lifespan="5000"
              max-idle="1000" />
  <memory max-count="1000000"
          when-full="REMOVE"/>
  <indexing enabled="true"
            storage="local-heap">
    <index-reader refresh-interval="1000"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</distributed-cache>
Copy to Clipboard Toggle word wrap

JSON

{
  "distributed-cache": {
    "mode": "SYNC",
    "owners": "2",
    "segments": "256",
    "capacity-factor": "1.0",
    "l1-lifespan": "5000",
    "statistics": "true",
    "encoding": {
      "media-type": "application/x-protostream"
    },
    "locking": {
      "isolation": "REPEATABLE_READ"
    },
    "transaction": {
      "mode": "FULL_XA",
      "locking": "OPTIMISTIC"
    },
    "expiration" : {
      "lifespan" : "5000",
      "max-idle" : "1000"
    },
    "memory": {
      "max-count": "1000000",
      "when-full": "REMOVE"
    },
    "indexing" : {
      "enabled" : true,
      "storage" : "local-heap",
      "index-reader" : {
        "refresh-interval" : "1000"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

YAML

distributedCache:
  mode: "SYNC"
  owners: "2"
  segments: "256"
  capacityFactor: "1.0"
  l1Lifespan: "5000"
  statistics: "true"
  encoding:
    mediaType: "application/x-protostream"
  locking:
    isolation: "REPEATABLE_READ"
  transaction:
    mode: "FULL_XA"
    locking: "OPTIMISTIC"
  expiration:
    lifespan: "5000"
    maxIdle: "1000"
  memory:
    maxCount: "1000000"
    whenFull: "REMOVE"
  indexing:
    enabled: "true"
    storage: "local-heap"
    indexReader:
      refreshInterval: "1000"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

复制缓存

XML

<replicated-cache segments="256"
                  mode="SYNC"
                  statistics="true">
  <encoding media-type="application/x-protostream"/>
  <locking isolation="REPEATABLE_READ"/>
  <transaction mode="FULL_XA"
               locking="OPTIMISTIC"/>
  <expiration lifespan="5000"
              max-idle="1000" />
  <memory max-count="1000000"
          when-full="REMOVE"/>
  <indexing enabled="true"
            storage="local-heap">
    <index-reader refresh-interval="1000"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</replicated-cache>
Copy to Clipboard Toggle word wrap

JSON

{
  "replicated-cache": {
    "mode": "SYNC",
    "segments": "256",
    "statistics": "true",
    "encoding": {
      "media-type": "application/x-protostream"
    },
    "locking": {
      "isolation": "REPEATABLE_READ"
    },
    "transaction": {
      "mode": "FULL_XA",
      "locking": "OPTIMISTIC"
    },
    "expiration" : {
      "lifespan" : "5000",
      "max-idle" : "1000"
    },
    "memory": {
      "max-count": "1000000",
      "when-full": "REMOVE"
    },
    "indexing" : {
      "enabled" : true,
      "storage" : "local-heap",
      "index-reader" : {
        "refresh-interval" : "1000"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

YAML

replicatedCache:
  mode: "SYNC"
  segments: "256"
  statistics: "true"
  encoding:
    mediaType: "application/x-protostream"
  locking:
    isolation: "REPEATABLE_READ"
  transaction:
    mode: "FULL_XA"
    locking: "OPTIMISTIC"
  expiration:
    lifespan: "5000"
    maxIdle: "1000"
  memory:
    maxCount: "1000000"
    whenFull: "REMOVE"
  indexing:
    enabled: "true"
    storage: "local-heap"
    indexReader:
      refreshInterval: "1000"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

多个缓存

XML

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:13.0 https://infinispan.org/schemas/infinispan-config-13.0.xsd
                          urn:infinispan:server:13.0 https://infinispan.org/schemas/infinispan-server-13.0.xsd"
      xmlns="urn:infinispan:config:13.0"
      xmlns:server="urn:infinispan:server:13.0">
  <cache-container name="default"
                   statistics="true">
    <distributed-cache name="mycacheone"
                       mode="ASYNC"
                       statistics="true">
      <encoding media-type="application/x-protostream"/>
      <expiration lifespan="300000"/>
      <memory max-size="400MB"
              when-full="REMOVE"/>
    </distributed-cache>
    <distributed-cache name="mycachetwo"
                       mode="SYNC"
                       statistics="true">
      <encoding media-type="application/x-protostream"/>
      <expiration lifespan="300000"/>
      <memory max-size="400MB"
              when-full="REMOVE"/>
    </distributed-cache>
  </cache-container>
</infinispan>
Copy to Clipboard Toggle word wrap

YAML

infinispan:
  cacheContainer:
    name: "default"
    statistics: "true"
    caches:
      mycacheone:
       distributedCache:
          mode: "ASYNC"
          statistics: "true"
          encoding:
            mediaType: "application/x-protostream"
          expiration:
            lifespan: "300000"
          memory:
            maxSize: "400MB"
            whenFull: "REMOVE"
      mycachetwo:
        distributedCache:
          mode: "SYNC"
          statistics: "true"
          encoding:
            mediaType: "application/x-protostream"
          expiration:
            lifespan: "300000"
          memory:
            maxSize: "400MB"
            whenFull: "REMOVE"
Copy to Clipboard Toggle word wrap

JSON

{
  "infinispan" : {
    "cache-container" : {
      "name" : "default",
      "statistics" : "true",
      "caches" : {
        "mycacheone" : {
          "distributed-cache" : {
            "mode": "ASYNC",
            "statistics": "true",
            "encoding": {
              "media-type": "application/x-protostream"
            },
            "expiration" : {
              "lifespan" : "300000"
            },
            "memory": {
              "max-size": "400MB",
              "when-full": "REMOVE"
            }
          }
        },
        "mycachetwo" : {
          "distributed-cache" : {
            "mode": "SYNC",
            "statistics": "true",
            "encoding": {
              "media-type": "application/x-protostream"
            },
            "expiration" : {
              "lifespan" : "300000"
            },
            "memory": {
              "max-size": "400MB",
              "when-full": "REMOVE"
            }
          }
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

2.1.2. 修改缓存
复制链接

通过 PUT 请求（在有效负载中包含 XML 或 JSON 配置）在 Data Grid 集群中对缓存配置进行更改。

注意

只有在更改与现有配置兼容时，才能修改缓存。

例如，您无法使用复制的缓存配置来修改分布式缓存。同样，如果您使用特定属性创建缓存配置，您无法修改配置以使用不同的属性。例如，通过为 max-count 属性指定一个值来尝试修改缓存配置，如果已经设置了 max-size，则会导致无效的配置。 

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

Content-Type

必需

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

标记

OPTIONAL

用于设置 AdminFlags

2.1.3. 验证缓存
复制链接

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

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

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

使用 POST 请求和 ?template= 参数从 Data Grid 模板创建缓存。 

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

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

使用 GET 请求检索 Data Grid 缓存配置。 

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

accept

OPTIONAL

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

2.1.6. 在 XML、JSON 和 YAML 之间转换缓存配置
复制链接

使用有效配置和 ?action=convert 参数调用 POST 请求。Data Grid 使用 Accept 标头指定的类型中的配置的等效表示来进行响应。 

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

要转换缓存配置，您必须使用 Content-Type 标头和所需的输出格式指定配置的输入格式。例如，以下命令将复制的缓存配置从 XML 转换为 YAML： 

curl localhost:11222/rest/v2/caches?action=convert \
--digest -u username:password \
-X POST -H "Accept: application/yaml" -H "Content-Type: application/xml" \
-d '<replicated-cache mode="SYNC" statistics="false"><encoding media-type="application/x-protostream"/><expiration lifespan="300000" /><memory max-size="400MB" when-full="REMOVE"/></replicated-cache>'
Copy to Clipboard Toggle word wrap

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

调用 GET 请求，以检索 Data Grid 缓存的所有详细信息。 

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,
  "rebalancing_enabled": true,
  "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。
  • 如果启用了重新平衡，则 rebalancing_enabled 为 true。获取此属性可能会在服务器中失败。在这种情况下，属性不会出现在有效负载中。
  • 在启用过期时 绑定。
  • 如果索引缓存，则 索引为 true。
  • 如果缓存 持久，则持久性为 true。
  • 如果缓存是 事务处理，则为事务处理。
  • 如果缓存 安全，则安全保护为 true。
  • 如果缓存有远程备份，则为 has_remote_backup true。
  • key_storage 缓存密钥的介质类型。
  • value_storage 缓存值的介质类型。
注意

key_storage 和 value_storage 匹配缓存的编码配置。对于没有编码的服务器缓存，Data Grid 会假定在对缓存进行索引时，Data Grid 会假定 application/x-protostream，否则 应用/未知。

2.1.8. 检索所有可变缓存配置属性
复制链接

调用 GET 请求，以检索 Data Grid 缓存的所有可变缓存配置属性。 

GET /rest/v2/caches/{name}?action=get-mutable-attributes
Copy to Clipboard Toggle word wrap

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

[
  "jmx-statistics.statistics",
  "locking.acquire-timeout",
  "transaction.single-phase-auto-commit",
  "expiration.max-idle",
  "transaction.stop-timeout",
  "clustering.remote-timeout",
  "expiration.lifespan",
  "expiration.interval",
  "memory.max-count",
  "memory.max-size"
]
Copy to Clipboard Toggle word wrap

添加 full 参数以获取值和类型信息： 

GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true
Copy to Clipboard Toggle word wrap

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

{
  "jmx-statistics.statistics": {
    "value": true,
    "type": "boolean"
  },
  "locking.acquire-timeout": {
    "value": 15000,
    "type": "long"
  },
  "transaction.single-phase-auto-commit": {
    "value": false,
    "type": "boolean"
  },
  "expiration.max-idle": {
    "value": -1,
    "type": "long"
  },
  "transaction.stop-timeout": {
    "value": 30000,
    "type": "long"
  },
  "clustering.remote-timeout": {
    "value": 17500,
    "type": "long"
  },
  "expiration.lifespan": {
    "value": -1,
    "type": "long"
  },
  "expiration.interval": {
    "value": 60000,
    "type": "long"
  },
  "memory.max-count": {
    "value": -1,
    "type": "long"
  },
  "memory.max-size": {
    "value": null,
    "type": "string"
  }
}
Copy to Clipboard Toggle word wrap

对于 enum 类型的属性，额外的 universe 属性将包含一组可能的值。

2.1.9. 更新缓存配置属性
复制链接

调用 POST 请求，以更改 mutable 缓存配置属性。 

POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}
Copy to Clipboard Toggle word wrap

2.1.10. 添加条目
复制链接

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

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

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

如果成功创建条目，服务会返回 204 (No Content)。

如果指定键的值已存在，POST 请求会返回 409 (Conflict)，且不会修改值。要更新值，您应该使用 PUT 请求。请参阅 替换条目。

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

Key-Content-Type

OPTIONAL

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

Content-Type

OPTIONAL

为键设置值的 MediaType。

timeToLiveSeconds

OPTIONAL

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

maxIdleTimeSeconds

OPTIONAL

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

标记

OPTIONAL

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

注意

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

注意

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

如果只有 maxIdleTimeSeconds 的值为 0， Data Grid 使用：

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

如果只有 timeToLiveSeconds 的值为 0， Data Grid 使用：

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

2.1.11. 替换条目
复制链接

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

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

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

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

使用 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.5. Headers
标头必需/可选参数

Key-Content-Type

OPTIONAL

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

accept

OPTIONAL

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

提示

在查询字符串中附加 扩展 参数以获取更多信息： 

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.13. 检查条目预期
复制链接

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

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

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

注意

HEAD 请求也支持 扩展 参数。

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

Key-Content-Type

OPTIONAL

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

2.1.14. 删除条目
复制链接

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

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

Key-Content-Type

OPTIONAL

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

2.1.15. 删除缓存
复制链接

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

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

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

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

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

limit

OPTIONAL

指定使用 InputStream 检索的最大密钥数。负值检索所有键。默认值为 -1。

batch

OPTIONAL

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

2.1.17. 从缓存检索所有条目
复制链接

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

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

元数据

OPTIONAL

包括响应中每个条目的元数据。默认值为 false。

limit

OPTIONAL

指定要在响应中包含的最大键数。负值检索所有键。默认值为 -1。

batch

OPTIONAL

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

content-negotiation

OPTIONAL

如果为 true，则将键和值转换为可读的格式。对于使用文本编码（如 text/plain、xml、json）的缓存，服务器会以纯文本形式返回键和值。对于带有二进制编码的缓存，服务器将在支持转换时返回条目为 JSON，否则以文本十六进制格式（如 0xA123CF98 ）返回条目。使用内容协商时，响应将包含两个标头： key-content-type 和 value-content-type，以描述协商的格式。

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

[
    {
        "key":1,
        "value":"value1",
        "timeToLiveSeconds":-1,
        "maxIdleTimeSeconds":-1,
        "created":-1,
        "lastUsed":-1,
        "expireTime":-1
    },
    {
        "key":2,
        "value":"value2",
        "timeToLiveSeconds":10,
        "maxIdleTimeSeconds":45,
        "created":1607966017944,
        "lastUsed": 1607966017944,
        "expireTime":1607966027944
    }
]
Copy to Clipboard Toggle word wrap
  • 条目的键。
  • 条目的值。
  • timeToLiveSeconds 基于条目寿命，但以秒为单位，如果条目永不过期，则为 -1。除非设置了 metadata="true"，否则它不会返回。
  • maxIdleTimeSeconds 最大空闲时间，以秒为单位，如果条目永不过期，则为 -1。除非设置了 metadata="true"，否则它不会返回。
  • 创建 条目创建时间，或为 immortal 条目创建 -1。除非设置了 metadata="true"，否则它不会返回。
  • lastUsed Last time 是在条目上执行某个操作，或 -1 代表 immortal 条目。除非设置了 metadata="true"，否则它不会返回。
  • 当条目过期或 -1 代表 immortal 条目时，expireTime 时间。除非设置了 metadata="true"，否则它不会返回。

2.1.18. 清除缓存
复制链接

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

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

如果操作成功完成，服务会返回 204 (No Content)。

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

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

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

2.1.20. 获取缓存统计信息
复制链接

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

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

2.1.21. 列出缓存
复制链接

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

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

2.1.22. 侦听缓存事件
复制链接

使用 服务器层事件接收缓存事件。事件 值将是 cache-entry-created,cache-entry-removed,cache-entry-updated,cache-entry-expired 之一。data 值将包含以 Accept 标头设置的格式触发事件的条目键。 

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

accept

OPTIONAL

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

2.1.23. 启用重新平衡
复制链接

为特定的缓存打开自动重新平衡。 

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

2.1.24. 禁用重新平衡
复制链接

关闭特定缓存的自动重新平衡。 

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

2.1.25. 获取缓存可用性
复制链接

检索缓存的可用性。 

GET /rest/v2/caches/{cacheName}?action=get-availability
Copy to Clipboard Toggle word wrap
注意

您可以获取内部缓存的可用性，但可能会在未来的 Data Grid 版本中有所变化。

2.1.26. 设置缓存可用性
复制链接

在使用 DENY_READ_WRITES 或 ALLOW_READS 分区处理策略时，更改集群缓存的可用性。 

POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}
Copy to Clipboard Toggle word wrap
Expand
表 2.11. 请求参数
参数必需/可选值

可用性

必需

AVAILABLE 或 DEGRADED_MODE

  • AVAILABLE 使缓存对网络分区中的所有节点可用。
  • DEGRADED_MODE 可防止发生网络分区时缓存上的读写操作。
注意

您可以设置内部缓存的可用性，但可能会在未来的 Data Grid 版本中有所变化。

2.1.27. 使用 REST API 索引和查询
复制链接

使用 GET 请求和任何 HTTP 客户端中的 ?action=search&query 参数查询远程缓存。 

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.12. 请求参数
参数必需/可选值

query

必需

指定查询字符串。

max_results

OPTIONAL

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

offset

OPTIONAL

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

local

OPTIONAL

为 true 时，查询仅限于处理请求的节点中存在的数据。默认值为 false。

要使用请求的正文而不是指定查询参数，请按如下方式调用 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.27.1. 重新索引数据
复制链接

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

POST  /v2/caches/{cacheName}/search/indexes?action=mass-index
Copy to Clipboard Toggle word wrap
Expand
表 2.13. 请求参数
参数必需/可选值

模式

OPTIONAL

mode 参数的值如下：

* sync 仅在重新索引操作完成后返回 204 (No Content)。

* async 立即返回 204 (No Content)，重新索引操作将继续在集群中运行。您可以使用 Index Statistics REST 调用来检查状态。

local

OPTIONAL

为 true 时，只有处理请求的节点数据才会被重新索引。默认值为 false，表示所有集群范围的数据都会被重新索引。

2.1.27.2. 清除索引
复制链接

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

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

如果操作成功完成，服务会返回 204 (No Content)。

2.1.27.3. 检索查询和索引统计信息
复制链接

获取有关 GET 请求在缓存中查询和索引的信息。

注意

您必须在缓存配置中启用统计信息或结果为空。 

GET /rest/v2/caches/{cacheName}/search/stats
Copy to Clipboard Toggle word wrap
Expand
表 2.14. 请求参数
参数必需/可选值

scope

OPTIONAL

使用集群检索 集群 所有成员的合并统计。省略时，Data Grid 会返回本地查询和索引的统计信息。

Data Grid 响应

{
  "query": {
    "indexed_local": {
      "count": 1,
      "average": 12344.2,
      "max": 122324,
      "slowest": "FROM Entity WHERE field > 4"
    },
    "indexed_distributed": {
      "count": 0,
      "average": 0.0,
      "max": -1,
      "slowest": "FROM Entity WHERE field > 4"
    },
    "hybrid": {
      "count": 0,
      "average": 0.0,
      "max": -1,
      "slowest": "FROM Entity WHERE field > 4 AND desc = 'value'"
    },
    "non_indexed": {
      "count": 0,
      "average": 0.0,
      "max": -1,
      "slowest": "FROM Entity WHERE desc = 'value'"
    },
    "entity_load": {
      "count": 123,
      "average": 10.0,
      "max": 120
    }
  },
  "index": {
    "types": {
      "org.infinispan.same.test.Entity": {
        "count": 5660001,
        "size": 0
      },
      "org.infinispan.same.test.AnotherEntity": {
        "count": 40,
        "size": 345560
      }
    },
    "reindexing": false
  }
}
Copy to Clipboard Toggle word wrap

在 query 部分：

  • indexed_local 提供有关索引查询的详情。
  • indexed_distributed 提供分布式索引查询的详细信息。
  • 混合 提供有关仅使用索引的查询详情。
  • non_indexed 提供有关不使用索引的查询的详细信息。
  • entity_load 提供在索引查询执行后获取对象的缓存操作的详细信息。
注意

时间始终以纳秒为单位。

在 index 部分中：

  • 类型 提供在缓存中配置的每个索引类型（类名称或 protobuf 消息）的详细信息。

    • 计算为类型索引的实体数量。
    • 类型 的大小 使用（以字节为单位）。
  • 重新索引 如果值为 true，则 索引 程序在缓存中运行。

2.1.27.4. 清除查询统计信息
复制链接

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

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

Data Grid 仅重置本地节点的执行时间。此操作不清除索引统计信息。

2.1.27.5. 检索索引统计信息（已弃用）
复制链接

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

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

Data Grid 响应

{
    "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，则缓存中启动 MassIndexer。

2.1.27.6. 检索查询统计信息（已弃用）
复制链接

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

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

Data Grid 响应

{
    "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 提供加载对象执行的平均时间。
  • object_loaded_count 提供加载的对象计数。
  • search_query_execution_max_time_query_string 提供执行较慢的查询。

2.1.27.7. 清除查询统计信息（已弃用）
复制链接

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

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

2.1.28. 使用缓存的跨站点操作
复制链接

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

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

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

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

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

{
  "NYC": {
    "status": "online"
  },
  "LON": {
    "status": "mixed",
    "online": [
      "NodeA"
    ],
    "offline": [
      "NodeB"
    ]
  }
}
Copy to Clipboard Toggle word wrap
Expand
表 2.15. 返回的状态
值描述

online

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

离线

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

mixed

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

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

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

GET /rest/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.16. 返回的状态
值描述

online

节点在线。

离线

节点离线。

失败

无法检索状态。远程缓存可能会关闭，或者在请求过程中发生网络错误。

2.1.28.3. 离线备份位置
复制链接

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

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

2.1.28.4. 在线备份位置
复制链接

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

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

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

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

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

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

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

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

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

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

GET /rest/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.17. 返回的状态
值描述

SEND

状态转移到备份位置正在进行中。

确定

状态转移成功完成。

ERROR

状态传输发生错误。检查日志文件。

取消

状态转移取消正在进行。

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

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

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

2.1.28.9. 修改所需的离线条件
复制链接

如果满足特定条件，站点会脱机。修改 take offline 参数，以控制备份位置自动下线的时间。

流程

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

    GET /rest/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 /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config
    Copy to Clipboard Toggle word wrap

    如果操作成功完成，服务会返回 204 (No Content)。

2.1.28.10. 取消接收站点的状态传输
复制链接

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

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

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

2.1.29. 滚动升级
复制链接

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

2.1.29.1. 连接源集群
复制链接

使用以下方法将目标集群连接到源集群： 

POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

您必须以 JSON 格式提供一个 remote-store 定义，作为正文：

JSON

{
  "remote-store": {
    "cache": "my-cache",
    "shared": true,
    "raw-values": true,
    "socket-timeout": 60000,
    "protocol-version": "2.9",
    "remote-server": [
      {
        "host": "127.0.0.2",
        "port": 12222
      }
    ],
    "connection-pool": {
      "max-active": 110,
      "exhausted-action": "CREATE_NEW"
    },
    "async-executor": {
      "properties": {
        "name": 4
      }
    },
    "security": {
      "authentication": {
        "server-name": "servername",
        "digest": {
          "username": "username",
          "password": "password",
          "realm": "realm",
          "sasl-mechanism": "DIGEST-MD5"
        }
      },
      "encryption": {
        "protocol": "TLSv1.2",
        "sni-hostname": "snihostname",
        "keystore": {
          "filename": "/path/to/keystore_client.jks",
          "password": "secret",
          "certificate-password": "secret",
          "key-alias": "hotrod",
          "type": "JKS"
        },
        "truststore": {
          "filename": "/path/to/gca.jks",
          "password": "secret",
          "type": "JKS"
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

多个元素是可选的，如 安全、async-executor 和 connection-pool。配置必须包含缓存名称最少，raw-values 设置为 false，以及源集群中单个端口的主机/ip。有关 remote-store 配置的详细信息，请参阅 XSD Schema。

如果操作成功完成，服务会返回 204 (No Content)。如果目标集群已连接到源集群，它会返回 304 状态（未修改）。

2.1.29.2. 获取源集群连接详情
复制链接

要获取缓存的 remote-store 定义，请使用 GET 请求： 

GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

如果缓存之前已连接，它将以 JSON 格式返回关联 remote-store 的配置，以及状态 200 (OK)，否则会返回 404 (Not Found)状态。

注意

这不是一个集群范围的操作，它只会在处理 REST 调用的节点中返回缓存的远程存储。

2.1.29.3. 检查缓存是否已连接
复制链接

要检查缓存是否已连接到远程集群，请使用 HEAD 请求： 

HEAD /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

如果对于集群的所有节点，则返回状态 200 (OK)，cacheName 配置了单个远程存储，否则为 404 (NOT_FOUND)。

2.1.29.4. 同步数据
复制链接

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

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

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

2.1.29.5. 断开源集群
复制链接

将数据与目标集群同步后，使用 DELETE 请求与源集群断开连接： 

DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

如果操作成功完成，服务会返回 204 (No Content)。它没有连接源，它会返回代码 304 （未修改）。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat