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

此内容没有您所选择的语言版本。

Chapter 2. Interacting with the Data Grid REST API

The Data Grid REST API lets you monitor, maintain, and manage Data Grid deployments and provides access to your data.

2.1. Creating and Managing Caches
复制链接

Create and manage Data Grid caches and perform operations on data.

2.1.1. Creating Caches
复制链接

Create named caches across Data Grid clusters with POST requests that include XML or JSON configuration in the payload. 

POST /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap
Expand
Table 2.1. Headers
HeaderRequired or OptionalParameter

Content-Type

REQUIRED

Sets the MediaType for the Data Grid configuration payload; either application/xml or application/json.

Flags

OPTIONAL

Used to set AdminFlags

References

2.1.1.1. XML Configuration
复制链接

Data Grid configuration in XML format must conform to the schema and include:

  • <infinispan> root element.
  • <cache-container> definition.

Example XML Configuration

<infinispan>
    <cache-container>
        <distributed-cache name="cacheName" mode="SYNC">
            <memory>
                <object size="20"/>
            </memory>
        </distributed-cache>
    </cache-container>
</infinispan>
Copy to Clipboard Toggle word wrap

2.1.1.2. JSON Configuration
复制链接

Data Grid configuration in JSON format:

  • Requires the cache definition only.

  • Must follow the structure of an XML configuration.

    • XML elements become JSON objects.
    • XML attributes become JSON fields.

Example JSON Configuration

{
  "distributed-cache": {
    "mode": "SYNC",
    "memory": {
      "object": {
        "size": 20
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

2.1.2. Verifying Caches
复制链接

Check if caches are available in Data Grid clusters with HEAD requests. 

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

2.1.3. Creating Caches with Templates
复制链接

Create caches from Data Grid templates with POST requests and the ?template= parameter. 

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

2.1.4. Retrieving Cache Configuration
复制链接

Retrieve Data Grid cache configurations with GET requests. 

GET /rest/v2/caches/{name}?action=config
Copy to Clipboard Toggle word wrap
Expand
Table 2.2. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

Sets the required format to return content. Supported formats are application/xml and application/json. The default is application/json. See Accept for more information.

2.1.5. Converting Cache Configurations to JSON
复制链接

Invoke a POST request with valid XML configuration and the ?action=toJSON parameter. Data Grid responds with the equivalent JSON representation of the configuration. 

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

2.1.6. Retrieving All Cache Details
复制链接

Invoke a GET request to retreive all details for Data Grid caches. 

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

Data Grid provides a JSON response such as the following: 

{
  "stats": {
    "time_since_start": -1,
    "time_since_reset": -1,
    "hits": -1,
    "current_number_of_entries": -1,
    "current_number_of_entries_in_memory": -1,
    "total_number_of_entries": -1,
    "stores": -1,
    "off_heap_memory_used": -1,
    "data_memory_used": -1,
    "retrievals": -1,
    "misses": -1,
    "remove_hits": -1,
    "remove_misses": -1,
    "evictions": -1,
    "average_read_time": -1,
    "average_read_time_nanos": -1,
    "average_write_time": -1,
    "average_write_time_nanos": -1,
    "average_remove_time": -1,
    "average_remove_time_nanos": -1,
    "required_minimum_number_of_nodes": -1
  },
  "size": 0,
  "configuration": {
    "distributed-cache": {
      "mode": "SYNC",
      "transaction": {
        "stop-timeout": 0,
        "mode": "NONE"
      }
    }
  },
  "rehash_in_progress": false,
  "bounded": false,
  "indexed": false,
  "persistent": false,
  "transactional": false,
  "secured": false,
  "has_remote_backup": false,
  "indexing_in_progress": false,
  "statistics": false
}
Copy to Clipboard Toggle word wrap
  • stats current stats of the cache.
  • size the estimated size for the cache.
  • configuration the cache configuration.
  • rehash_in_progress true when a rehashing is in progress.
  • indexing_in_progress true when indexing is in progress.
  • bounded when expiration is enabled.
  • indexed true if the cache is indexed.
  • persistent true if the cache is persisted.
  • transactional true if the cache is transactional.
  • secured true if the cache is secured.
  • has_remote_backup true if the cache has remote backups.

2.1.7. Adding Entries
复制链接

Add entries to caches with POST requests. 

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

The preceding request places the payload, or request body, in the cacheName cache with the cacheKey key. The request replaces any data that already exists and updates the Time-To-Live and Last-Modified values, if they apply.

If a value already exists for the specified key, the POST request returns an HTTP CONFLICT status and does not modify the value. To update values, you should use PUT requests. See Replacing Entries.

Expand
Table 2.3. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. See Key-Content-Type for more information.

Content-Type

OPTIONAL

Sets the MediaType of the value for the key.

timeToLiveSeconds

OPTIONAL

Sets the number of seconds before the entry is automatically deleted. If you do not set this parameter, Data Grid uses the default value from the configuration. If you set a negative value, the entry is never deleted.

maxIdleTimeSeconds

OPTIONAL

Sets the number of seconds that entries can be idle. If a read or write operation does not occur for an entry after the maximum idle time elapses, the entry is automatically deleted. If you do not set this parameter, Data Grid uses the default value from the configuration. If you set a negative value, the entry is never deleted.

flags

OPTIONAL

The flags used to add the entry. See Flag for more information.

Note

The flags header also applies to all other operations involving data manipulation on the cache,

Note

If both timeToLiveSeconds and maxIdleTimeSeconds have a value of 0, Data Grid uses the default lifespan and maxIdle values from the configuration.

If only maxIdleTimeSeconds has a value of 0, Data Grid uses:

  • the default maxIdle value from the configuration.
  • the value for timeToLiveSeconds that you pass as a request parameter or a value of -1 if you do not pass a value.

If only timeToLiveSeconds has a value of 0, Data Grid uses:

  • the default lifespan value from the configuration.
  • the value for maxIdle that you pass as a request parameter or a value of -1 if you do not pass a value.

2.1.8. Replacing Entries
复制链接

Replace entries in caches with PUT requests. 

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

If a value already exists for the specified key, the PUT request updates the value. If you do not want to modify existing values, use POST requests that return HTTP CONFLICT status instead of modifying values. See Adding Values.

2.1.9. Retrieving Data By Keys
复制链接

Retrieve data for specific keys with GET requests. 

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

The server returns data from the given cache, cacheName, under the given key, cacheKey, in the response body. Responses contain Content-Type headers that correspond to the MediaType negotiation.

Note

Browsers can also access caches directly, for example as a content delivery network (CDN). Data Grid returns a unique ETag for each entry along with the Last-Modified and Expires header fields.

These fields provide information about the state of the data that is returned in your request. ETags allow browsers and other clients to request only data that has changed, which conserves bandwidth.

Expand
Table 2.4. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

Accept

OPTIONAL

Sets the required format to return content. See Accept for more information.

Tip

Append the extended parameter to the query string to get additional information: 

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

The preceding request returns custom headers:

  • Cluster-Primary-Owner returns the node name that is the primary owner of the key.
  • Cluster-Node-Name returns the JGroups node name of the server that handled the request.
  • Cluster-Physical-Address returns the physical JGroups address of the server that handled the request.

2.1.10. Checking if Entries Exist
复制链接

Verify that specific entries exists with HEAD requests. 

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

The preceding request returns only the header fields and the same content that you stored with the entry. For example, if you stored a String, the request returns a String. If you stored binary, base64-encoded, blobs or serialized Java objects, Data Grid does not de-serialize the content in the request.

Note

HEAD requests also support the extended parameter.

Expand
Table 2.5. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

2.1.11. Deleting Entries
复制链接

Remove entries from caches with DELETE requests. 

DELETE /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap
Expand
Table 2.6. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

2.1.12. Deleting Caches
复制链接

Remove caches from Data Grid clusters with DELETE requests. 

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

2.1.13. Retrieving All Keys from Caches
复制链接

Invoke GET requests to retrieve all the keys in a cache in JSON format. 

GET /rest/v2/caches/{cacheName}?action=keys
Copy to Clipboard Toggle word wrap
Expand
Table 2.7. Request Parameters
ParameterRequired or OptionalValue

batch-size

OPTIONAL

Specifies the internal batch size when retrieving the keys. The default value is 1000.

2.1.14. Clearing Caches
复制链接

To delete all data from a cache, invoke a GET request with the ?action=clear parameter. 

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

2.1.15. Getting Cache Size
复制链接

Retrieve the size of caches across the entire cluster with GET requests and the ?action=size parameter. 

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

2.1.16. Getting Cache Statistics
复制链接

Obtain runtime statistics for caches with GET requests. 

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

2.1.17. Querying Caches
复制链接

Perform Ickle queries on caches with GET requests and the ?action=search&query parameter. 

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

Data Grid responds with query hits such as the following: 

{
  "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 displays the total number of results from the query.
  • hits is an array of matches from the query.

  • hit is an object that matches the query.

    Tip

    Hits can contain all fields or a subset of fields if you use a Select clause.

Expand
Table 2.8. Request Parameters
ParameterRequired or OptionalValue

query

REQUIRED

Specifies the query string.

max_results

OPTIONAL

Sets the number of results to return. The default is 10.

offset

OPTIONAL

Specifies the index of the first result to return. The default is 0.

query_mode

OPTIONAL

Specifies how the Data Grid server executes the query. Values are FETCH and BROADCAST. The default is FETCH.

To use the body of the request instead of specifying query parameters, invoke POST requests as follows: 

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

The following example shows a query in the request body: 

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

2.1.18. Re-indexing Data
复制链接

Re-index all data in caches with GET requests and the ?action=mass-index&mode={mode} parameter. 

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

Values for the mode parameter are as follows:

  • sync returns a response of 200 only after the re-indexing operation is complete.
  • async returns a response of 200 immediately and the re-indexing operation continues running in the cluster. You can check the status with the Index Statistics REST call.

2.1.19. Purging Indexes
复制链接

Delete all indexes from caches with GET requests and the ?action=clear parameter. 

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

2.1.20. Retrieving Index Statistics
复制链接

Obtain information about indexes in caches with GET requests. 

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

Data Grid provides a JSON response such as the following: 

{
    "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 Provides the class names of the indexes present in the cache. For Protobuf the value is always org.infinispan.query.remote.impl.indexing.ProtobufValueWrapper.
  • indexed_entities_count Provides the number of entities indexed per class.
  • index_sizes Provides the size, in bytes, for each index in the cache.
  • reindexing Indicates if a re-indexing operation was performed for the cache. If the value is true, the MassIndexer was started in the cache.

2.1.21. Retrieving Query Statistics
复制链接

Get information about the queries that have been run in caches with GET requests. 

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

Data Grid provides a JSON response such as the following: 

{
    "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 Provides the number of queries that have been run.
  • search_query_total_time Provides the total time spent on queries.
  • search_query_execution_max_time Provides the maximum time taken for a query.
  • search_query_execution_avg_time Provides the average query time.
  • object_loading_total_time Provides the total time spent loading objects from the cache after query execution.
  • object_loading_execution_max_time Provides the maximum time spent loading objects execution.
  • object_loading_execution_avg_time Provides the average time spent loading objects execution.
  • objects_loaded_count Provides the count of objects loaded.
  • search_query_execution_max_time_query_string Provides the slowest query executed.

2.1.22. Clearing Query Statistics
复制链接

Reset runtime statistics with GET requests and the ?action=clear parameter. 

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

2.1.23. Listing Caches
复制链接

List all available caches in Data Grid clusters with GET requests. 

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

2.1.24. Cross-Site Operations with Caches
复制链接

Perform cross-site replication operations with the Data Grid REST API.

2.1.24.1. Getting Status of All Backup Locations
复制链接

Retrieve the status of all backup locations with GET requests. 

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

Data Grid responds with the status of each backup location in JSON format, as in the following example: 

{
  "NYC": "online",
  "LON": "offline"
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.9. Returned Status
ValueDescription

online

All nodes in the local cluster have a cross-site view with the backup location.

offline

No nodes in the local cluster have a cross-site view with the backup location.

mixed

Some nodes in the local cluster have a cross-site view with the backup location, other nodes in the local cluster do not have a cross-site view. The response indicates status for each node.

2.1.24.2. Getting Status of Specific Backup Locations
复制链接

Retrieve the status of a backup location with GET requests. 

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

Data Grid responds with the status of each node in the site in JSON format, as in the following example: 

{
  "NodeA":"offline",
  "NodeB":"online"
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.10. Returned Status
ValueDescription

online

The node is online.

offline

The node is offline.

failed

Not possible to retrieve status. The remote cache could be shutting down or a network error occurred during the request.

2.1.24.3. Taking Backup Locations Offline
复制链接

Take backup locations offline with GET requests and the ?action=take-offline parameter. 

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

2.1.24.4. Bringing Backup Locations Online
复制链接

Bring backup locations online with the ?action=bring-online parameter. 

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

2.1.24.5. Pushing State to Backup Locations
复制链接

Push cache state to a backup location with the ?action=start-push-state parameter. 

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

2.1.24.6. Canceling State Transfer
复制链接

Cancel state transfer operations with the ?action=cancel-push-state parameter. 

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

2.1.24.7. Getting State Transfer Status
复制链接

Retrieve status of state transfer operations with the ?action=push-state-status parameter. 

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

Data Grid responds with the status of state transfer for each backup location in JSON format, as in the following example: 

{
   "NYC":"CANCELED",
   "LON":"OK"
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.11. Returned Status
ValueDescription

SENDING

State transfer to the backup location is in progress.

OK

State transfer completed successfully.

ERROR

An error occurred with state transfer. Check log files.

CANCELLING

State transfer cancellation is in progress.

2.1.24.8. Clearing State Transfer Status
复制链接

Clear state transfer status for sending sites with the ?action=clear-push-state-status parameter. 

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

2.1.24.9. Modifying Take Offline Conditions
复制链接

Sites go offline if certain conditions are met. Modify the take offline parameters to control when backup locations automatically go offline.

Procedure

  1. Check configured take offline parameters with GET requests and the take-offline-config parameter. 

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

    The Data Grid response includes after_failures and min_wait fields as follows: 

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

  2. Modify take offline parameters in the body of PUT requests. 

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

2.1.24.10. Canceling State Transfer from Receiving Sites
复制链接

If the connection between two backup locations breaks, you can cancel state transfer on the site that is receiving the push.

Cancel state transfer from a remote site and keep the current state of the local cache with the ?action=cancel-receive-state parameter. 

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

2.1.25. Rolling Upgrades
复制链接

Perform rolling upgrades of cache data between Data Grid clusters

2.1.25.1. Synchronizing Data
复制链接

Synchronize data from a source cluster to a target cluster with GET requests and the ?action=sync-data parameter: 

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

When the operation completes, Data Grid responds with the total number of entries copied to the target cluster.

2.1.25.2. Disconnecting Source Clusters
复制链接

After you synchronize data to target clusters, disconnect from the source cluster with GET requests and the ?action=disconnect-source parameter: 

GET /v2/caches/{cacheName}?action=disconnect-source
Copy to Clipboard Toggle word wrap

2.2. Creating and Managing Counters
复制链接

Create, delete, and modify counters via the REST API.

2.2.1. Creating Counters
复制链接

Create counters with POST requests that include configuration in the payload. 

POST /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap

Example Weak Counter

{
    "weak-counter":{
        "initial-value":5,
        "storage":"PERSISTENT",
        "concurrency-level":1
    }
}
Copy to Clipboard Toggle word wrap

Example Strong Counter

{
    "strong-counter":{
        "initial-value":3,
        "storage":"PERSISTENT",
        "upper-bound":5
    }
}
Copy to Clipboard Toggle word wrap

2.2.2. Deleting Counters
复制链接

Remove specific counters with DELETE requests. 

DELETE /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap

2.2.3. Retrieving Counter Configuration
复制链接

Retrieve configuration for specific counters with GET requests. 

GET /rest/v2/counters/{counterName}/config
Copy to Clipboard Toggle word wrap

Data Grid responds with the counter configuration in JSON format.

2.2.4. Adding Values to Counters
复制链接

Add values to specific counters with POST requests.

Important

This method processes plain/text content only. 

POST /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap

If the request payload is empty, the counter is incremented by one, otherwise the payload is interpreted as a signed long and added to the counter.

Note

WEAK counters never respond after operations.

STRONG counters return the current value after each operation.

2.2.5. Getting Counter Values
复制链接

Retrieve counter values with GET requests. 

GET /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap
Expand
Table 2.12. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

The required format to return the content. Supported formats are application/json and text/plain. JSON is assumed if no header is provided.

2.2.6. Resetting Counters
复制链接

Restore the intial value of counters without GET requests and the ?action=reset parameter. 

GET /rest/v2/counters/{counterName}?action=reset
Copy to Clipboard Toggle word wrap

2.2.7. Incrementing Counters
复制链接

Increment counter values with GET request` and the ?action=increment parameter. 

GET /rest/v2/counters/{counterName}?action=increment
Copy to Clipboard Toggle word wrap
Note

WEAK counters never respond after operations.

STRONG counters return the current value after each operation.

2.2.8. Adding Deltas to Counters
复制链接

Add arbitrary values to counters with GET requests that include the ?action=add and delta parameters. 

GET /rest/v2/counters/{counterName}?action=add&delta={delta}
Copy to Clipboard Toggle word wrap
Note

WEAK counters never respond after operations.

STRONG counters return the current value after each operation.

2.2.9. Decrementing Counter Values
复制链接

Decrement counter values with GET requests and the ?action=decrement parameter. 

GET /rest/v2/counters/{counterName}?action=decrement
Copy to Clipboard Toggle word wrap
Note

WEAK counters never respond after operations.

STRONG counters return the current value after each operation.

Atomically set values for strong counters with GET requests and the compareAndSet parameter. 

GET /rest/v2/counters/{counterName}?action=compareAndSet&expect={expect}&update={update}
Copy to Clipboard Toggle word wrap

Data Grid atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Data Grid returns true.

Atomically set values for strong counters with GET requests and the compareAndSwap parameter. 

GET /rest/v2/counters/{counterName}?action=compareAndSwap&expect={expect}&update={update}
Copy to Clipboard Toggle word wrap

Data Grid atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Data Grid returns the previous value in the payload.

2.2.12. Listing Counters
复制链接

Retrieve a list of counters in Data Grid clusters with GET requests. 

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

2.3. Working with Cache Managers
复制链接

Interact with Data Grid Cache Managers to get cluster and usage statistics.

2.3.1. Getting Basic Cache Manager Information
复制链接

Retrieving information about Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}
Copy to Clipboard Toggle word wrap

Data Grid responds with information in JSON format, as in the following example: 

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

}
Copy to Clipboard Toggle word wrap
  • version contains the Data Grid version
  • name contains the name of the cache manager as defined in the configuration
  • coordinator is true if the cache manager is the coordinator of the cluster
  • cache_configuration_names contains an array of all caches configurations defined in the cache manager
  • cluster_name contains the name of the cluster as defined in the configuration
  • physical_addresses contains the physical network addresses associated with the cache manager
  • coordinator_address contains the physical network addresses of the coordinator of the cluster
  • cache_manager_status the lifecycle status of the cache manager. For possible values, check the org.infinispan.lifecycle.ComponentStatus documentation
  • created_cache_count number of created caches, excludes all internal and private caches
  • running_cache_count number of created caches that are running
  • node_address contains the logical address of the cache manager
  • cluster_members and cluster_members_physical_addresses an array of logical and physical addresses of the members of the cluster
  • cluster_size number of members in the cluster
  • defined_caches A list of all caches defined in the cache manager, excluding private caches but including internal caches that are accessible

2.3.2. Getting Cluster Health
复制链接

Retrieve health information for Data Grid clusters with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/health
Copy to Clipboard Toggle word wrap

Data Grid responds with cluster health information in JSON format, as in the following example: 

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

}
Copy to Clipboard Toggle word wrap

  • cluster_health contains the health of the cluster

    • cluster_name specifies the name of the cluster as defined in the configuration.

    • health_status provides one of the following:

      • DEGRADED indicates at least one of the caches is in degraded mode.
      • HEALTHY_REBALANCING indicates at least one cache is in the rebalancing state.
      • HEALTHY indicates all cache instances in the cluster are operating as expected.
    • number_of_nodes displays the total number of cluster members. Returns a value of 0 for non-clustered (standalone) servers.
    • node_names is an array of all cluster members. Empty for standalone servers.

  • cache_health contains health information per-cache

    • status HEALTHY, DEGRADED or HEALTHY_REBALANCING
    • cache_name the name of the cache as defined in the configuration.

2.3.3. Getting Cache Manager Health Status
复制链接

Retrieve the health status of Cache Managers with GET requests that do not require authentication. 

GET /rest/v2/cache-managers/{cacheManagerName}/health/status
Copy to Clipboard Toggle word wrap

Data Grid responds with one of the following in text/plain format:

  • HEALTHY
  • HEALTHY_REBALANCING
  • DEGRADED

2.3.4. Checking REST Endpoint Availability
复制链接

Verify Data Grid server REST endpoint availability with HEAD requests. 

HEAD /rest/v2/cache-managers/{cacheManagerName}/health
Copy to Clipboard Toggle word wrap

If you receive a successful response code then the Data Grid REST server is running and serving requests.

2.3.5. Obtaining Global Configuration for Cache Managers
复制链接

Retrieve global configuration for Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/config
Copy to Clipboard Toggle word wrap
Expand
Table 2.13. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

The required format to return the content. Supported formats are application/json and application/xml. JSON is assumed if no header is provided.

Reference

GlobalConfiguration

2.3.6. Obtaining Configuration for All Caches
复制链接

Retrieve the configuration for all caches with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs
Copy to Clipboard Toggle word wrap

Data Grid responds with JSON arrays that contain each cache and cache configuration, as in the following example: 

[
  {
      "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"
              }
          }
      }
  }
]
Copy to Clipboard Toggle word wrap

2.3.7. Listing Available Cache Templates
复制链接

Retrieve all available Data Grid cache templates with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs/templates
Copy to Clipboard Toggle word wrap
Tip

Retrieve a list of all available caches for a Cache Manager, along with cache statuses and details, with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/caches
Copy to Clipboard Toggle word wrap

Data Grid responds with JSON arrays that lists and describes each available cache, as in the following example: 

[ {
  "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"
}, {
  "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"
}]
Copy to Clipboard Toggle word wrap

2.3.9. Getting Cache Manager Statistics
复制链接

Retrieve the statistics for Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/stats
Copy to Clipboard Toggle word wrap

Data Grid responds with Cache Manager statistics in JSON format, as in the following example: 

{
    "statistics_enabled":true,
    "read_write_ratio":0.0,
    "time_since_start":1,
    "time_since_reset":1,
    "number_of_entries":0,
    "total_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
}
Copy to Clipboard Toggle word wrap
  • statistics_enabled is true if statistics collection is enabled for the Cache Manager.
  • read_write_ratio displays the read/write ratio across all caches.
  • time_since_start shows the time, in seconds, since the Cache Manager started.
  • time_since_reset shows the number of seconds since the Cache Manager statistics were last reset.
  • number_of_entries shows the total number of entries currently in all caches from the Cache Manager. This statistic returns entries in the local cache instances only.
  • total_number_of_entries shows the number of store operations performed across all caches for the Cache Manager.
  • off_heap_memory_used shows the amount, in bytes[], of off-heap memory used by this cache container.
  • data_memory_used shows the amount, in bytes[], that the current eviction algorithm estimates is in use for data across all caches. Returns 0 if eviction is not enabled.
  • misses shows the number of get() misses across all caches.
  • remove_hits shows the number of removal hits across all caches.
  • remove_misses shows the number of removal misses across all caches.
  • evictions shows the number of evictions across all caches.
  • average_read_time shows the average number of milliseconds taken for get() operations across all caches.
  • average_read_time_nanos same as average_read_time but in nanoseconds.
  • average_remove_time shows the average number of milliseconds for remove() operations across all caches.
  • average_remove_time_nanos same as average_remove_time but in nanoseconds.
  • required_minimum_number_of_nodes shows the required minimum number of nodes to guarantee data consistency.
  • hits provides the number of get() hits across all caches.
  • stores provides the number of put() operations across all caches.
  • current_number_of_entries_in_memory shows the total number of entries currently in all caches, excluding passivated entries.
  • hit_ratio provides the total percentage hit/(hit+miss) ratio for all caches.
  • retrievals shows the total number of get() operations.

2.3.10. Cross-Site Operations with Cache Managers
复制链接

Perform cross-site operations with Cache Managers to apply the operations to all caches.

2.3.10.1. Getting Status of Backup Locations
复制链接

Retrieve the status of all backup locations from Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/
Copy to Clipboard Toggle word wrap

Data Grid responds with status in JSON format, as in the following example: 

{
   "SFO-3":{
      "status":"online"
   },
   "NYC-2":{
      "status":"mixed",
      "online":[
         "CACHE_1"
      ],
      "offline":[
         "CACHE_2"
      ]
   }
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.14. Returned Status
ValueDescription

online

All nodes in the local cluster have a cross-site view with the backup location.

offline

No nodes in the local cluster have a cross-site view with the backup location.

mixed

Some nodes in the local cluster have a cross-site view with the backup location, other nodes in the local cluster do not have a cross-site view. The response indicates status for each node.

2.3.10.2. Taking Backup Locations Offline
复制链接

Take backup locations offline with the ?action=take-offline parameter. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=take-offline
Copy to Clipboard Toggle word wrap

2.3.10.3. Bringing Backup Locations Online
复制链接

Bring backup locations online with the ?action=bring-online parameter. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=bring-online
Copy to Clipboard Toggle word wrap

2.3.10.4. Starting State Transfer
复制链接

Push state of all caches to remote sites with the ?action=start-push-state parameter. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=start-push-state
Copy to Clipboard Toggle word wrap

2.3.10.5. Canceling State Transfer
复制链接

Cancel ongoing state transfer operations with the ?action=cancel-push-state parameter. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=cancel-push-state
Copy to Clipboard Toggle word wrap

2.4. Working with Data Grid Servers
复制链接

Monitor and manage Data Grid server instances.

2.4.1. Retrieving Basic Server Information
复制链接

View basic information about Data Grid servers with GET requests. 

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

Data Grid responds with the server name, codename, and version in JSON format as in the following example: 

{
  "version":"Infinispan 'Codename' xx.x.x.Final"
}
Copy to Clipboard Toggle word wrap

2.4.2. Getting Cache Managers
复制链接

Retrieve lists of cache managers for Data Grid servers with GET requests. 

GET /rest/v2/server/cache-managers
Copy to Clipboard Toggle word wrap

Data Grid responds with an array of the cache manager names configured for the server.

2.4.3. Adding Caches to Ignore Lists
复制链接

Configure Data Grid to temporarily exclude specific caches from client requests. Send empty POST requests that include the names of the cache manager name and the cache. 

POST /v2/server/ignored-caches/{cache-manager}/{cache}
Copy to Clipboard Toggle word wrap

Data Grid returns a service unavailable status (503) for REST client requests and a Server Error (code 0x85) for Hot Rod client requests.

Note

Data Grid currently supports one cache manager per server only. For future compatibility you must provide the cache manager name in the requests.

2.4.4. Removing Caches from Ignore Lists
复制链接

Remove caches from the ignore list with DELETE requests. 

DELETE /v2/server/ignored-caches/{cache-manager}/{cache}
Copy to Clipboard Toggle word wrap

2.4.5. Confirming Ignored Caches
复制链接

Confirm that caches are ignored with GET requests. 

GET /v2/server/ignored-caches/{cache-manager}
Copy to Clipboard Toggle word wrap

2.4.6. Obtaining Server Configuration
复制链接

Retrieve Data Grid server configurations with GET requests. 

GET /rest/v2/server/config
Copy to Clipboard Toggle word wrap

Data Grid responds with the configuration in JSON format, as follows: 

{
    "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"
            }
        }
    }
}
Copy to Clipboard Toggle word wrap

2.4.7. Getting Environment Variables
复制链接

Retrieve all environment variables for Data Grid servers with GET requests. 

GET /rest/v2/server/env
Copy to Clipboard Toggle word wrap

2.4.8. Getting JVM Memory Details
复制链接

Retrieve JVM memory usage information for Data Grid servers with GET requests. 

GET /rest/v2/server/memory
Copy to Clipboard Toggle word wrap

Data Grid responds with heap and non-heap memory statistics, direct memory usage, and information about memory pools and garbage collection in JSON format.

2.4.9. Getting JVM Thread Dumps
复制链接

Retrieve the current thread dump for the JVM with GET requests. 

GET /rest/v2/server/threads
Copy to Clipboard Toggle word wrap

Data Grid responds with the current thread dump in text/plain format.

2.4.10. Stopping Data Grid Servers
复制链接

Stop Data Grid servers with GET requests. 

GET /rest/v2/server?action=stop
Copy to Clipboard Toggle word wrap

Data Grid responds with 200(OK) and then stops running.

2.5. Working with Data Grid Clusters
复制链接

Monitor and perform administrative tasks on Data Grid clusters.

2.5.1. Stopping Data Grid Clusters
复制链接

Shut down entire Data Grid clusters with GET requests. 

GET /rest/v2/cluster?action=stop
Copy to Clipboard Toggle word wrap

Data Grid responds with 200(OK) and then performs an orderly shutdown of the entire cluster.

2.5.2. Stopping Specific Data Grid Servers in Clusters
复制链接

Shut down one or more specific servers in Data Grid clusters with GET requests and the ?action=stop&server parameter. 

GET /rest/v2/cluster?action=stop&server={server1_host}&server={server2_host}
Copy to Clipboard Toggle word wrap

Data Grid responds with 200(OK).

2.6. Using Server Tasks
复制链接

Retrieve, execute, and upload Data Grid server tasks.

2.6.1. Retrieving Server Tasks Information
复制链接

View information about available server tasks with GET requests. 

GET /rest/v2/tasks
Copy to Clipboard Toggle word wrap
Expand
Table 2.15. Request Parameters
ParameterRequired or OptionalValue

type

OPTIONAL

user: will exclude internal (admin) tasks from the results

Data Grid responds with a list of available tasks. The list includes the names of tasks, the engines that handle tasks, the named parameters for tasks, the execution modes of tasks, either ONE_NODE or ALL_NODES, and the allowed security role in JSON format, as in the following example: 

[
  {
    "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"
  }
]
Copy to Clipboard Toggle word wrap

2.6.2. Executing Tasks
复制链接

Execute tasks with GET requests that include the task name and required parameters prefixed with param. 

GET /rest/v2/tasks/myTask?action=exec&param.p1=v1&param.p2=v2
Copy to Clipboard Toggle word wrap

Data Grid responds with the task result.

2.6.3. Uploading Script Tasks
复制链接

Upload script tasks with PUT or POST requests.

Supply the script as the content payload of the request. After Data Grid uploads the script, you can execute it with GET requests. 

POST /rest/v2/tasks/taskName
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat