ActiveGate API - POST an auto-update job

Creates a new auto-update job on the specified ActiveGate.

The job updates the ActiveGate to the specified version. You can fetch the list of available versions with the GET available versions of ActiveGate call.

The request consumes and produces an application/json payload.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/api/v2/activeGates/{agId}/updateJobs
Environment ActiveGateCluster ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs

Authentication

To execute this request, you need an access token with activeGates.write scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
agIdstring

The ID of the required ActiveGate.

pathrequired
bodyUpdateJob

JSON body of the request, containing update-job parameters.

bodyrequired

Request body objects

The UpdateJob object

Configuration of the ActiveGate update job.

ElementTypeDescriptionRequired
agTypestring

The type of the ActiveGate.

  • CLUSTER
  • ENVIRONMENT
  • ENVIRONMENT_MULTI
optional
cancelableboolean

The job can (true) or can't (false) be cancelled at the moment.

optional
durationinteger

The duration of the update, in milliseconds.

optional
environmentsstring[]

A list of environments (specified by IDs) the ActiveGate can connect to.

optional
errorstring

The information about update error.

optional
jobIdstring

The ID of the update job.

optional
jobStatestring

The status of the update job.

  • FAILED
  • IN_PROGRESS
  • PENDING
  • ROLLBACK
  • SCHEDULED
  • SKIPPED
  • SUCCEED
optional
startVersionstring

The initial version of the ActiveGate.

optional
targetVersionstring

The target version of the update.

Specify the version in the <major>.<minor>.<revision>.<timestamp> format.

To update to the latest available version, use the latest value.

required
timestampinteger

The timestamp of the update job completion.

The null value means the job is still running.

optional
updateMethodstring

The method of updating the ActiveGate or its component.

  • AUTOMATIC
  • MANUAL_INSTALLATION
  • ON_DEMAND
optional
updateTypestring

The component to be updated.

  • ACTIVE_GATE
  • REMOTE_PLUGIN_AGENT
  • SYNTHETIC
  • Z_REMOTE
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.

{
  "agType": "ENVIRONMENT",
  "cancelable": false,
  "duration": 3608000,
  "environments": [
    "string"
  ],
  "error": "string",
  "jobId": "-3524498778810258605",
  "jobState": "SUCCEED",
  "startVersion": "1.185.0.20200201-120000",
  "targetVersion": "1.190.0.20200301-130000",
  "timestamp": 1582031917814,
  "updateMethod": "AUTOMATIC",
  "updateType": "ACTIVE_GATE"
}

Response

Response codes

CodeTypeDescription
201UpdateJob

Success. The update-job have been created.

400ErrorEnvelope

Failed. The input is invalid.

4XXErrorEnvelope

Client side error.

5XXErrorEnvelope

Server side error.

Response body objects

The UpdateJob object

Configuration of the ActiveGate update job.

ElementTypeDescription
agTypestring

The type of the ActiveGate.

  • CLUSTER
  • ENVIRONMENT
  • ENVIRONMENT_MULTI
cancelableboolean

The job can (true) or can't (false) be cancelled at the moment.

durationinteger

The duration of the update, in milliseconds.

environmentsstring[]

A list of environments (specified by IDs) the ActiveGate can connect to.

errorstring

The information about update error.

jobIdstring

The ID of the update job.

jobStatestring

The status of the update job.

  • FAILED
  • IN_PROGRESS
  • PENDING
  • ROLLBACK
  • SCHEDULED
  • SKIPPED
  • SUCCEED
startVersionstring

The initial version of the ActiveGate.

targetVersionstring

The target version of the update.

Specify the version in the <major>.<minor>.<revision>.<timestamp> format.

To update to the latest available version, use the latest value.

timestampinteger

The timestamp of the update job completion.

The null value means the job is still running.

updateMethodstring

The method of updating the ActiveGate or its component.

  • AUTOMATIC
  • MANUAL_INSTALLATION
  • ON_DEMAND
updateTypestring

The component to be updated.

  • ACTIVE_GATE
  • REMOTE_PLUGIN_AGENT
  • SYNTHETIC
  • Z_REMOTE

Response body JSON model

{
  "agType": "ENVIRONMENT",
  "cancelable": false,
  "duration": 3608000,
  "environments": [
    "string"
  ],
  "error": "string",
  "jobId": "-3524498778810258605",
  "jobState": "SUCCEED",
  "startVersion": "1.185.0.20200201-120000",
  "targetVersion": "1.190.0.20200301-130000",
  "timestamp": 1582031917814,
  "updateMethod": "AUTOMATIC",
  "updateType": "ACTIVE_GATE"
}

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.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/api/v2/activeGates/{agId}/updateJobs/validator
Environment ActiveGateCluster ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs/validator

Authentication

To execute this request, you need an access token with activeGates.write scope.

To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

CodeTypeDescription
204-

Validated. The submitted update-job is valid. Response doesn't have a body.

400ErrorEnvelope

Failed. The input is invalid.

4XXErrorEnvelope

Client side error.

5XXErrorEnvelope

Server side error.

Example

In this example, the request creates an update job to update the ActiveGate with the ID of 1812885988 to the 1.198.0.20200630-163221 version.

The API token is passed in the Authorization header.

Curl

curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/activeGates/1812885988/updateJobs' \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
--data-raw '{
    "targetVersion": "1.198.0.20200630-163221"
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/activeGates/1812885988/updateJobs

Request body

{
  "targetVersion": "1.198.0.20200630-163221"
}

Response body

{
  "jobId": "-7240069678607892845",
  "jobState": "PENDING",
  "updateMethod": null,
  "updateType": null,
  "cancelable": true,
  "startVersion": "1.195.5.20200522-174041",
  "targetVersion": "1.198.0.20200630-163221",
  "timestamp": null,
  "agType": "ENVIRONMENT",
  "environments": [
    "mySampleEnv"
  ],
  "error": null,
  "duration": null
}

Response code

201

Related topics