Bulk copy multiple properties from a node source
POST api/nodes/hostname/copy_properties
Bulk copy property values from a node source to one or more target nodes or node groups. This is useful when you've made a data configuration change on one node and then want to deploy the changes in batches to your entire environment.
At a high level, this is the process to perform a bulk copy.
- Determine your source node - The source node is the origin of the property values you want to copy. You specify the source node hostname in the request.
- Prepare your list of properties - Create a list of the property template names you want to copy from the source node. It is specified as a string array in the request.
- Determine your targets - Determine which target node or node groups you want to bulk copy the properties to. You can specify a target as one or more node hostnames, node group names, or as saved filters.
Request syntax
post api/nodes/<hostname>/copy_properties '{"properties": ["my_property1","my_property2"],"target": {"hostnames": ["sit0001red0","sit0001red1"],"group_names": ["Node Group 1","Node Group 2"]}}'Request parameters
The request accepts the following data in JSON format.
| Parameter | Type | Description | Example | Required |
|---|---|---|---|---|
| source | String | The node source is specified as part of the endpoint path and must be specified as a hostname value. | api/nodes/sit0001red0/copy_properties | Yes |
properties | String array | A list of property template names. | ["my_bridge0", "my_migration_test_hash"] | Yes |
target | Hash | The target details to copy to. | {"group_names": ["RedBox Global"]} | Yes |
Target hash parameters
The target hash parameter accepts the following parameters.
| Key | Type | Description | Required |
|---|---|---|---|
hostnames | String array | The list of target hostnames to copy the property values to. | Only if group_names, saved_filter_id, or saved_filter_name is not present or empty. |
group_names | String array | The list of node group names to copy the property values to. | Only if hostnames, saved_filter_id, or saved_filter_name is not present or empty. |
saved_filter_id | Integer | The property values are copied to all nodes filtered by this saved filter. It only accepts filters that apply to nodes. | Only if hostnames, saved_filter_name, or group_names is not present or empty. |
saved_filter_name | String | The property values are copied to all nodes filtered by this saved filter. It only accepts filters that apply to nodes. | Only if hostnames, saved_filter_id, or group_names is not present or empty. |
Limits
| Item | Maximum amount | Details |
|---|---|---|
| Targets | 2000 | There is a limit of 2000 targets on each request. When using a saved filter, the number of targets the filter returns is counted against this limit. If the filter returns more than 2000 targets, an error is returned. |
| Properties | 15 | There is a limit of 15 properties that can be copied on each request. If more than 15 properties are specified, an error is returned. |
Response syntax
{
"successful_target_count": integer,
"failed_target_count": integer,
"failed_targets": [
{
"hostname": "string",
"message": "string"
}
]
}Response parameters
If the action is successful, either an HTTP 200 or HTTP 201 response is returned. The following data is returned in JSON format.
| Field | Type | Description |
|---|---|---|
successful_target_count | Integer | The number of successful copies. |
failed_target_count | Integer | The number of failed copies. |
failed targets | String array | The details of each failed copy. The hostname or group_name is included with an error message. |
exporter_job | Integer | The ID of the exporter job carrying out the request. |
Errors
The following are common errors returned by this API.
| Code | Message | Cause |
|---|---|---|
| 200/201 | Property <property_template_name> not enabled. | The property being copied doesn't exist on the target. You must ensure all properties are added to the targets before the property values can be copied. A response of 201 is returned if at least one property was successfully copied. |
| 400 | You need to specify at least one property. | The property parameter was empty. You must specify at least one property template name. |
| 422 | Source property <property_template_name> not found. | The specified property doesn't exist on the node source. |
| 422 | Source property <property_template_name> has no value. | The specified property exists on the node source but has no value. |
| 400 | Validation Failed: target is missing | The request has no target. |
| 400 | Please enter a maximum of 15 properties. | More than 15 properties were specified. See Limits. |
| 404 | Not found | The source node in the endpoint path does not exist. |
Examples
Example 1: Bulk copy one or more properties from one node to multiple target nodes.
This example bulk copies the values of properties my_docker_app1_tag and my_docker_app2_tag from node sit0018red0 to nodes sit0023red0 and sit0023red1.
ruby api.rb <customer_code> post api/nodes/sit0018red0/copy_properties '{"properties": ["my_docker_app1_tag","my_docker_app2_tag"],"target": {"hostnames": ["sit0023red0","sit0023red1"]}}'Response
{
"successful_target_count": 2,
"failed_target_count": 0,
"exporter_job": 1562656
}Example 2: Bulk copy one or more properties from one node to multiple target node groups.
This example bulk copies the values of properties my_bridge0 and my_test_hash from node sit0018red0 to node groups RedBox NA and RedBox SA.
ruby api.rb <customer_code> post api/nodes/sit0018red0/copy_properties '{"properties": ["my_bridge0","my_test_hash"],"target": {"group_names": ["RedBox NA","RedBox SA"]}}'The response has the same format as the response in Example 1.
Example 3: Bulk copy one or more properties from one node to a mixed target of nodes and node groups.
This example bulk copies the values of properties my_bridge0 and my_test_hash from node sit0018red0 to nodes sit0023red0 and sit0023red1 and to node groups RedBox NA and RedBox SA.
ruby api.rb <customer_code> post api/nodes/sit0018red0/copy_properties '{"properties": ["my_bridge0","my_test_hash"],"target":{"hostnames": ["sit0023red0","sit0023red1"], "group_names": ["RedBox NA","RedBox SA"]}}'The response has the same format as the response in Example 1.