Data Grid REST API


Red Hat Data Grid 8.5

配置并与 Data Grid REST API 交互

Red Hat Customer Content Services

摘要

访问数据、监控和维护集群,通过 Data Grid REST API 执行管理操作。

Red Hat Data Grid

Data Grid 是一个高性能分布式内存数据存储。

无架构数据结构
将不同对象存储为键值对的灵活性。
基于网格的数据存储
旨在在集群中分发和复制数据。
弹性扩展
动态调整节点数量,以便在不中断服务的情况下满足需求。
数据互操作性
从不同端点在网格中存储、检索和查询数据。

Data Grid 文档

红帽客户门户网站中提供了 Data Grid 的文档。

Data Grid 下载

访问红帽客户门户上的 Data Grid 软件下载

注意

您必须有一个红帽帐户才能访问和下载数据中心软件。

使开源包含更多

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看 CTO Chris Wright 的信息

第 1 章 Data Grid REST 端点

Data Grid 服务器通过在 Netty 基础上构建的 REST 端点提供对数据的 RESTful HTTP 访问。

1.1. REST 身份验证

使用 Data Grid 命令行界面(CLI)和 user 命令配置对 REST 端点的身份验证。CLI 允许您创建和管理用于访问 REST 端点的用户、密码和授权角色。

1.2. 支持的协议

Data Grid REST 端点支持 HTTP/1.1HTTP/2 协议。

您可以执行以下操作之一使用 HTTP/2

1.3. 数据格式和 REST API

Data Grid 缓存以可采用 MediaType 定义的格式存储数据。

有关 MediaTypes 和使用 Data Grid 编码数据的更多信息,请参阅缓存编码和 Marshalling

以下示例为条目配置存储格式:

<distributed-cache>
   <encoding>
      <key media-type="application/x-java-object"/>
      <value media-type="application/xml; charset=UTF-8"/>
   </encoding>
</distributed-cache>

如果没有配置 MediaType,则 Data Grid 默认为 application/octet-stream 用于键和值。但是,如果缓存被索引,Data Grid 默认为 application/x-protostream

1.3.1. 支持的格式

您可以以不同格式编写和读取数据,如果需要,Data Grid 可以在这些格式之间进行转换。

以下 "标准" 格式是可交换的:

  • application/x-java-object
  • application/octet-stream
  • application/x-www-form-urlencoded
  • text/plain

您还可以将前面的数据格式转换为以下格式:

  • application/xml
  • application/json
  • application/x-jboss-marshalling
  • application/x-protostream
  • application/x-java-serialized

Data Grid 还可让您在 application/x-protostreamapplication/json 之间转换。

所有对 REST API 的调用都可以提供描述内容在读取时写入的内容或所需格式的标头。Data Grid 支持为值应用的标准 HTTP/1.1 标头 "Content-Type" 和 "Accept",再加上键的类似效果的 "Key-Content-Type"。

1.3.2. 接受标头

Data Grid REST 端点符合 RFC-2616 Accept 标头,并根据支持的转换协商正确的 MediaType。

例如,在读取数据时发送以下标头:

Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6

前面的标题使 Data Grid 首先以 JSON 格式返回内容(高优先级 0.8)。如果无法将存储格式转换为 JSON,Data Grid 会尝试下一个 文本/纯文本 格式(第二个最高优先级 0.7)。最后,Data Grid 回退到"为",它根据缓存配置选择合适的格式。

1.3.3. 带有特殊 Characters 的名称

创建任何 REST 资源需要一个 URL 的一部分的名称,如果此名称包含 RFC 3986 spec 第 2.2 节 中定义的任何特殊字符,则需要使用 Percent 编码机制对其进行编码

1.3.4. key-Content-Type Headers

大多数 REST API 调用具有 URL 中包含的密钥。在处理这些调用时,Data Grid 假设 Key 是 java.lang.String,但您可以使用特定的标头 Key-Content-Type 用于不同格式的密钥。

key-Content-Type 标头示例

  • 将 byte[] Key 指定为 Base64 字符串:

API 调用:

`PUT /my-cache/AQIDBDM=`

headers:

key-Content-Type: application/octet-stream

  • 将 byte[] Key 指定为十六进制字符串:

API 调用:

GET /my-cache/0x01CA03042F

headers:

Key-Content-Type: application/octet-stream; encoding=hex
  • 指定双密钥:

API 调用:

POST /my-cache/3.141456

headers:

Key-Content-Type: application/x-java-object;type=java.lang.Double

application/x-java-objecttype 参数仅限于:

  • 原语打包程序类型
  • java.lang.String
  • bytes,使 application/x-java-object;type=Bytes 等同于 application/octet-stream;encoding=hex

1.3.5. JSON/Protostream Conversion

当缓存被索引或者特别配置为存储 application/x-protostream 时,您可以发送和接收自动转换为 Protobuf 的 JSON 文档。

您必须注册一个 Protobuf 模式,才能进行转换。

要通过 REST 注册 protobuf 模式,请在 ___protobuf_metadata 缓存中调用 POSTPUT,如下例所示:

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/schema.proto

在编写 JSON 文档时,文档中必须存在一个特殊的字段 _type,才能识别与文档对应的 Protobuf 消息

Person.proto

message Person  {
  required string name = 1;
  required int32 age = 2;
}

Person.json

{
   "_type": "Person",
   "name": "user1",
   "age": 32
}

1.4. 跨资源共享(CORS)请求

Data Grid REST 连接器支持 CORS,包括基于请求来源的 preflight 和规则。

下面显示了一个带有 CORS 规则的 REST 连接器配置示例:

<rest-connector name="rest1" socket-binding="rest" cache-container="default">
   <cors-rules>
      <cors-rule name="restrict host1"
                 allow-credentials="false">
         <allowed-origins>http://host1,https://host1</allowed-origins>
         <allowed-methods>GET</allowed-methods>
      </cors-rule>
      <cors-rule name="allow ALL"
                 allow-credentials="true"
                 max-age-seconds="2000">
         <allowed-origins>*</allowed-origins>
         <allowed-methods>GET,OPTIONS,POST,PUT,DELETE</allowed-methods>
         <allowed-headers>Key-Content-Type</allowed-headers>
      </cors-rule>
   </cors-rules>
</rest-connector>

Data Grid 根据浏览器设置的"Origin"标头来按顺序评估 CORS 规则。

在前面的示例中,如果原始卷是 "http://host1" 或 "https://host1",则应用规则 "restrict host1"。如果原始卷不同,则会测试下一个规则。

因为 "allow ALL" 规则允许所有来源,所以除 "http://host1" 或 "https://host1" 以外的原始脚本都可以执行允许的方法,并使用提供的标头。

有关配置 CORS 规则的详情,请参考 Data Grid Server Configuration Schema

1.4.1. 允许某些原始卷的所有 CORS 权限

在启动服务器时,可以使用 VM 属性 infinispan.server.rest.cors-allow 来允许一个或多个源的所有权限。Example:

./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com

使用此方法指定的所有源都将优先于配置的规则。

第 2 章 与 Data Grid REST API 交互

Data Grid REST API 允许您监控、维护和管理数据网格部署,并提供对数据的访问。

注意

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

2.1. 创建和管理缓存

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

2.1.1. 创建缓存

在 Data Grid 集群中使用 POST 请求(在有效负载中包含 XML 或 JSON 配置)中创建命名缓存。

POST /rest/v2/caches/{cacheName}
表 2.1. Headers
标头必需/可选参数

Content-Type

必需

为 Data Grid 配置有效负载设置 MediaTypeapplication/xmlapplication/json

标记

可选

用于设置 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"/>
    <indexed-entities>
      <indexed-entity>org.infinispan.Person</indexed-entity>
    </indexed-entities>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</distributed-cache>

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"
          },
          "indexed-entities": [
            "org.infinispan.Person"
          ]
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}

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"
    indexedEntities:
      - "org.infinispan.Person"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.

复制的缓存

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"/>
    <indexed-entities>
      <indexed-entity>org.infinispan.Person</indexed-entity>
    </indexed-entities>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</replicated-cache>

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"
        },
      "indexed-entities": [
        "org.infinispan.Person"
      ]
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}

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"
    indexedEntities:
      - "org.infinispan.Person"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.

多个缓存

XML

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:15.0 https://infinispan.org/schemas/infinispan-config-15.0.xsd
                          urn:infinispan:server:15.0 https://infinispan.org/schemas/infinispan-server-15.0.xsd"
      xmlns="urn:infinispan:config:15.0"
      xmlns:server="urn:infinispan:server:15.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>

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"
            }
          }
        }
      }
    }
  }
}

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"

2.1.2. 修改缓存

使用在有效负载中包含 XML 或 JSON 配置的 PUT 请求,在 Data Grid 集群中更改缓存配置中的属性。

注意

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

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

PUT /rest/v2/caches/{cacheName}
表 2.2. Headers
标头必需/可选参数

Content-Type

必需

为 Data Grid 配置有效负载设置 MediaTypeapplication/xmlapplication/json

标记

可选

用于设置 AdminFlags

2.1.3. 验证缓存

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

HEAD /rest/v2/caches/{cacheName}

通过 GET 请求检索缓存运行状况。

GET /rest/v2/caches/{cacheName}?action=health

2.1.4. 使用模板创建缓存

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

POST /rest/v2/caches/{cacheName}?template={templateName}
提示

请参阅 列出可用缓存模板。

2.1.5. 检索缓存配置

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

GET /rest/v2/caches/{name}?action=config
表 2.3. Headers
标头必需/可选参数

accept

可选

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

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

调用带有有效配置和 ?action=convert 参数的 POST 请求。在 Accept 标头指定的类型中,Data Grid 以等效的配置表示。

POST /rest/v2/caches?action=convert

要转换缓存配置,您必须使用 Content-Type 标头和所需的输出格式,使用 Accept 标头指定配置的输入格式。例如,以下命令将复制的缓存配置从 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>'

2.1.7. 比较缓存配置

使用包含两个缓存配置和 ?action=compare 参数的 多部分数据 正文调用 POST 请求。

POST /rest/v2/caches?action=compare
提示

添加 ignoreMutable=true 参数,以忽略比较中的可变属性。

如果配置相等,则数据网格使用 204 (No Content) 响应,如果配置相同,则它们会被 409 (Conflict )。

2.1.8. 检索所有缓存详情

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

GET /rest/v2/caches/{name}?action=stats

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,
    "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,
  "mode" : "DIST_SYNC",
  "storage_type": "HEAP",
  "max_size": "",
  "max_size_bytes" : -1
}
  • 统计 缓存的当前统计信息。
  • 调整缓存的预期大小。
  • 配置 缓存配置。
  • 当重新哈希正在进行时,rehash_in_progress true。
  • 索引进行时,indexing_in_progress true。
  • 如果启用了重新平衡,则 rebalancing_enabled 为 true。获取此属性可能在服务器上失败。在这种情况下,属性不会存在于有效负载中。
  • 启用过期时间时 绑定
  • 如果缓存被索引,则 索引为 true。
  • 如果缓存被保留,则持久性 为 true。
  • 如果缓存是 事务性,则事务性为 true。
  • 如果缓存 被保护,则安全为 true。
  • 如果缓存有远程备份,则 has_remote_backup true。
  • key_storage 缓存密钥的介质类型。
  • value_storage 缓存值的介质类型。
注意

key_storagevalue_storage 与缓存的编码配置匹配。对于没有编码的服务器缓存,当缓存被索引且 应用程序/ 未知时,Data Grid 会假定应用程序/ x-protostream

2.1.9. 重置所有缓存统计信息

调用 POST 请求,以重置 Data Grid 缓存的所有统计信息。

POST /rest/v2/caches/{name}?action=stats-reset

2.1.10. 检索缓存的数据分发

调用 GET 请求,以检索 Data Grid 缓存的数据分布的所有详细信息。

GET /rest/v2/caches/{name}?action=distribution

Data Grid 提供 JSON 响应,如下所示:

[
  {
    "node_name": "NodeA",
    "node_addresses": [
      "127.0.0.1:44175"
    ],
    "memory_entries": 0,
    "total_entries": 0,
    "memory_used": 528512
  },
  {
    "node_name":"NodeB",
    "node_addresses": [
      "127.0.0.1:44187"
    ],
    "memory_entries": 0,
    "total_entries": 0,
    "memory_used": 528512
  }
]

列表中的每个元素代表节点。这些属性是:

  • node_name 是节点名称
  • node_addresses 是所有节点的物理地址的列表。
  • memory_entries 节点在属于缓存的内存中保存的条目数。
  • total_entries 节点内存和属于缓存的磁盘的条目数。
  • memory_used 数值以字节为单位,驱除算法估计缓存占用情况。如果没有启用驱除,则返回 -1。

2.1.11. 检索所有可变缓存配置属性

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

GET /rest/v2/caches/{name}?action=get-mutable-attributes

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"
]

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

GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true

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"
  }
}

对于 type enum 的属性,额外的 universe 属性将包含一组可能的值。

2.1.12. 更新缓存配置属性

调用 POST 请求,以更改可变缓存配置属性。

POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}

2.1.13. 添加条目

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

POST /rest/v2/caches/{cacheName}/{cacheKey}

前面的请求使用 cacheKey 密钥将有效负载或请求正文放在 cacheName 缓存中。请求替换任何已存在的数据,并在应用时更新 Time-To-LiveLast-Modified 值。

如果成功创建了该条目,服务会返回 204 (非内容)。

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

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

Key-Content-Type

可选

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

Content-Type

可选

为键设置 MediaType

timeToLiveSeconds

可选

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

maxIdleTimeSeconds

可选

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

标记

可选

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

注意

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

注意

如果 timeToLiveSecondsmaxIdleTimeSeconds 的值为 0,Data Grid 则使用来自配置的默认 lifespanmaxIdle 值。

如果 只有 maxIdleTimeSeconds 的值为 0, Data Grid 使用:

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

如果 只有 timeToLiveSeconds 的值为 0, Data Grid 使用:

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

2.1.14. 替换条目

使用 PUT 请求替换缓存中的条目。

PUT /rest/v2/caches/{cacheName}/{cacheKey}

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

2.1.15. 按键检索数据

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

GET /rest/v2/caches/{cacheName}/{cacheKey}

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

注意

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

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

表 2.5. 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

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

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

2.1.16. 检查 Entries Exist

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

HEAD /rest/v2/caches/{cacheName}/{cacheKey}

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

注意

HEAD 请求也支持 扩展 参数。

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

Key-Content-Type

可选

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

2.1.17. 删除条目

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

DELETE /rest/v2/caches/{cacheName}/{cacheKey}
表 2.7. Headers
标头必需/可选参数

Key-Content-Type

可选

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

2.1.18. 检查缓存条目的发布

调用此端点,以检索 Data Grid 缓存条目的数据分布详情。

GET /rest/v2/caches/{cacheName}/{cacheKey}?action=distribution

Data Grid 提供 JSON 响应,如下所示:

{
  "contains_key": true,
  "owners": [
    {
      "node_name": "NodeA",
      "primary": true,
      "node_addresses": [
        "127.0.0.1:39492"
      ]
    },
    {
      "node_name": "NodeB",
      "primary": false,
      "node_addresses": [
        "127.0.0.1:38195"
      ]
    }
  ]
}
  • 如果缓存包含密钥,则 contains_key 会返回 true
  • owners 提供包含密钥的节点列表

owners 列表包括以下属性:

  • node_name 显示节点的名称
  • primary 标识是主所有者的节点
  • node_addresses 显示可以访问该节点的 IP 地址和端口

2.1.19. 删除缓存

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

DELETE /rest/v2/caches/{cacheName}

2.1.20. 从缓存检索所有密钥

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

GET /rest/v2/caches/{cacheName}?action=keys
表 2.8. 请求参数
参数必需/可选value

limit

可选

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

batch

可选

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

2.1.21. 从缓存检索所有条目

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

GET /rest/v2/caches/{cacheName}?action=entries
表 2.9. 请求参数
参数必需/可选value

metadata

可选

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

limit

可选

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

batch

可选

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

content-negotiation

可选

如果为 true,则将键和值转换为可读的格式。对于使用文本编码的缓存(如 text/plain、xml、json),服务器以纯文本形式返回键和值。对于带有二进制编码的缓存,如果支持转换,服务器会将条目返回为 JSON,否则以文本十六进制格式返回,如 0xA123CF98。当使用 content-negotiation 时,响应将包含两个标头: key-content-typevalue-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,
        "version": 7
    },
    {
        "key": 3,
        "value": "value2",
        "timeToLiveSeconds": 10,
        "maxIdleTimeSeconds": 45,
        "created": 1607966017944,
        "lastUsed": 1607966017944,
        "expireTime": 1607966027944,
        "version": 7,
        "topologyId": 9
    }
]
  • 条目的密钥。
  • :条目的值。
  • timeToLiveSeconds 基于条目生命周期,但以秒为单位,如果条目永不过期,则为 -1。除非设置了 metadata="true",否则不会返回。
  • maxIdleTimeSeconds 最大空闲时间(以秒为单位)或 -1 ( 如果条目永不过期)。除非设置了 metadata="true",否则不会返回。
  • 为 immortal 条目创建的时间,或为 -1 创建条目。除非设置了 metadata="true",否则不会返回。
  • lastUsed Last time when a operation on the entry or -1 for immortal 条目。除非设置了 metadata="true",否则不会返回。
  • 当条目过期或 -1 用于 immortal 条目时的 expireTime 时间。除非设置了 metadata="true",否则不会返回。
  • Version 与缓存条目相关的元数据版本。只有在存在值时才。
  • topologyId 一个集群版本元数据的拓扑 Id。只有在存在值时才。

2.1.22. 清除缓存

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

POST /rest/v2/caches/{cacheName}?action=clear

如果操作成功完成,服务会返回 204 (不内容)

2.1.23. 获取缓存大小

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

GET /rest/v2/caches/{cacheName}?action=size

2.1.24. 获取缓存统计信息

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

GET /rest/v2/caches/{cacheName}?action=stats

2.1.25. 列出缓存

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

GET /rest/v2/caches/

2.1.26. 获取缓存状态和信息

检索缓存管理器的所有可用缓存的列表,以及缓存状态和详细信息,以及 GET 请求。

GET /rest/v2/caches?action=detailed

Data Grid 响应列出并描述每个可用缓存的 JSON 数组,如下例所示:

[ {
  "status" : "RUNNING",
  "name" : "cache1",
  "type" : "local-cache",
  "simple_cache" : false,
  "transactional" : false,
  "persistent" : false,
  "bounded": false,
  "secured": false,
  "indexed": true,
  "has_remote_backup": true,
  "health":"HEALTHY",
  "rebalancing_enabled": true
}, {
  "status" : "RUNNING",
  "name" : "cache2",
  "type" : "distributed-cache",
  "simple_cache" : false,
  "transactional" : true,
  "persistent" : false,
  "bounded": false,
  "secured": false,
  "indexed": true,
  "has_remote_backup": true,
  "health":"HEALTHY",
  "rebalancing_enabled": false
}]
表 2.10. 请求参数
参数必需/可选描述

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.1.27. 列出角色的可访问缓存

启用安全性后,检索角色的所有可访问缓存的列表。此操作需要 ADMIN 权限。

GET /rest/v2/caches?action=role-accessible&role=observer

data Grid 使用 JSON 响应,如下例所示:

{
  "secured" : ["securedCache1", "securedCache2"],
  "non-secured" : ["cache1", "cache2", "cache3"]
}
表 2.11. 请求参数
参数必需/可选描述

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.1.28. 侦听缓存事件

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

GET /rest/v2/caches/{name}?action=listen
表 2.12. Headers
标头必需/可选参数

accept

可选

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

2.1.29. 启用重新平衡

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

POST /rest/v2/caches/{cacheName}?action=enable-rebalancing

2.1.30. 禁用重新平衡

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

POST /rest/v2/caches/{cacheName}?action=disable-rebalancing

2.1.31. 获取缓存可用性

检索缓存的可用性。

GET /rest/v2/caches/{cacheName}?action=get-availability
注意

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

2.1.32. 设置缓存可用性

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

POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}
表 2.13. 请求参数
参数必需/可选value

可用性

必需

AVAILABLE 或 DEGRADED_MODE

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

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

2.1.33. 设置 Stable Topology

默认情况下,在集群关闭后,Data Grid 会等待所有节点加入集群并恢复拓扑。但是,您可以使用 REST 操作将当前集群拓扑定义为特定缓存的稳定。

POST /rest/v2/caches/{cacheName}?action=initialize&force={FORCE}
表 2.14. 请求参数
参数必需/可选value

force

可选

true 或 false。

  • 当当前拓扑中缺失的节点数量大于或等于拥有者的数量时,需要 force
重要

手动安装拓扑可能会导致数据丢失,只有在无法重新创建初始拓扑时才执行此操作。

2.1.34. 使用 REST API 进行索引和查询

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

GET /rest/v2/caches/{cacheName}?action=search&query={ickle query}

Data Grid 响应

{
  "hit_count" : 150,
  "hit_count_exact" : true,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 12
    }
  } ]
}

  • hit_count 显示查询的结果总数。
  • hit_count_exacttrue,这意味着 hit_count 是准确的。为 false 时,这意味着点击数值为较低的绑定。
  • hits 代表来自查询的单个匹配的数组。
  • hit 指的是与查询中匹配项对应的每个对象。

    提示

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

表 2.15. 请求参数
参数必需/可选value

query

必需

指定查询字符串。

offset

可选

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

max_results

可选

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

hit_count_accuracy

可选

将索引查询的点击数所需的准确性限制为上限。默认值为 10_000。您可以通过设置 query.hit-count-accuracy 缓存属性来更改默认限制。

local

可选

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

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

POST /rest/v2/caches/{cacheName}?action=search

在请求正文中查询

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}

2.1.34.1. 重建索引

当您删除字段或更改索引字段定义时,您必须重建索引以确保索引与缓存中的数据一致。

注意

使用 REST、CLI、Data Grid 控制台或远程客户端重建 Protobuf 模式可能会导致不一致。远程客户端可能具有不同的 Protostream 实体版本,这可能会导致不可靠的行为。

使用 POST 请求和 ?action=reindex 参数在缓存中重新索引所有数据。

POST /rest/v2/caches/{cacheName}/search/indexes?action=reindex
表 2.16. 请求参数
参数必需/可选value

模式

可选

mode 参数的值如下:

* sync 仅在重新索引操作完成后返回 204 (非内容 )。

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

local

可选

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

2.1.34.2. 更新索引模式

更新索引模式操作可让您以最少的停机时间添加模式更改。Data Grid 不移除之前索引的数据并重新创建索引模式,而是为现有的架构添加新字段。

使用 POST 请求和 ?action=updateSchema 参数,更新您缓存中的值的索引模式。

POST /rest/v2/caches/{cacheName}/search/indexes?action=updateSchema
2.1.34.3. 清除索引

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

POST /rest/v2/caches/{cacheName}/search/indexes?action=clear

如果操作成功完成,服务会返回 204 (不内容)

2.1.34.4. get Indexes Metamodel

介绍此缓存中定义的所有索引的完整索引模式 metamodel。

GET /rest/v2/caches/{cacheName}/search/indexes/metamodel

Data Grid 响应

[{
    "entity-name": "org.infinispan.query.test.Book",
    "java-class": "org.infinispan.query.test.Book",
    "index-name": "org.infinispan.query.test.Book",
    "value-fields": {
        "description": {
            "multi-valued": false,
            "multi-valued-in-root": false,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false,
            "analyzer": "standard"
        },
        "name": {
            "multi-valued": false,
            "multi-valued-in-root": true,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false,
            "analyzer": "standard"
        },
        "surname": {
            "multi-valued": false,
            "multi-valued-in-root": true,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false
        },
        "title": {
            "multi-valued": false,
            "multi-valued-in-root": false,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false
        }
    },
    "object-fields": {
        "authors": {
            "multi-valued": true,
            "multi-valued-in-root": true,
            "nested": true,
            "value-fields": {
                "name": {
                    "multi-valued": false,
                    "multi-valued-in-root": true,
                    "type": "java.lang.String",
                    "projection-type": "java.lang.String",
                    "argument-type": "java.lang.String",
                    "searchable": true,
                    "sortable": false,
                    "projectable": false,
                    "aggregable": false,
                    "analyzer": "standard"
                },
                "surname": {
                    "multi-valued": false,
                    "multi-valued-in-root": true,
                    "type": "java.lang.String",
                    "projection-type": "java.lang.String",
                    "argument-type": "java.lang.String",
                    "searchable": true,
                    "sortable": false,
                    "projectable": false,
                    "aggregable": false
                }
            }
        }
    }
}, {
    "entity-name": "org.infinispan.query.test.Author",
    "java-class": "org.infinispan.query.test.Author",
    "index-name": "org.infinispan.query.test.Author",
    "value-fields": {
        "surname": {
            "multi-valued": false,
            "multi-valued-in-root": false,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false
        },
        "name": {
            "multi-valued": false,
            "multi-valued-in-root": false,
            "type": "java.lang.String",
            "projection-type": "java.lang.String",
            "argument-type": "java.lang.String",
            "searchable": true,
            "sortable": false,
            "projectable": false,
            "aggregable": false,
            "analyzer": "standard"
        }
    }
}]

2.1.34.5. 检索查询和索引统计

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

注意

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

GET /rest/v2/caches/{cacheName}/search/stats
表 2.17. 请求参数
参数必需/可选value

scope

可选

使用 cluster 检索群集的所有成员的整合统计数据。如果省略,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
  }
}

query 部分中:

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

时间始终以纳秒为单位。

index 部分中:

  • Type 提供缓存中配置的每个索引类型(类名称或 protobuf 消息)的详情。

    • 计算为类型索引的实体数。
    • 类型 的大小 (以字节为单位)。
  • 如果值为 true,则 索引程序 在缓存中运行。
2.1.34.6. 清除查询统计信息

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

POST /rest/v2/caches/{cacheName}/search/stats?action=clear

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

2.1.34.7. 检索索引统计信息(已弃用)

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

GET /rest/v2/caches/{cacheName}/search/indexes/stats

Data Grid 响应

{
    "indexed_class_names": ["org.infinispan.sample.User"],
    "indexed_entities_count": {
        "org.infinispan.sample.User": 4
    },
    "index_sizes": {
        "cacheName_protobuf": 14551
    },
    "reindexing": false
}

  • indexed_class_names 提供缓存中存在的索引的类名称。对于 Protobuf,值始终为 org.infinispan.query.remote.impl.indexing.ProtobufValueWrapper
  • indexed_entities_count 提供每个类索引的实体数量。
  • index_sizes 为缓存中的每个索引提供大小(以字节为单位)。
  • 重新索引 指示是否对缓存执行重新索引操作。如果值为 true,则 MassIndexer 在缓存中启动。
2.1.34.8. 检索查询统计信息(已弃用)

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

GET /rest/v2/caches/{cacheName}/search/query/stats

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"
}

  • 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.34.9. 清除查询统计信息(已弃用)

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

POST /rest/v2/caches/{cacheName}/search/query/stats?action=clear

2.1.35. 使用缓存进行跨站点操作

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

2.1.35.1. 获取所有备份位置的状态

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

GET /rest/v2/caches/{cacheName}/x-site/backups/

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

{
  "NYC": {
    "status": "online"
  },
  "LON": {
    "status": "mixed",
    "online": [
      "NodeA"
    ],
    "offline": [
      "NodeB"
    ]
  }
}
表 2.18. 返回的状态
value描述

online

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

离线

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

mixed

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

2.1.35.2. 获取特定备份位置的状态

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

GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}

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

{
  "NodeA":"offline",
  "NodeB":"online"
}
表 2.19. 返回的状态
value描述

online

节点在线。

离线

节点离线。

失败

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

2.1.35.3. 使备份位置离线

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

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline
2.1.35.4. 在线提供备份位置

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

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online
2.1.35.5. 将状态推送到备份位置

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

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state
2.1.35.6. 取消状态传输

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

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state
2.1.35.7. 获取状态传输状态

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

GET /rest/v2/caches/{cacheName}/x-site/backups?action=push-state-status

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

{
   "NYC":"CANCELED",
   "LON":"OK"
}
表 2.20. 返回的状态
value描述

发送

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

确定

状态传输成功完成。

ERROR

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

取消

状态转移取消正在进行。

2.1.35.8. 清除状态传输状态

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

POST /rest/v2/caches/{cacheName}/x-site/local?action=clear-push-state-status
2.1.35.9. 修改 会使离线条件

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

流程

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

    GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config

    Data Grid 响应包括 after_failuresmin_wait 字段,如下所示:

    {
      "after_failures": 2,
      "min_wait": 1000
    }
  2. 修改 取 PUT 请求正文中的离线参数。

    PUT /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config

    如果操作成功完成,服务会返回 204 (不内容)

2.1.35.10. 从接收站点取消状态传输

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

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

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-receive-state

2.1.36. 滚动升级

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

2.1.36.1. 连接源集群

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

POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

您必须以 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"
        }
      }
    }
  }
}

几个元素是可选的,如 security,async-executorconnection-pool。配置必须包含缓存名称,raw-values 被设置为 false,以及源集群中单个端口的主机/IP。有关 remote-store 配置的详细信息,请参阅 XSD 架构

如果操作成功完成,服务会返回 204 (非内容)。如果目标集群已连接到源集群,它会返回状态 304 (未修改)。

2.1.36.2. 获取源集群连接详情

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

GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

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

注意

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

2.1.36.3. 检查缓存是否已连接

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

HEAD /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

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

2.1.36.4. 同步数据

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

POST /rest/v2/caches/{cacheName}?action=sync-data

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

2.1.36.5. 断开源集群

将数据同步到目标集群后,使用 DELETE 请求断开与源集群的连接:

DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

如果操作成功完成,服务会返回 204 (不内容)它没有连接源,它会返回代码 304 (未修改)。

2.2. 创建和管理计数器

通过 REST API 创建、删除和修改计数器。

2.2.1. 创建计数器

使用在有效负载中包含配置的 POST 请求创建计数器。

POST /rest/v2/counters/{counterName}

Weak Counter 示例

{
    "weak-counter":{
        "initial-value":5,
        "storage":"PERSISTENT",
        "concurrency-level":1
    }
}

Strong Counter 示例

{
    "strong-counter":{
        "initial-value":3,
        "storage":"PERSISTENT",
        "upper-bound":5
    }
}

2.2.2. 删除计数器

使用 DELETE 请求删除特定的计数器。

DELETE /rest/v2/counters/{counterName}

2.2.3. 检索计数配置

使用 GET 请求检索特定计数器的配置。

GET /rest/v2/counters/{counterName}/config

Data Grid 以 JSON 格式通过计数器配置进行响应。

2.2.4. 获取计数值

使用 GET 请求检索计数器值。

GET /rest/v2/counters/{counterName}
表 2.21. Headers
标头必需/可选参数

accept

可选

返回内容所需的格式。支持的格式有 application/jsontext/plain。如果没有提供标头,则会假定 JSON。

2.2.5. 重置计数器

在没有 POST 请求和 ?action=reset 参数的情况下恢复计数器的初始值。

POST /rest/v2/counters/{counterName}?action=reset

如果操作成功完成,服务会返回 204 (不内容)

2.2.6. 递增计数器

使用 POST 请求' 和 ?action=increment 参数递增计数器值。

POST /rest/v2/counters/{counterName}?action=increment
注意

WEAK 计数器不会在操作后响应,并返回 204 (无内容)。

STRONG 计数器返回 200 (OK),以及每个操作后的当前值。

2.2.7. 将 Deltas 添加到计数器

使用包含 ?action=adddelta 参数的 POST 请求向计数器添加任意值。

POST /rest/v2/counters/{counterName}?action=add&delta={delta}
注意

WEAK 计数器不会在操作后响应,并返回 204 (无内容)。

STRONG 计数器返回 200 (OK),以及每个操作后的当前值。

2.2.8. 减少计数值

使用 POST 请求和 ?action=decrement 参数减少计数器值。

POST /rest/v2/counters/{counterName}?action=decrement
注意

WEAK 计数器不会在操作后响应,并返回 204 (无内容)。

STRONG 计数器返回 200 (OK),以及每个操作后的当前值。

2.2.9. 在 Strong Counters 上执行 getAndSet 原子操作

使用 POST 请求和 getAndSet 参数为强大的计数器设置值。

POST /rest/v2/counters/{counterName}?action=getAndSet&value={value}

如果操作成功,Data Grid 会在有效负载中返回之前的值。

2.2.10. 在 Strong Counters 上执行 compareAndSet 操作

使用 GET 请求和 compareAndSet 参数为强大的计数器设置值。

POST /rest/v2/counters/{counterName}?action=compareAndSet&expect={expect}&update={update}

如果当前的值是 {expect},则按比例将值设置为 {update}。如果操作成功,Data Grid 会返回 true

2.2.11. 在 Strong Counters 上执行 compareAndSwap Operations

使用 GET 请求和 compareAndSwap 参数为强大的计数器设置值。

POST /rest/v2/counters/{counterName}?action=compareAndSwap&expect={expect}&update={update}

如果当前的值是 {expect},则按比例将值设置为 {update}。如果操作成功,Data Grid 会在有效负载中返回之前的值。

2.2.12. 列出计数器

使用 GET 请求在 Data Grid 集群中检索计数器列表。

GET /rest/v2/counters/

2.3. 使用 Protobuf Schemas

通过 Data Grid REST API 创建和管理 Protobuf 模式 .proto 文件。

2.3.1. 创建 Protobuf Schemas

使用 POST 请求在 Data Grid 集群中创建 Protobuf 模式,该请求在有效负载中包含 protobuf 文件的内容。

POST /rest/v2/schemas/{schemaName}

如果架构已存在,Data Grid 会返回 HTTP 409 (Conflict)。如果因为语法错误,架构无效,或者由于缺少某些依赖项,Data Grid 存储模式并在响应正文中返回错误。

Data Grid 使用架构名称和任何错误做出响应。

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • name 是 Protobuf 模式的名称。
  • 对于有效的 Protobuf 模式,错误null。如果 Data Grid 无法成功验证架构,它会返回错误。

如果操作成功完成,服务会返回 201 (Created)

2.3.2. 读取 Protobuf Schemas

使用 GET 请求从 Data Grid 检索 Protobuf 模式。

GET /rest/v2/schemas/{schemaName}

2.3.3. 更新 Protobuf Schemas

使用有效负载中包含 protobuf 文件内容的 PUT 请求修改 Protobuf 模式。

重要

当您更改现有的 Protobuf 模式定义时,您必须更新或重建索引模式。如果更改涉及修改现有字段,则必须重建索引。当您添加新字段时,您可以更新索引模式,而不是重建它。

PUT /rest/v2/schemas/{schemaName}

如果因为语法错误,架构无效,或者由于缺少某些依赖项,Data Grid 会更新该模式,并在响应正文中返回错误。

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • name 是 Protobuf 模式的名称。
  • 对于有效的 Protobuf 模式,错误null。如果 Data Grid 无法成功验证架构,它会返回错误。

2.3.4. 删除 Protobuf Schemas

使用 DELETE 请求从 Data Grid 集群中删除 Protobuf 模式。

DELETE /rest/v2/schemas/{schemaName}

如果操作成功完成,服务会返回 204 (不内容)

2.3.5. 列出 Protobuf Schemas

使用 GET 请求列出所有可用的 Protobuf 模式。

GET /rest/v2/schemas/

Data Grid 使用集群中所有可用的模式列表进行响应。

[ {
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}, {
  "name" : "people.proto",
  "error" : null
}]
  • name 是 Protobuf 模式的名称。
  • 对于有效的 Protobuf 模式,错误null。如果 Data Grid 无法成功验证架构,它会返回错误。

2.3.6. 列出 Protobuf 类型

使用 GET 请求列出所有可用的 Protobuf 类型。

GET /rest/v2/schemas?action=types

Data Grid 使用集群中所有可用的类型列表进行响应。

["org.infinispan.Person", "org.infinispan.Phone"]

2.4. 使用缓存管理器

与 Data Grid Cache Manager 交互以获取集群和用量统计。

2.4.1. 获取基本容器信息

使用 GET 请求检索有关缓存管理器的信息。

GET /rest/v2/container

Data Grid 以 JSON 格式响应信息,如下例所示:

注意

与安全授权的缓存的信息仅适用于具有特定角色和权限的用户。

{
    "version":"xx.x.x-FINAL",
    "name":"default",
    "coordinator":true,
    "cache_configuration_names":[
        "___protobuf_metadata",
        "cache2",
        "CacheManagerResourceTest",
        "cache1"
    ],
    "cluster_name":"ISPN",
    "physical_addresses":"[127.0.0.1:35770]",
    "coordinator_address":"CacheManagerResourceTest-NodeA-49696",
    "cache_manager_status":"RUNNING",
    "created_cache_count":"3",
    "running_cache_count":"3",
    "node_address":"CacheManagerResourceTest-NodeA-49696",
    "cluster_members":[
        "CacheManagerResourceTest-NodeA-49696",
        "CacheManagerResourceTest-NodeB-28120"
    ],
    "cluster_members_physical_addresses":[
        "127.0.0.1:35770",
        "127.0.0.1:60031"
    ],
    "cluster_size":2,
    "defined_caches":[
        {
            "name":"CacheManagerResourceTest",
            "started":true
        },
        {
            "name":"cache1",
            "started":true
        },
        {
            "name":"___protobuf_metadata",
            "started":true
        },
        {
            "name":"cache2",
            "started":true
        }
    ],
    "local_site": "LON",
    "relay_node": true,
    "relay_nodes_address": [
      "CacheManagerResourceTest-NodeA-49696"
    ],
    "sites_view": [
        "LON",
        "NYC"
    ],
    "rebalancing_enabled": true
}
  • 版本 包含 Data Grid 版本
  • name 包含配置中定义的缓存管理器的名称
  • 如果缓存 管理器是集群的协调者,则协调器为 true
  • cache_configuration_names 包含缓存管理器中定义的所有缓存配置的数组,这些配置可以被当前用户访问
  • CLUSTER_ NAME 包含配置中定义的集群名称
  • physical_addresses 包含与缓存管理器关联的物理网络地址
  • coordinator_address 包含集群的协调器的物理网络地址
  • cache_manager_status 是缓存管理器的生命周期状态。如需可能的值,请查看 org.infinispan.lifecycle.ComponentStatus 文档
  • created_cache_count 创建缓存的数量,不包括所有内部和外部缓存
  • running_cache_count 创建的缓存数
  • node_address 包含缓存管理器的逻辑地址
  • cluster_memberscluster_members_physical_addresses 是集群成员的逻辑和物理地址的数组
  • 集群中的成员的 cluster_size 数量
  • defined_caches A 在缓存管理器中定义的所有缓存列表,不包括私有缓存,但包括可以访问的内部缓存
  • local_site 是本地站点的名称。
    如果没有配置跨站点复制,Data Grid 会返回"本地"。
  • 如果节点在集群间处理 RELAY 消息,则 relay_node 为 true。
  • relay_nodes_address 是中继节点的逻辑地址的数组。
  • site _view 参与跨站点复制的站点列表。
    如果没有配置跨站点复制,Data Grid 会返回空列表。
  • 如果启用了重新平衡,则 rebalancing_enabled 为 true。获取此属性可能在服务器上失败。在这种情况下,属性不会存在于有效负载中。

2.4.2. 获取集群健康状况

使用 GET 请求检索 Data Grid 集群的健康状况信息。

GET /rest/v2/container/health

Data Grid 以 JSON 格式响应集群健康信息,如下例所示:

{
    "cluster_health":{
        "cluster_name":"ISPN",
        "health_status":"HEALTHY",
        "number_of_nodes":2,
        "node_names":[
            "NodeA-36229",
            "NodeB-28703"
        ]
    },
    "cache_health":[
        {
            "status":"HEALTHY",
            "cache_name":"___protobuf_metadata"
        },
        {
            "status":"HEALTHY",
            "cache_name":"cache2"
        },
        {
            "status":"HEALTHY",
            "cache_name":"mycache"
        },
        {
            "status":"HEALTHY",
            "cache_name":"cache1"
        }
    ]
}
  • cluster_health 包含集群的运行状况

    • CLUSTER_ NAME 指定配置中定义的集群名称。
    • health_status 提供以下之一:

      • DEGRADED 表示至少一个缓存处于降级模式。
      • HEALTHY_REBALANCING 表示至少一个缓存处于重新平衡状态。
      • HEALTHY 表示集群中的所有缓存实例都如预期运行。
      • FAILED 表示缓存无法使用提供的配置启动。
    • number_of_nodes 显示群集成员的总数。为非集群(standalone)服务器返回值 0。
    • node_names 是所有群集成员的数组。对于单机服务器为空。
  • cache_health 包含每个缓存的健康状况信息

    • Status HEALTHY, DEGRADED, HEALTHY_REBALANCING 或 FAILED
    • cache_name 是配置中定义的缓存名称。

2.4.3. 获取容器健康状态

使用不需要身份验证的 GET 请求,检索 Data Grid 容器的健康状态。

GET /rest/v2/container/health/status

Data Grid 以 text/plain 格式使用以下之一进行响应:

  • 健康
  • HEALTHY_REBALANCING
  • DEGRADED
  • 失败

2.4.4. 检查 REST 端点可用性

使用 HEAD 请求验证 Data Grid 服务器 REST 端点的可用性。

HEAD /rest/v2/container/health

如果您收到成功的响应代码,则 Data Grid REST 服务器正在运行并服务请求。

2.4.5. 获取全局配置

使用 GET 请求检索 data 容器的全局配置。

GET /rest/v2/container/config
表 2.22. Headers
标头必需/可选参数

accept

可选

返回内容所需的格式。支持的格式有 application/jsonapplication/xml。如果没有提供标头,则会假定 JSON。

表 2.23. 请求参数
参数必需/可选描述

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.4.6. 获取所有缓存的配置

使用 GET 请求检索所有缓存的配置。

GET /rest/v2/container/cache-configs

Data Grid 响应包含每个缓存和缓存配置的 JSON 阵列,如下例所示:

[
  {
      "name":"cache1",
      "configuration":{
          "distributed-cache":{
              "mode":"SYNC",
              "partition-handling":{
                  "when-split":"DENY_READ_WRITES"
              },
              "statistics":true
          }
      }
  },
  {
      "name":"cache2",
      "configuration":{
          "distributed-cache":{
              "mode":"SYNC",
              "transaction":{
                  "mode":"NONE"
              }
          }
      }
  }
]
表 2.24. 请求参数
参数必需/可选描述

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.4.7. 列出可用的缓存模板

使用 GET 请求检索所有可用的 Data Grid 缓存模板。

GET /rest/v2/cache-configs/templates
提示
表 2.25. 请求参数
参数必需/可选描述

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.4.8. 获取容器统计信息

使用 GET 请求检索容器的统计信息。

GET /rest/v2/container/stats

Data Grid 以 JSON 格式响应缓存管理器统计信息,如下例所示:

{
    "statistics_enabled":true,
    "read_write_ratio":0.0,
    "time_since_start":1,
    "time_since_reset":1,
    "number_of_entries":0,
    "off_heap_memory_used":0,
    "data_memory_used":0,
    "misses":0,
    "remove_hits":0,
    "remove_misses":0,
    "evictions":0,
    "average_read_time":0,
    "average_read_time_nanos":0,
    "average_write_time":0,
    "average_write_time_nanos":0,
    "average_remove_time":0,
    "average_remove_time_nanos":0,
    "required_minimum_number_of_nodes":1,
    "hits":0,
    "stores":0,
    "current_number_of_entries_in_memory":0,
    "hit_ratio":0.0,
    "retrievals":0
}
  • 如果为 Cache Manager 启用了统计集合,则 statistics_enabledtrue
  • read_write_ratio 显示所有缓存的读/写比率。
  • time_since_start 显示自缓存管理器启动以来的时间(以秒为单位)。
  • time_since_reset 显示缓存管理器统计信息最后一次重置后的秒数。
  • number_of_entries 显示缓存管理器中当前所有缓存中的条目总数。这个统计只返回本地缓存实例中的条目。
  • off_heap_memory_used 显示此缓存容器使用的 off-heap 内存的数量( 以字节为单位[])。
  • data_memory_used 显示当前驱除算法估计用于所有缓存的数据的数量( 以字节为单位[] )。如果没有启用驱除,则返回 0。
  • misses 显示所有缓存的 get () 数。
  • remove_hits 显示所有缓存的删除次数。
  • remove_misses 显示所有缓存间丢失的删除次数。
  • 驱除 显示所有缓存中的驱除数量。
  • average_read_time 显示所有缓存中的 get () 操作的平均毫秒数。
  • average_read_time_nanosaverage_read_time 相同,但以纳秒为单位。
  • average_remove_time 显示所有缓存中的 remove () 操作的平均毫秒数。
  • average_remove_time_nanosaverage_remove_time 相同,但以纳秒为单位。
  • required_minimum_number_of_nodes 显示必要的最少节点数量,以保证数据一致性。
  • hits 提供所有缓存的 get () 命中数。
  • 存储 提供了所有缓存中的 put () 操作数量。
  • current_number_of_entries_in_memory 显示当前所有缓存中的条目总数,不包括传递的条目。
  • hit_ratio 为所有缓存提供总百分比的 hit/(hit+miss)比率。
  • retrieves 显示 get () 操作总数。

2.4.9. 重置容器统计信息

使用 POST 请求重置统计信息。

POST /rest/v2/container/stats?action=reset

2.4.10. 关闭所有容器缓存

使用 POST 请求关闭服务器上的 Data Grid 容器。

POST /rest/v2/container?action=shutdown

Data Grid 使用 204 (无内容) 进行响应,然后关闭容器中的所有缓存。服务器仍然使用活跃端点和集群运行,但对容器资源的 REST 调用会导致 503 Service Unavailable 响应。

注意

这个方法主要供 Data Grid Operator 使用。预期在调用此端点后,服务器进程将很快手动终止。调用此方法后,就无法重启容器状态。

2.4.11. 为所有缓存启用重新平衡

打开所有缓存的自动重新平衡。

POST /rest/v2/container?action=enable-rebalancing

2.4.12. 禁用所有缓存的重新平衡

关闭所有缓存的自动重新平衡。

POST /rest/v2/container?action=disable-rebalancing

2.4.13. 备份网格

创建备份存档 application/zip,其中包含当前存储在 Data Grid 中的资源(缓存、缓存模板、计数器、Protobuf 模式、服务器任务等)

POST /rest/v2/container/backups/{backupName}

如果存在具有相同名称的备份,服务会使用 409 (Conflict) 响应。如果 directory 参数无效,服务会返回 400 (Bad Request)202 响应表示接受备份请求进行处理。

(可选)将您的 JSON 有效负载包含您的请求,其中包含备份操作的参数,如下所示:

表 2.26. JSON 参数
必需/可选value

目录

可选

指定在服务器上创建和存储备份存档的位置。

resources

可选

以 JSON 格式指定要备份的资源。默认为备份所有资源。如果您指定了一个或多个资源,则 Data Grid 仅备份这些资源。如需更多信息 ,请参阅 资源参数表。

表 2.27. 资源参数
必需/可选value

缓存

可选

指定所有缓存的缓存名称数组,或指定为 *

cache-configs

可选

指定一组缓存模板以备份所有模板,或指定为 *

计数器

可选

定义一组要备份的计数器名称,或所有计数器的结尾名称。

proto-schemas

可选

定义一组 Protobuf 模式名称来备份或 * 用于所有模式。

process

可选

指定要备份或所有任务的服务器任务数组。

以下示例在指定目录中创建一个名为 [cache1,cache2] 的备份归档,其中包含所有计数器和缓存:

{
  "directory": "/path/accessible/to/the/server",
  "resources": {
    "caches": ["cache1", "cache2"],
    "counters": ["*"]
  }
}

2.4.14. 列出备份

检索正在进行、完成或失败的所有备份操作的名称。

GET /rest/v2/container/backups

Data Grid 使用所有备份名称阵列响应,如下例所示:

["backup1", "backup2"]

2.4.15. 检查备份可用性

验证备份操作是否完成。

HEAD /rest/v2/container/backups/{backupName}

200 响应表示备份存档可用。202 响应表示备份操作正在进行中。

2.4.16. 下载备份归档

从服务器下载备份存档。

GET /rest/v2/container/backups/{backupName}

200 响应表示备份存档可用。202 响应表示备份操作正在进行中。

2.4.17. 删除备份归档

从服务器中删除备份存档。

DELETE /rest/v2/container/backups/{backupName}

204 响应表示备份存档已被删除。202 响应表示备份操作正在进行,但操作完成后会被删除。

2.4.18. 从备份归档中恢复 Data Grid 资源

从备份存档中恢复 Data Grid 资源。提供的 {restoreName} 用于跟踪恢复进度,独立于正在恢复的备份文件的名称。

POST /rest/v2/container/restores/{restoreName}

202 响应表示接受恢复请求进行处理。

2.4.18.1. 从 Data Grid 服务器上的备份归档中恢复

application/json 内容类型与您的 POST 请求一起使用,以从服务器上可用的存档备份。

表 2.28. JSON 参数
必需/可选value

位置

必需

指定要恢复的备份存档的路径。

resources

可选

以 JSON 格式指定要恢复的资源。默认为恢复所有资源。如果您指定了一个或多个资源,则 Data Grid 只恢复这些资源。如需更多信息 ,请参阅 资源参数表。

表 2.29. 资源参数
必需/可选value

缓存

可选

指定所有缓存的缓存名称数组,或指定为 *

cache-configs

可选

指定一组缓存模板以备份所有模板,或指定为 *

计数器

可选

定义一组要备份的计数器名称,或所有计数器的结尾名称。

proto-schemas

可选

定义一组 Protobuf 模式名称来备份或 * 用于所有模式。

process

可选

指定要备份或所有任务的服务器任务数组。

以下示例从服务器上的备份存档恢复所有计数器:

{
  "location": "/path/accessible/to/the/server/backup-to-restore.zip",
  "resources": {
    "counters": ["*"]
  }
}
2.4.18.2. 从本地备份归档中恢复

multipart/form-data 内容类型与 POST 请求一起使用,将本地备份存档上传到服务器。

表 2.30. 表格数据
参数Content-Type必需/可选value

backup

application/zip

必需

指定要恢复的备份存档的字节。

resources

application/json,text/plain

可选

定义请求参数的 JSON 对象。

请求示例

Content-Type: multipart/form-data; boundary=5ec9bc07-f069-4662-a535-46069afeda32
Content-Length: 7721

--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="resources"
Content-Length: 23

{"scripts":["test.js"]}
--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="backup"; filename="testManagerRestoreParameters.zip"
Content-Type: application/zip
Content-Length: 7353

<zip-bytes>
--5ec9bc07-f069-4662-a535-46069afeda32--

2.4.19. 列出恢复

检索正在进行、完成或失败的所有恢复请求的名称。

GET /rest/v2/container/restores

Data Grid 使用所有恢复名称的数组响应,如下例所示:

["restore1", "restore2"]

2.4.20. 检查 Restore Progress

验证恢复操作是否已完成。

HEAD /rest/v2/container/restores/{restoreName}

201 (Created) 响应表示恢复操作已完成。202 (Accepted) 响应表示备份操作正在进行中。

2.4.21. 删除恢复元数据

删除从服务器恢复请求的元数据。此操作会删除与恢复请求关联的所有元数据,但不会删除任何恢复的内容。如果删除了请求元数据,您可以使用请求名称来执行后续的恢复操作。

DELETE /rest/v2/container/restores/{restoreName}

204 (非内容) 响应表示恢复元数据已被删除。202 (Accepted) 响应表示恢复操作正在进行中,并在操作完成后删除。

2.4.22. 侦听容器配置事件

使用 Server-Sent Events 接收关于配置更改的事件。event 值将是 create-cache、delete-cache、update-cache create-template、delete-templateupdate-template 之一。data 值将包含已创建的实体的声明配置。删除事件将仅包含已删除实体的名称。

GET /rest/v2/container/config?action=listen
表 2.31. Headers
标头必需/可选参数

accept

可选

设置返回内容所需的格式。支持的格式有 application/yamlapplication/jsonapplication/xml。默认为 application/yaml。如需更多信息,请参阅 Accept

表 2.32. 请求参数
参数必需/可选描述

includeCurrentState

可选

如果为 true,则结果还包括现有配置的状态,以及更改。如果设置为 false,则请求仅返回更改。默认值为 false

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.4.23. 侦听容器事件

使用 Server-Sent Events 从容器接收事件。发出的事件来自日志信息,因此每个事件都包含与消息关联的标识符。事件值将是 lifecycle- event 数据 具有日志信息,其中包含 消息,category,level,timestamp,owner,context, 和 scope,其中的一些信息可能为空。目前,我们只公开 LIFECYCLE 事件。

GET /rest/v2/container?action=listen
表 2.33. Headers
标头必需/可选参数

accept

可选

设置返回内容所需的格式。支持的格式有 application/yamlapplication/jsonapplication/xml。默认为 application/yaml。如需更多信息,请参阅 Accept

表 2.34. 请求参数
参数必需/可选描述

includeCurrentState

可选

如果为 true,则结果还包括现有配置的状态,以及更改。如果设置为 false,则请求仅返回更改。默认值为 false

pretty

可选

如果为 true 返回格式化内容,包括额外的空间和行分隔符,以提高可读性,但会增加有效负载大小。默认值为 false

2.4.24. 使用缓存管理器的跨站点操作

使用缓存管理器执行跨站点操作,将操作应用到所有缓存。

2.4.24.1. 获取备份位置的状态

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

GET /rest/v2/container/x-site/backups/

Data Grid 以 JSON 格式的状态响应,如下例所示:

{
   "SFO-3":{
      "status":"online"
   },
   "NYC-2":{
      "status":"mixed",
      "online":[
         "CACHE_1"
      ],
      "offline":[
         "CACHE_2"
      ],
      "mixed": [
         "CACHE_3"
      ]
   }
}
表 2.35. 返回的状态
value描述

online

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

离线

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

mixed

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

GET /rest/v2/container/x-site/backups/{site}

返回单个备份位置的状态。

2.4.24.2. 使备份位置离线

使用 ?action=take-offline 参数使备份位置离线。

POST /rest/v2/container/x-site/backups/{siteName}?action=take-offline
2.4.24.3. 在线提供备份位置

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

POST /rest/v2/container/x-site/backups/{siteName}?action=bring-online
2.4.24.4. 检索状态传输模式

使用 GET 请求检查状态传输模式。

GET /rest/v2/caches/{cacheName}/x-site/backups/{site}/state-transfer-mode
2.4.24.5. 设置状态传输模式

使用 ?action=set 参数配置状态传输模式。

POST /rest/v2/caches/{cacheName}/x-site/backups/{site}/state-transfer-mode?action=set&mode={mode}
2.4.24.6. 启动状态传输

使用 ?action=start-push-state 参数将所有缓存的状态推送到远程站点。

POST /rest/v2/container/x-site/backups/{siteName}?action=start-push-state
2.4.24.7. 取消状态传输

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

POST /rest/v2/container/x-site/backups/{siteName}?action=cancel-push-state

2.5. 使用 Data Grid 服务器

监控和管理 Data Grid 服务器实例。

2.5.1. 检索基本服务器信息

使用 GET 请求查看有关 Data Grid 服务器的基本信息。

GET /rest/v2/server

Data Grid 以 JSON 格式的服务器名称、代码名称和版本响应,如下例所示:

{
  "version":"Infinispan 'Codename' xx.x.x.Final"
}

2.5.2. 获取缓存管理器

使用 GET 请求检索 Data Grid 服务器的缓存管理器列表。

GET /rest/v2/server/cache-managers

Data Grid 响应为服务器配置的缓存管理器名称的数组。

注意

网格目前仅支持每台服务器有一个缓存管理器。

2.5.3. 将缓存添加到 Ignore 列表中

配置 Data Grid,以从客户端请求中临时排除特定的缓存。发送包含缓存管理器名称和缓存名称的空 POST 请求。

POST /rest/v2/server/ignored-caches/{cache}

如果未找到缓存或缓存管理器,Data Grid 会在 204 (未内容 )中成功添加到 ignore 列表或 404 (Not Found) 时响应。

注意

网格目前仅支持每台服务器有一个缓存管理器。对于将来的兼容性,您必须在请求中提供 Cache Manager 名称。

2.5.4. 从 Ignore 列表中删除缓存

使用 DELETE 请求从 ignore 列表中删除缓存。

DELETE /rest/v2/server/ignored-caches/{cache}

如果未找到缓存或缓存管理器,Data Grid 会在 204 (未内容 )中成功从忽略列表中或 404 (Not Found) 进行响应。

2.5.5. 确认 Ignored Caches

确认缓存被忽略了 GET 请求。

GET /rest/v2/server/ignored-caches/

2.5.6. 获取服务器配置

使用 GET 请求检索 Data Grid 服务器配置。

GET /rest/v2/server/config

Data Grid 以 JSON 格式响应配置,如下所示:

{
    "server":{
        "interfaces":{
            "interface":{
                "name":"public",
                "inet-address":{
                    "value":"127.0.0.1"
                }
            }
        },
        "socket-bindings":{
            "port-offset":0,
            "default-interface":"public",
            "socket-binding":[
                {
                    "name":"memcached",
                    "port":11221,
                    "interface":"memcached"
                }
            ]
        },
        "security":{
            "security-realms":{
                "security-realm":{
                    "name":"default"
                }
            }
        },
        "endpoints":{
            "socket-binding":"default",
            "security-realm":"default",
            "hotrod-connector":{
                "name":"hotrod"
            },
            "rest-connector":{
                "name":"rest"
            }
        }
    }
}

2.5.7. 获取环境变量

使用 GET 请求检索 Data Grid 服务器的所有环境变量。

GET /rest/v2/server/env

2.5.8. 获取 JVM 内存详情

使用 GET 请求检索 Data Grid 服务器的 JVM 内存用量信息。

GET /rest/v2/server/memory

网格以 JSON 格式响应堆和非堆内存统计信息、直接内存用量以及有关内存池和垃圾收集的信息。

2.5.9. 获取 JVM 堆转储

使用 POST 请求为 Data Grid 服务器生成 JVM 堆转储。

POST /rest/v2/server/memory?action=heap-dump[&live=true|false]

Data Grid 在服务器数据目录中生成 HPROF 格式的堆转储文件,并使用 JSON 格式文件的完整路径进行响应。

2.5.10. 获取 JVM 线程转储

使用 GET 请求检索 JVM 的当前线程转储。

GET /rest/v2/server/threads

Data Grid 以 text/plain 格式通过当前线程转储进行响应。

2.5.11. 为 Data Grid 服务器获取诊断报告

使用 GET 请求检索 Data Grid 服务器的聚合报告。检索所请求服务器的报告:

GET /rest/v2/server/report

要检索集群中另一台服务器的报告,请按名称引用节点:

GET /rest/v2/server/report/{nodeName}

Data Grid 使用 tar.gz 存档进行响应,其中包含一个聚合的报告,其中包含有关 Data Grid Server 和主机的诊断信息。除了配置和日志文件外,报告还提供有关 CPU、内存、打开文件、网络套接字和路由、线程的详细信息。

2.5.12. 停止 Data Grid 服务器

使用 POST 请求停止 Data Grid 服务器。

POST /rest/v2/server?action=stop

网格以 204 (无内容) 响应,然后停止运行。

2.5.13. 检索客户端连接信息

使用 GET 请求列出与 Data Grid 服务器连接的客户端的信息。

GET /rest/v2/server/connections

Data Grid 以 JSON 格式响应所有活跃客户端连接的详情,如下例所示:

[
  {
    "id": 2,
    "name": "flower",
    "created": "2023-05-18T14:54:37.882566188Z",
    "principal": "admin",
    "local-address": "/127.0.0.1:11222",
    "remote-address": "/127.0.0.1:58230",
    "protocol-version": "RESP3",
    "client-library": null,
    "client-version": null,
    "ssl-application-protocol": "http/1.1",
    "ssl-cipher-suite": "TLS_AES_256_GCM_SHA384",
    "ssl-protocol": "TLSv1.3"
  },
  {
    "id": 0,
    "name": null,
    "created": "2023-05-18T14:54:07.727775875Z",
    "principal": "admin",
    "local-address": "/127.0.0.1:11222",
    "remote-address": "/127.0.0.1:35716",
    "protocol-version": "HTTP/1.1",
    "client-library": "Infinispan CLI 15.0.0-SNAPSHOT",
    "client-version": null,
    "ssl-application-protocol": "http/1.1",
    "ssl-cipher-suite": "TLS_AES_256_GCM_SHA384",
    "ssl-protocol": "TLSv1.3"
  }
]
表 2.36. 请求参数
参数必需/可选value

global

可选

true :将收集来自集群中所有服务器的连接

2.5.14. 为缓存配置检索默认值

使用 GET 请求检索缓存配置的默认值。

POST /rest/v2/server/caches/defaults

Data Grid 以 JSON 格式响应缓存配置的默认值。

2.6. 使用 Data Grid 集群

在 Data Grid 集群中监控并执行管理任务。

2.6.1. 停止 Data Grid 集群

使用 POST 请求关闭整个 Data Grid 集群。

POST /rest/v2/cluster?action=stop

Data Grid 使用 204 (无内容) 进行响应,然后执行整个集群的有序关闭。

2.6.2. 在集群中停止特定的 Data Grid 服务器

使用 GET 请求和 ?action=stop&server 参数关闭 Data Grid 集群中的一个或多个特定服务器。

POST /rest/v2/cluster?action=stop&server={server1_host}&server={server2_host}

Data Grid 使用 204 (无内容) 进行响应。

2.6.3. 备份 Data Grid 集群

创建备份存档 application/zip,其中包含当前存储在集群的缓存容器中的资源(缓存、模板、计数器、Protobuf 模式、服务器任务等)。

POST /rest/v2/cluster/backups/{backupName}

(可选)将您的 JSON 有效负载包含您的请求,其中包含备份操作的参数,如下所示:

表 2.37. JSON 参数
必需/可选value

目录

可选

指定在服务器上创建和存储备份存档的位置。

如果备份操作成功完成,服务会返回 202 (Accepted)。如果存在具有相同名称的备份,服务会返回 409 (Conflict)。如果 directory 参数无效,服务会返回 400 (Bad Request)

2.6.4. 列出备份

检索正在进行、完成或失败的所有备份操作的名称。

GET /rest/v2/cluster/backups

Data Grid 使用所有备份名称阵列响应,如下例所示:

["backup1", "backup2"]

2.6.5. 检查备份可用性

验证备份操作是否完成。200 响应表示备份存档可用。202 响应表示备份操作正在进行中。

HEAD /rest/v2/cluster/backups/{backupName}

2.6.6. 下载备份归档

从服务器下载备份存档。200 响应表示备份存档可用。202 响应表示备份操作正在进行中。

GET /rest/v2/cluster/backups/{backupName}

2.6.7. 删除备份归档

从服务器中删除备份存档。204 响应表示备份存档已被删除。202 响应表示备份操作正在进行,但操作完成后会被删除。

DELETE /rest/v2/cluster/backups/{backupName}

2.6.8. 恢复 Data Grid 集群资源

在备份存档中应用资源以恢复 Data Grid 集群。提供的 {restoreName} 用于跟踪恢复进度,独立于正在恢复的备份文件的名称。

重要

只有在备份存档中的容器名称与集群的容器名称匹配时,才能恢复资源。

POST /rest/v2/cluster/restores/{restoreName}

202 响应表示接受恢复请求进行处理。

2.6.8.1. 从 Data Grid 服务器上的备份归档中恢复

application/json 内容类型与您的 POST 请求一起使用,以从服务器上可用的存档备份。

表 2.38. JSON 参数
必需/可选value

位置

必需

指定要恢复的备份存档的路径。

resources

可选

以 JSON 格式指定要恢复的资源。默认为恢复所有资源。如果您指定了一个或多个资源,则 Data Grid 只恢复这些资源。如需更多信息 ,请参阅 资源参数表。

表 2.39. 资源参数
必需/可选value

缓存

可选

指定所有缓存的缓存名称数组,或指定为 *

cache-configs

可选

指定一组缓存模板以备份所有模板,或指定为 *

计数器

可选

定义一组要备份的计数器名称,或所有计数器的结尾名称。

proto-schemas

可选

定义一组 Protobuf 模式名称来备份或 * 用于所有模式。

process

可选

指定要备份或所有任务的服务器任务数组。

以下示例从服务器上的备份存档恢复所有计数器:

{
  "location": "/path/accessible/to/the/server/backup-to-restore.zip",
  "resources": {
    "counters": ["*"]
  }
}
2.6.8.2. 从本地备份归档中恢复

multipart/form-data 内容类型与 POST 请求一起使用,将本地备份存档上传到服务器。

表 2.40. 表格数据
参数Content-Type必需/可选value

backup

application/zip

必需

指定要恢复的备份存档的字节。

请求示例

Content-Type: multipart/form-data; boundary=5ec9bc07-f069-4662-a535-46069afeda32
Content-Length: 7798

--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="backup"; filename="testManagerRestoreParameters.zip"
Content-Type: application/zip
Content-Length: 7353

<zip-bytes>
--5ec9bc07-f069-4662-a535-46069afeda32--

2.6.9. 列出恢复

检索正在进行、完成或失败的所有恢复请求的名称。

GET /rest/v2/cluster/restores

Data Grid 使用所有恢复名称的数组响应,如下例所示:

["restore1", "restore2"]

2.6.10. 检查 Restore Progress

验证恢复操作是否已完成。

HEAD /rest/v2/cluster/restores/{restoreName}

201 (Created) 响应表示恢复操作已完成。202 响应表示备份操作正在进行中。

2.6.11. 删除恢复元数据

删除从服务器恢复请求的元数据。此操作会删除与恢复请求关联的所有元数据,但不会删除任何恢复的内容。如果删除了请求元数据,您可以使用请求名称来执行后续的恢复操作。

DELETE /rest/v2/cluster/restores/{restoreName}

204 响应表示恢复元数据已被删除。202 响应表示恢复操作正在进行中,操作完成后会被删除。

2.6.12. 检查集群发布

检索 Data Grid 集群中所有服务器的分发详细信息。

GET /rest/v2/cluster?action=distribution

返回集群中每个 Data Grid 服务器统计的 JSON 数组,其格式如下:

[
  {
    "node_name": "NodeA",
    "node_addresses": [
      "127.0.0.1:39313"
    ],
    "memory_available": 466180016,
    "memory_used": 56010832
  },
  {
    "node_name": "NodeB",
    "node_addresses": [
      "127.0.0.1:47477"
    ],
    "memory_available": 467548568,
    "memory_used": 54642280
  }
]

阵列中的每个元素代表一个 Data Grid 节点。如果禁用了统计集合,则有关内存用量值的信息为 -1。这些属性是:

  • node_name 是节点名称。
  • node_addresses 是所有节点的物理地址的列表。
  • memory_available 节点可用内存(以字节为单位)。
  • memory_used 用于节点使用的内存(以字节为单位)。

2.7. Data Grid 服务器日志记录配置

在运行时查看和修改 Data Grid 集群上的日志配置。

2.7.1. 列出日志记录附加器

使用 GET 请求查看所有配置的附加器的列表。

GET /rest/v2/logging/appenders

Data Grid 使用 JSON 格式的附加器列表响应,如下例所示:

{
  "STDOUT" : {
    "name" : "STDOUT"
  },
  "JSON-FILE" : {
    "name" : "JSON-FILE"
  },
  "HR-ACCESS-FILE" : {
    "name" : "HR-ACCESS-FILE"
  },
  "FILE" : {
    "name" : "FILE"
  },
  "REST-ACCESS-FILE" : {
    "name" : "REST-ACCESS-FILE"
  }
}

2.7.2. 列出日志记录器

查看所有配置的带有 GET 请求的日志记录器的列表。

GET /rest/v2/logging/loggers

Data Grid 以 JSON 格式的日志记录器列表响应,如下例所示:

[ {
  "name" : "",
  "level" : "INFO",
  "appenders" : [ "STDOUT", "FILE" ]
}, {
  "name" : "org.infinispan.HOTROD_ACCESS_LOG",
  "level" : "INFO",
  "appenders" : [ "HR-ACCESS-FILE" ]
}, {
  "name" : "com.arjuna",
  "level" : "WARN",
  "appenders" : [ ]
}, {
  "name" : "org.infinispan.REST_ACCESS_LOG",
  "level" : "INFO",
  "appenders" : [ "REST-ACCESS-FILE" ]
} ]

2.7.3. 创建/修改日志记录器

创建一个新的日志记录器,或修改带有 PUT 请求的现有日志记录器。

PUT /rest/v2/logging/loggers/{loggerName}?level={level}&appender={appender}&appender={appender}...

Data Grid 将 {loggerName} 标识的日志记录器级别设置为 {level}。另外,也可以为日志记录器设置一个或多个附加器。如果没有指定附加者,则使用根日志记录器中指定的程序。

如果操作成功完成,服务会返回 204 (不内容)

2.7.4. 删除日志记录器

使用 DELETE 请求移除现有的日志记录器。

DELETE /rest/v2/logging/loggers/{loggerName}

Data Grid 会删除由 {loggerName} 标识的日志记录器,从而有效地恢复到使用根日志记录器配置。

如果操作成功处理,服务会返回响应代码 204 (无内容)。

2.8. 使用服务器任务

检索、执行和上传 Data Grid 服务器任务。

2.8.1. 检索服务器任务信息

使用 GET 请求查看有关可用服务器任务的信息。

GET /rest/v2/tasks
表 2.41. 请求参数
参数必需/可选value

type

可选

User: 将从结果中排除内部(admin)任务

Data Grid 使用可用任务列表响应。列表中包括任务的名称、处理任务的引擎、任务指定参数、任务的执行模式、ONE_NODEALL_NODES 以及 JSON 格式的允许安全角色,如下例所示:

[
  {
    "name": "SimpleTask",
    "type": "TaskEngine",
    "parameters": [
      "p1",
      "p2"
    ],
    "execution_mode": "ONE_NODE",
    "allowed_role": null
  },
  {
    "name": "RunOnAllNodesTask",
    "type": "TaskEngine",
    "parameters": [
      "p1"
    ],
    "execution_mode": "ALL_NODES",
    "allowed_role": null
  },
  {
    "name": "SecurityAwareTask",
    "type": "TaskEngine",
    "parameters": [],
    "execution_mode": "ONE_NODE",
    "allowed_role": "MyRole"
  }
]

2.8.2. 执行任务

使用包含任务名称的 POST 请求、可选缓存名称和所需参数(前缀为 param )执行任务。

POST /rest/v2/tasks/SimpleTask?action=exec&cache=mycache&param.p1=v1&param.p2=v2

Data Grid 在任务结果中响应。

2.8.3. 上传脚本任务

使用 PUTPOST 请求上传脚本任务。

提供脚本作为请求的内容有效负载。在 Data Grid 上传脚本后,您可以使用 GET 请求执行该脚本。

POST /rest/v2/tasks/taskName

2.8.4. 下载脚本任务

使用 GET 请求下载脚本任务。

GET /rest/v2/tasks/taskName?action=script

2.9. 使用 Data Grid 安全性

查看和修改安全信息。

2.9.1. 检索用户的 ACL

查看用户主体和 access-control 列表的信息。

GET /rest/v2/security/user/acl

Data Grid 使用执行请求的用户的信息进行响应。列表中包括用户的主体,以及资源列表以及用户访问它们的权限。

{
  "subject": [
    {
      "name": "deployer",
      "type": "NamePrincipal"
    }
  ],
  "global": [
    "READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"  ],
  "caches": {
    "___protobuf_metadata": [
      "READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
    ],
    "mycache": [
      "LIFECYCLE", "READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "ADMIN", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
    ],
    "___script_cache": [
      "READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
    ]
  }
}

2.9.2. 清空安全缓存

刷新集群中的安全缓存。

POST /rest/v2/security/cache?action=flush

2.9.3. 检索可用的角色

查看服务器中定义的所有可用角色。

GET /rest/v2/security/roles

Data Grid 使用可用角色列表进行响应。如果启用了授权,则只有具有 ADMIN 权限的用户才能调用此 API。

["observer","application","admin","monitor","deployer"]

2.9.4. 获取可用角色详述

查看服务器中定义的所有可用角色及其完整详情。

GET /rest/v2/security/roles?action=detailed

Data Grid 使用可用角色及其详情的列表进行响应。如果启用了授权,则只有具有 ADMIN 权限的用户才能调用此 API。

{
  "observer": {
    "inheritable": true,
    "permissions": [
      "MONITOR",
      "ALL_READ"
    ],
    "implicit": true,
    "description": "..."
  },
  "application": {
    "inheritable": true,
    "permissions": [
      "MONITOR",
      "ALL_WRITE",
      "EXEC",
      "LISTEN",
      "ALL_READ"
    ],
    "implicit": true,
    "description": "..."
  },
  "admin": {
    "inheritable": true,
    "permissions": [
      "ALL"
    ],
    "implicit": true,
    "description": "..."
  },
  "monitor": {
    "inheritable": true,
    "permissions": [
      "MONITOR"
    ],
    "implicit": true,
    "description": "..."
  },
  "deployer": {
    "inheritable": true,
    "permissions": [
      "CREATE",
      "MONITOR",
      "ALL_WRITE",
      "EXEC",
      "LISTEN",
      "ALL_READ"
    ],
    "implicit": true,
    "description": "..."
  }
}

2.9.5. 为主体检索角色

查看映射到主体的所有角色。

GET /rest/v2/security/roles/some_principal

Data Grid 使用指定主体的可用角色列表进行响应。使用中的域中不存在主体的需求。

["observer"]

2.9.6. 为主体授予角色

为主体授予一个或多个新角色。

PUT /rest/v2/security/roles/some_principal?action=grant&role=role1&role=role2
表 2.42. 请求参数
参数必需/可选value

role

必需

角色的名称

2.9.7. 拒绝角色到主体

删除之前授予主体的一个或多个角色。

PUT /rest/v2/security/roles/some_principal?action=deny&role=role1&role=role2
表 2.43. 请求参数
参数必需/可选value

role

必需

角色的名称

2.9.8. 列出主体

列出所有可枚举用户(属性,ldap)的安全域的主体名称

GET /rest/v2/security/principals

Data Grid 使用每个领域的主要主体列表进行响应

{"default:properties":["admin","user1","user2"]}

2.9.9. 创建角色

通过在请求正文中定义名称、其权限和可选描述来创建角色。

POST /rest/v2/security/permissions/somerole?permission=permission1&permission=permission2
表 2.44. 请求参数
参数必需/可选value

权限

必需

权限的名称

2.9.10. 更新角色

更新现有角色权限和/或描述。

POST /rest/v2/security/permissions/somerole?permission=permission1&permission=permission2
表 2.45. 请求参数
参数必需/可选value

权限

必需

权限的名称

2.9.11. 删除角色

删除现有角色。

DELETE /rest/v2/security/permissions/somerole

2.9.12. 检索角色的权限

查看角色的所有权限。

GET /rest/v2/security/permissions/somerole

Data Grid 使用指定主体的可用角色列表进行响应。使用中的域中不存在主体的需求。

{
  "name" : "application",
  "permissions" : [ "LISTEN","ALL_READ","MONITOR","ALL_WRITE","EXEC" ],
  "inheritable": true,
  "implicit": true,
  "description": "..."
}

2.10. 启用跟踪传播

通过 Data Grid Server 和 REST API 进行追踪,您可以监控和分析请求流,并跟踪不同组件的执行路径。

2.10.1. 启用 Data Grid Server 和 REST API 之间的追踪传播

当您在 Data Grid 服务器和 REST API 之间启用追踪传播时,您必须在客户端和服务器端配置追踪。

要将 OpenTelemetry 追踪 span 传播到 Data Grid span,您必须在每个 REST 调用上设置 trace 上下文。

前提条件

  • 在 Data Grid 服务器和远程客户端上启用了追踪。

流程

  1. 使用 io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator 提取当前的追踪上下文。

    提取会生成存储追踪上下文信息的上下文映射。

  2. 在 REST 调用的标头中传递上下文映射,以确保保留 trace 上下文。

    HashMap<String, String> contextMap = new HashMap<>();
    
    // Inject the request with the *current* Context, which contains our current Span.
    W3CTraceContextPropagator.getInstance().inject(Context.current(), contextMap,
    (carrier, key, value) -> carrier.put(key, value));
    
    // Pass the context map in the header
    RestCacheClient client = restClient.cache(CACHE_NAME);
    client.put("aaa", MediaType.TEXT_PLAIN.toString(),RestEntity.create(MediaType.TEXT_PLAIN, "bbb"), contextMap);

客户端应用程序生成的追踪范围与 Data Grid 服务器生成的依赖范围相关联。

法律通告

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutube

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

© 2024 Red Hat, Inc.