OneAgent remote configuration management API - POST a configuration job
The request consumes an application/json payload.
| POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement |
| SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/oneagents/remoteConfigurationManagement | |
| Environment ActiveGateCluster ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement |
Authentication
To execute this request, you need an access token with oneAgents.write scope.
To learn how to obtain and use it, see Tokens and authentication.
Parameters
You identify your OneAgents by their IDs. Use the OneAgent on a host request to learn the IDs of OneAgents that you'd like to configure.
| Parameter | Type | Description | In | Required |
|---|---|---|---|---|
| restart | boolean | One Agents will be restarted ( | query | optional |
| body | RemoteConfigurationManagementOperationOneAgentRequest | JSON body of the request, containing remote configuration management job definition. | body | required |
Request body objects
The RemoteConfigurationManagementOperationOneAgentRequest object
Remote configuration management operation creation request.
| Element | Type | Description | Required |
|---|---|---|---|
| entities | string[] | A list of entities IDs for which remote configuration management is to be executed. | required |
| operations | RemoteConfigurationManagementOperation[] | A list of remote configuration management operations to be executed. | required |
The RemoteConfigurationManagementOperation object
Definition of a single remote configuration management operation.
| Element | Type | Description | Required |
|---|---|---|---|
| attribute | string | The attribute which is affected by the operation.
| required |
| operation | string | The operation performed on given attribute.
| required |
| value | string | The value which should be assigned to given attribute. | optional |
Request body JSON model
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"entities": ["HOST-D454A967666E7970","HOST-811760CFF2A5E872"],"operations": [{"attribute": "networkZone","operation": "set","value": "exampleNetworkZoneName"}]}
Response
Response codes
| Code | Type | Description |
|---|---|---|
| 201 | RemoteConfigurationManagementJob | Created |
| 400 | RemoteConfigurationManagementValidationResult | Failed. The input is invalid. |
| 409 | - | Other remote configuration management job is currently being executed |
| 4XX | ErrorEnvelope | Client side error. |
| 5XX | ErrorEnvelope | Server side error. |
Response body objects
The RemoteConfigurationManagementJob object
Remote configuration management job.
| Element | Type | Description |
|---|---|---|
| endTime | string | Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the remote configuration management job was finished. This field is present only for finished jobs. |
| entityType | string | Type of entities modified by remote configuration management.
|
| id | string | The ID of the remote configuration management job. |
| operations | RemoteConfigurationManagementOperation[] | A list of executed remote configuration management jobs. |
| processedEntitiesCount | integer | Number of entities that were already processed at the time the response was created. |
| startTime | string | Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the remote configuration management job was started. |
| timeoutTime | string | Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the running remote configuration management job will time-out. This field is present only for running jobs. |
| totalEntitiesCount | integer | Total number of entities to process. |
The RemoteConfigurationManagementOperation object
Definition of a single remote configuration management operation.
| Element | Type | Description |
|---|---|---|
| attribute | string | The attribute which is affected by the operation.
|
| operation | string | The operation performed on given attribute.
|
| value | string | The value which should be assigned to given attribute. |
Response body JSON model
{"endTime": "2020-11-05T08:15:30.144Z","entityType": "ACTIVE_GATE or ONE_AGENT","id": "7974003406714390819","operations": [{"attribute": "networkZone","operation": "set","value": "exampleNetworkZoneName"}],"processedEntitiesCount": 1,"startTime": "2020-11-05T08:15:30.144Z","timeoutTime": "2020-11-05T08:15:30.144Z","totalEntitiesCount": 1}
The response is not sent to the client until all OneAgents defined in the payload are processed. A OneAgent is considered to be processed when the reconfiguration message is sent to it; the actual reconfiguration is handled independently by the OneAgent.
Validate payload
We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.
The request consumes an application/json payload.
| POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement/validator |
| SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/oneagents/remoteConfigurationManagement/validator | |
| Environment ActiveGateCluster ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement/validator |
Authentication
To execute this request, you need an access token with oneAgents.write scope.
To learn how to obtain and use it, see Tokens and authentication.
Response
Response codes
| Code | Type | Description |
|---|---|---|
| 204 | - | Success. Response doesn't have a body. |
| 400 | RemoteConfigurationManagementValidationResult | Failed. The input is invalid. |
| 4XX | ErrorEnvelope | Client side error. |
| 5XX | ErrorEnvelope | Server side error. |