To review your changes, retrieve the changelog of the transaction. For details about the transaction model of SPS, see How to configure SPS using REST.
GET https:<IP-address-of-SPS>/api/transaction/changes
| Cookie name | Description | Required | Values |
|---|---|---|---|
| session_id | Contains the authentication token of the user | Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API. Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
The following command retrieves the changelog of the transaction.
curl --cookie cookies https://<IP-address-of-SPS>/api/transaction/changes
The response contains the list of changes performed in the transaction, as list of JSON objects. Every change has a type and a path, other elements depend on the type of the transaction. For example, when you delete an object, the changelog includes the deleted object in the old_value field.
| Element | Type | Description |
|---|---|---|
| new_order | list | The new order of a list after the change. This field is available for reorder transactions. |
| new_value | string or JSON object | The value of the object after the change. For example, the new value of a parameter. |
| old_order | string or JSON object | The order of a list before the change. This field is available for reorder transactions. |
| old_value | string or JSON object | The value of the object before the change. For example, the value of a deleted object. |
| path | string | Path of the changed endpoint or object. |
| type | string | The type of the change. One of: create, delete, reorder, replace |
The following is a sample response received if the changelog is empty.
{
"meta": {
"href": "/api/transaction/changes",
"parent": "/api/transaction",
"transaction": "/api/transaction"
},
"changes": []
}
The following is a sample changelog received after deleting a Channel policy.
{
"meta": {
"href": "/api/transaction/changes",
"parent": "/api/transaction",
"transaction": "/api/transaction"
},
"changes": [
{
"old_value": {
"name": "deny",
"rules": []
},
"path": "/api/configuration/ssh/channel_policies/94615110156697e93121f3",
"type": "delete"
}
]
}
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| Code | Description | Notes |
|---|---|---|
| 200 | OK | Transaction changelog has been retrieved successfully. |
| 401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the GET method to retrieve the changelog a transaction. |
In addition to the standard HTTP status codes, in certain cases, the SPS REST server provides additional information in the response about the error. The following table contains a brief description of such errors. For more details, see the error object in the response body.
| Code | Description | Notes |
|---|---|---|
| 400 | InvalidRequestBody | The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value. |
| 400 | ConfigTreeNotAvailable | An error occurred while preparing the configuration tree for the REST API. |
| 400 | SyntacticError | A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid. |
| 400 | InvalidPath | The path provided by the client contains a syntax error. Path components are restricted to contain only lowercase alphanumeric characters, the dash (-) and the underscore (_) characters. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 400 | SemanticError | The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration. |
| 401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 403 | Unauthorized | The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 404 | NodeNotFound | The requested endpoint does not exist in the configuration. The details section contains the path that you tried to access, but could not be retrieved. |
| 404 | NodeNotAvailable | The requested endpoint exists in the configuration, however, it is not available directly. The details section contains the path that you tried to access, but could not be retrieved. |
| 405 | MethodNotAllowed | An attempt was made to change a configuration subtree in an unsupported way. The method <method> is not allowed for this node. |
| 409 | MidAirCollisionSemanticError | This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would interfere semantically with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction. |
| 409 | WebGuiOrRpcApiConfigInProgress | The configuration of SPS is locked. Opening a new transaction is not allowed while another user is modifying configuration through interfaces other than the REST API. For example, web GUI, console, and so on. |
| 409 | MidAirCollision | This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would overwrite or interfere with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction. |
| 409 | NoTransaction | An attempt was made to change the configuration when no transaction was open. |
| 409 | DoubleTransaction | This error is returned when the client attempts to open a transaction while another transaction of that client is already started. |
| 417 | Expectation Failed |
If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option. |
| 500 | CommitMessageMissing | This error is returned when a commit message is required for committing a transaction, but it was not provided in the commit request. |
| 500 | TransactionCommitError | Unexpected internal errors during committing a transaction are interpreted as TransactionCommitError. |
| 500 | AuthorizationError | The request could not be authorized due to an unexpected internal error. |
The main starting point of navigating the SPS configuration using REST is the https:<IP-address-of-SPS>/api/configuration endpoint. If you query this endpoint, the response contains a list of other endpoints that you can follow to list the various resources of SPS, or to list the objects of a specific resource. For example, https:<IP-address-of-SPS>/api/configuration/rdp lists resources related to controlling the Remote Desktop (RDP) protocol, while https:<IP-address-of-SPS>/api/configuration/rdp/channel_policies lists the available RDP Channel Policies.
Note that when you want to create an object that references another object (for example, a Channel Policy that uses a Content Policy), then the referenced object (in this case, the Content Policy) must already exist. For details, see Create a new object.
To modify or delete an object, you need the ID of the object. For details, see Change an object and Delete an object.
The following is a sample command to query the https:<IP-address-of-SPS>/api/configuration endpoint, and a sample response.
curl --cookie cookies https:<IP-address-of-SPS>/api/configuration
Response status: 200
--- BEGIN RESPONSE BODY ---
{
"meta": {
"first": "/api/configuration",
"href": "/api/configuration",
"last": "/api/configuration",
"next": null,
"parent": null,
"previous": null,
"transaction": "/api/transaction"
},
"items": [
{
"key": "aaa",
"meta": {
"href": "/api/configuration/aaa"
}
},
{
"key": "alerting",
"meta": {
"href": "/api/configuration/alerting"
}
},
{
"key": "datetime",
"meta": {
"href": "/api/configuration/datetime"
}
},
{
"key": "http",
"meta": {
"href": "/api/configuration/http"
}
},
{
"key": "ica",
"meta": {
"href": "/api/configuration/ica"
}
},
{
"key": "local_services",
"meta": {
"href": "/api/configuration/local_services"
}
},
{
"key": "management",
"meta": {
"href": "/api/configuration/management"
}
},
{
"key": "network",
"meta": {
"href": "/api/configuration/network"
}
},
{
"key": "passwords",
"meta": {
"href": "/api/configuration/passwords"
}
},
{
"key": "plugins",
"meta": {
"href": "/api/configuration/plugins"
}
},
{
"key": "policies",
"meta": {
"href": "/api/configuration/policies"
}
},
{
"key": "private_keys",
"meta": {
"href": "/api/configuration/private_keys"
}
},
{
"key": "rdp",
"meta": {
"href": "/api/configuration/rdp"
}
},
{
"key": "reporting",
"meta": {
"href": "/api/configuration/reporting"
}
},
{
"key": "ssh",
"meta": {
"href": "/api/configuration/ssh"
}
},
{
"key": "telnet",
"meta": {
"href": "/api/configuration/telnet"
}
},
{
"key": "troubleshooting",
"meta": {
"href": "/api/configuration/troubleshooting"
}
},
{
"key": "vnc",
"meta": {
"href": "/api/configuration/vnc"
}
},
{
"key": "x509",
"meta": {
"href": "/api/configuration/x509"
}
}
]
}
--- END RESPONSE BODY ---
The following sections describe deleting, creating and changing objects.
© 2024 One Identity LLC. ALL RIGHTS RESERVED. 利用規約 プライバシー Cookie Preference Center