CloudShell Sandbox API Version 2 Reference Guide

In this article:

login blueprint sandbox execution
login blueprints blueprint start execution id
  blueprint identifier blueprint start persistent execution stop
 

 

 sandboxes  
 

 

 sandbox identifier  
 

 

 sandbox commands  
 

 

 sandbox command name  
 

 

 sandbox command start  
 

 

 sandbox components  
 

 

 sandbox component id  
 

 

 sandbox component commands  
 

 

 component command name  
 

 

 component command start  
 

 

 sandbox activity  
 

 

 sandbox extend  
 

 

 sandbox output  
 

 

 sandbox stop  

 

 

sandbox owner identifier

 

To use the live documentation pages, log in to the Authentication API page using your user credentials and the name of the appropriate CloudShell domain. Then, access the Sandbox API page to execute its methods on the public blueprints and sandboxes in the domain.

Note: Sandbox API can be configured to run in secure mode. See Configuring Sandbox API to Work in HTTPS Mode.

login

Description

Logs the user in to CloudShell, authenticates the user’s credentials and domain, and returns an authorization token to be used with all subsequent requests. Requests that contain this token return information relevant for the specified domain, per the user's permissions.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/login

HTTP method

PUT

Request

Example header format for the login method:

Content-Type: application/json

The user credentials (in JSON format). The parameters of the login method include:

Parameter Description
username The user's name. (string)
password The user's password. (string)
domain The user's domain. (string)

Example request input for the login method in JSON format:

{
   "username":"admin",
   "password":"admin",
   "domain":"Global"
}

Response

The following is a sample authorization token returned by the login method:

"a0IAmINiGUmVsoJS9IeG1A=="

The login method returns an authorization token that must be added to the header of each API method.

blueprints

Description

Gets a list of all the public blueprints associated with the user's domain. Returns blueprint details related to the user's domain and permissions, such as the blueprint GUID and the actions that can be performed on each blueprint.

Note: In CloudShell Portal, make sure to set the blueprints to "Public" as the API does not work with private blueprints.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/blueprints

HTTP method

GET

Request

Example header format for the blueprints method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The blueprints method returns a list of all the blueprints associated with the user's domain and permissions and the actions that can be performed on the individual blueprints:

   }{
      "name":"WebApi",
      "id":"c6abccb6-71eb-423b-b754-477c11d6bc2a",
      "description":null,
      "availability":"Not Available",
      "categories":[
         
      ],
      "estimated_setup_duration":"PT25M""_links":{
         "self":{
            "href":"/blueprints/c6abccb6-71eb-423b-b754-477c11d6bc2a",
            "method":"GET",
            "name":"get a blueprint's details",
            "templated":true
         },
         "all":{
            "href":"/blueprints",
            "method":"GET",
            "name":"get available blueprints according to the user domain"
         },
         "create_sandbox":{
            "href":"/blueprints/c6abccb6-71eb-423b-b754-477c11d6bc2a/start",
            "method":"POST",
            "name":"create a sandbox from the blueprint",
            "templated":true
         }
      }
   }
]

The response output properties of the blueprints method are described in the following table.

Property Sub Property Description/Comments
name   The name of the blueprint. (string)
id   The ID of the blueprint. (string)
description   A short description about the
blueprint. (string)
availability   The availability of the blueprint.
Possible values: Available Now, Not Available.
(string)
categories   The categories assigned to the blueprint.
(string)
estimated_setup_duration   The estimated setup duration of the sandbox. The estimated duration's value is specified in ISO 8601 format.
_links   The actions that can be performed on the blueprints in the user's domain:
  self Provides a link to get the blueprint's details via a GET request.
  all Provides a link to get all available blueprints according to the user's domain via a GET request.
  create_sandbox Provides a link to create a sandbox from the blueprint
via a POST request.

blueprint identifier

Description

Gets details and available actions for a particular public blueprint associated with the user's domain.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/blueprints/{blueprint_identifier}

HTTP method

GET

Request

Note: You can get the blueprint name and blueprint ID from the blueprints method or from the blueprint ID segment in the CloudShell Portal URL).

Parameter Description/Comments
blueprint_identifier

The name or id of the blueprint (string).

Example header format for the blueprint identifier method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The example response of the blueprint identifier method is similar to that of the blueprints method. However, in this case the output properties are displayed for a particular blueprint (as opposed to multiple ones), and includes any published blueprint and resource input parameters. The API can call a blueprint by name or ID.

blueprint start

Description

Creates a new sandbox from a specific public blueprint associated with the user's domain. Returns details about the sandbox such as ID and the actions that can be performed on the sandbox. (After the sandbox is created, you can view it in the Sandboxes dashboard in CloudShell Portal.)

Notes:
  • You cannot reserve blueprints if there are conflicts with the reservation timeslot. For additional information see Creating Sandboxes.
  • This method does not support persistent sandboxes. As such, starting a persistent sandbox will deploy a regular sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/blueprints/{blueprint_identifier}/start

HTTP method

POST

Request

Example header format for the blueprint start method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

The scheduling and input parameters of the sandbox in JSON format. The elements of the blueprint start method include:

Parameter Description/Comments
name

The name of the sandbox. (string)

If you do not specify a name, you will get the following error message: "Reservation name and duration must be specified in request body".
duration

The duration for this sandbox. Time must be specified in ISO 8601 format (for example PT23H). (string)

If you do not specify the duration, you will get the following error message: "Duration format must be a valid 'ISO 8601' (e.g 'PT23H' or 'PT4H2M')".

params

Any published input parameters defined for the blueprint and its abstract resources. Input parameters that have no default must be included in the request. Abstract resource input parameters must be associated to global inputs (specify the global inputs in the request). (Array)

If you do not specify the input parameters, you will get the following error message: "Blueprint has invalid inputs".

permitted_users Users permitted to use the sandbox. Permitted users must have access to the logged-in domain. 
{
   "name":"testbp-sndbx",
   "duration":"PT2H5M",
   "params":[
      {
         "name":"global1",
         "value":"value1"
      },
      {
         "name":"abstract resource 1.attribute4",
         "value":"some value"
      },
      {
         "name":"abstract resource 1/sub resource.attribute4",
         "value":"some value"
      }
   ],
   "permitted_users":[
      "john.s",
      "emily.b",
      "lucas.w"
   ]
}

Response

The blueprint start method returns details about the new sandbox. The output includes details about the sandbox ID and the actions that can be performed on the sandbox:

{
   "name":"Test Blprnt2",
   "id":"994bd534-740a-45f5-851f-ff452f2a17a2",
   "state":"Ready",
   "type":"Sandbox",
   "components":[
      {
         "id":"82159835-2d95-46a9-95ec-9251963d203d",
         "name":"MyApp",
         "type":"Application",
         "component_type":"Generic App Model",
         "app_lifecycle":"undeployed",
         "_links":{
            "self":{
               "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/components/82159835-2d95-46a9-95ec-9251963d203d",
               "method":"GET"
            }
         }
      }
   ],
   "_links":{
      "self":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2",
         "method":"GET",
      },
      "components":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/components",
         "method":"GET"
      },
      "stop":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/stop",
         "method":"POST",
      },
      "all":{
         "href":"/sandboxes",
         "method":"GET",
      }
   }

The response output properties of the blueprint start method are described in the following table.

Property Sub Property Description/Comments
name   The name of the sandbox. (string)
id   The ID of the sandbox. (string)
state   The current state of the sandbox. Possible values: Pending, Setup, Ready, Teardown, Error, Ended. (string)
type   The sandbox type ("Sandbox"). (string)
components   The resource model of the sandbox. (array)
  name The name of the component. (string)
  type The component ("resource", "application", or "service"). (string)
  component_
type 		The resource model. (string)
  app_lifecycle (Available for App components) The current state of the App ("undeployed"/"deployed"). (string)
  _links The actions that can be performed on the sandbox component (Get component details).
_links   The actions that can be performed on the sandbox in the user's domain:
  self Provides a link to get the details for the sandbox via a GET request.
  components Provides a link to get all components in the sandbox via a GET request.
  stop Provides a link to get stop the sandbox via a POST request.
  all Provides a link to get all available sandboxes according to the user's domain via a GET request.

blueprint start persistent

Description

Creates a new persistent sandbox from a specific public persistent blueprint associated with the user's domain. Returns details about the persistent sandbox such as ID and the actions that can be performed on the sandbox. (After the sandbox is created, you can view it in the Sandboxes dashboard in CloudShell Portal.)

Notes:
  • You cannot reserve blueprints if there are conflicts with the reservation timeslot. For additional information see Creating Sandboxes.
  • This method does not support regular sandboxes. As such, attempting to start a regular blueprint will end in error.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/blueprints/{blueprint_identifier}/start-persistent

HTTP method

POST

Request

Example header format for the blueprint start method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

The scheduling and input parameters of the sandbox in JSON format. The elements of the blueprint start method include:

Parameter Description/Comments
name

The name of the sandbox. (string)

If you do not specify a name, you will get the following error message: "Reservation name must be specified in request body".
params

Any published input parameters defined for the blueprint and its abstract resources. Input parameters that have no default must be included in the request. Abstract resource input parameters must be associated to global inputs (specify the global inputs in the request). (Array)

If you do not specify the input parameters, you will get the following error message: "Blueprint has invalid inputs".

permitted_users Users permitted to use the sandbox. Permitted users must have access to the logged-in domain. 
{
  "name": "Persistent sandbox name",
  "params": [
  ],
  "permitted_users": [
     "steven",
     "julia"
  ]
}

Response

The blueprint start method returns details about the new sandbox. The output includes details about the sandbox ID and the actions that can be performed on the sandbox:

{
  "name": "Persistent sandbox name",
  "id": "8d653d03-9e12-47ce-9d30-19cae1a239c3",
  "blueprint_id": "b4852f4b-d2bd-4dbc-b03a-f943941a9053",
  "description": "Blueprint with preconfigured setup & teardown processes.Deploys Apps and resolves connections on Setup, and deletes App VMs on Teardown",
  "start_time": "2021-08-02T09:22:00Z",
  "end_time": null,
  "state": "BeforeSetup",
  "type": "Sandbox",
  "components": [
    {
      "id": "6644dc07-1cc1-4b28-9879-0c704f106c2b",
      "name": "cloudshell-latest",
      "type": "Application",
      "component_type": "Generic App Model",
      "app_lifecycle": "Undeployed",
      "_links": {
        "self": {
          "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3/components/6644dc07-1cc1-4b28-9879-0c704f106c2b",
          "method": "GET"
        }
      }
    },
    {
      "id": "92259d2a-3928-46ec-9da8-65eccc19b7f8",
      "name": "dbs-latest-cloudshell",
      "type": "Application",
      "component_type": "Generic App Model",
      "app_lifecycle": "Undeployed",
      "_links": {
        "self": {
          "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3/components/92259d2a-3928-46ec-9da8-65eccc19b7f8",
          "method": "GET"
        }
      }
    }
  ],
  "parameters": [],
  "setup_stage": "None",
  "permitted_users": [
    "admin",
    "julia",
    "steven"
  ],
  "_links": {
    "self": {
      "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3",
      "method": "GET"
    },
    "components": {
      "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3/components",
      "method": "GET"
    },
    "output": {
      "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3/output",
      "method": "GET"
    },
    "stop": {
      "href": "/sandboxes/8d653d03-9e12-47ce-9d30-19cae1a239c3/stop",
      "method": "POST"
    },
    "all": {
      "href": "/sandboxes",
      "method": "GET"
    },
    "blueprint": {
      "href": "/blueprints/b4852f4b-d2bd-4dbc-b03a-f943941a9053",
      "method": "GET"
    }
  }
}

The response output properties of the blueprint start method are described in the following table.

Property Sub Property Description/Comments
name   The name of the sandbox. (string)
id   The ID of the sandbox. (string)
state   The current state of the sandbox. Possible values: Pending, BeforeSetup, Setup, Ready, Teardown, Error, Ended. (string)
type   The sandbox type ("Sandbox"). (string)
components   The resource model of the sandbox. (array)
  id Component's unique ID. (string)
  name The name of the component. (string)
  description A short description of the resource.
  type The component ("resource", "application", or "service"). (string)
  component_
type 		The resource model. (string)
  attributes The attributes of the resource model.
(array)
  type The attribute type. (string)
  name The attribute name. (string)
  value The attribute value. (string)
  connection_
interfaces 		The connection interfaces of the resource.
(array)
  name The name of the connection interface.
(string)
  url The URL of the connection interface of the resource. (string)
  app_lifecycle (Available for App components) The current state of the App ("undeployed"/"deployed"). (string)
  _links The actions that can be performed on the sandbox component (Get component details).
_links   The actions that can be performed on the sandbox in the user's domain:
  self Provides a link to get the details for the sandbox via a GET request.
  components Provides a link to get all components in the sandbox via a GET request.
  stop Provides a link to get stop the sandbox via a POST request.
  all Provides a link to get all available sandboxes according to the user's domain via a GET request.
parameters   Published inputs and additional info.
permitted_users   Users permitted to use the sandbox, including the owner.

sandboxes

Description

Gets a list of all the running and pending sandboxes (regular and persistent sandboxes) associated with the user's domain, as well as each sandbox's details, including the sandbox ID and the available actions that can be performed on it. It can also show completed sandboxes related to the user's domain.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes

HTTP method

GET

Request

Example header format for the sandboxes method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Note: To also include completed sandboxes in the response, add the parameter show_historic to the request URL:

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes?show_historic=true

The default value for this parameter is false.

Response

The sandboxes method returns a list of all the sandboxes and the actions that can be performed on each sandbox.

[
   {
      "name":"Test Blprnt2",
      "id":"11491c80-6f79-4e9c-b592-78242c6dc698",
      "description":"This is a list of sandboxes in this user domain",
      "state":"Ready",
      "blueprint":{
         "name":"Test Blprnt2""id":"2f4c972b-5c64-4b08-bae4-73408d7b171d"
      }"_links":{
         "self":{
            "href":"/sandboxes/11491c80-6f79-4e9c-b592-78242c6dc698",
            "method":"GET""</code><MadCap":"conditionalText MadCap":"conditions=""REST-API.REST API&#160;V1"">""name":"get a sandbox' details",
            "templated":"true</code></MadCap":"conditionalText><code class=""language-javascript"">"
         },
         "</code><MadCap":"conditionalText MadCap":"conditions=""REST-API.REST API&#160;V2"">""components":{
            "href":"/sandboxes/11491c80-6f79-4e9c-b592-78242c6dc698/components",
            "method":"GET""</code></MadCap":"conditionalText>"
         },
         "stop":{
            "href":"/sandboxes/11491c80-6f79-4e9c-b592-78242c6dc698/stop",
            "method":"POST""</code><MadCap":"conditionalText MadCap":"conditions=""REST-API.REST API&#160;V1"">""name":"stop a sandbox",
            "templated":"true</code></MadCap":"conditionalText>"
         },
         "all":{
            "href":"/sandboxes",
            "method":"GET""</code></pre><pre xml":"space=""preserve"">""name":"get all sandboxes"
         }
      }
   }
]

The response output properties of the sandboxes method are described in the following table.

Property Sub Property Description/Comments
name   The name of the sandbox. (string)
id   The ID of the sandbox. (string)
description   A text description of the sandbox. (string)
state   The current state of the sandbox. Possible values: Pending, Setup, Ready, Teardown, Error, Ended. (string)
blueprint   The details of the sandbox's blueprint (Array)
  name The name of the blueprint (string)
  id The id of the blueprint (string)
_links   The actions that can be performed on a sandbox in the user's domain:
  self Provides a link to get a specific sandbox's details per specified sandbox ID via a GET request.
  components Provides a link to get all components in a sandbox per specified sandbox ID, via a GET request.
  stop Provides a link to end an active sandbox per specified sandbox ID via a POST request.
  all Provides a link to get all available sandboxes according to the user's domain via a GET request.

sandbox identifier

Description

Gets details and available actions for a particular sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).

Example header format for the sandbox identifier method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox identifier method returns details about a particular sandbox (as opposed to multiple ones). The output includes details about the sandbox ID and the actions that can be performed on the sandbox:

{
   "name":"Test Blprnt 2",
   "id":"994bd534-740a-45f5-851f-ff452f2a17a2",
   "blueprint id":"44ec66d1-4ac8-4e4b-a3e8-c733482ea176",
   "description":"",
   "start_time":"2017-01-01T10:30:00Z",
   "end_time":"2017-01-01T12:00:00Z",
   "state":"Ready",
   "setup_stage":"Provisioning""type":"Sandbox",
   "components":[
      {
         "id":"82159835-2d95-46a9-95ec-9251963d203d",
         "name":"MyApp",
         "type":"Application",
         "component_type":"Generic App Model",
         "app_lifecycle":"undeployed",
         "_links":{
            "self":{
               "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/components/82159835-2d95-46a9-95ec-9251963d203d",
               "method":"GET"
            }
         }
      }
   ],
   "parameters":[
      {
         "name":"Param1",
         "value":""
      },
      {
         "name":"Param2",
         "value":""
      }
   ]"permitted_users":[
      {
         "john.s",
         "emily.b",
         "lucas.w"
      }
   ]"_links":{
      "self":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2",
         "method":"GET",
      },
      "components":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/components",
         "method":"GET"
      },
      "output":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/output",
         "method":"GET"
      },
      "stop":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/stop",
         "method":"POST",
      },
      "all":{
         "href":"/sandboxes",
         "method":"GET",
      }"blueprint":{
         "href":"/blueprints/44ec66d1-4ac8-4e4b-a3e8-c733482ea176",
         "method":"GET"
      }
   }
}

The response output properties of the sandbox identifier method are described in the following table.

Property Sub Property Description/Comments
name   The name of the sandbox. (string)
id   The ID of the sandbox. (string)
blueprint_id   The ID of the blueprint on which the sandbox is based.
description   A description of the sandbox (string)
start_time   The time when the sandbox started (string)
end_time   the time when the sandbox ended or is expected to end (string)
state   The current state of the sandbox. Possible values: Pending, Setup, Ready, Teardown, Error, Ended. (string)
setup_stage   (If the sandbox includes orchestration scripts) The current setup stage of the sandbox. Possible values: Provisioning, Connectivity, Configuration, Ended, None. (string)
type   The sandbox type ("Sandbox"). (string)
components   The resource model of the sandbox. (array)
  name The name of the component. (string)
  type The component ("resource", "application", or "service"). (string)
  component_
type 		The resource model. (string)
  app_lifecycle (Available for App components) The current state of the App ("undeployed"/"deployed"). (string)
  _links The actions that can be performed on the sandbox component (Get component details).
parameters   Any published input parameters defined for the sandbox's blueprint and the blueprint's resources.
  name The parameter name (string)
  value The parameter value (string)
permitted_users   Sandbox's permitted users list. Specify as a comma-separated list of the CloudShell user names.
_links   The actions that can be performed on the sandbox in the user's domain:
  self Provides a link to get the details for the sandbox via a GET request.
  components Provides a link to get all components in the sandbox via a GET request.
  output Provides a link to get all messages printed to the Output console via a GET request.
  stop Provides a link to stop the sandbox via a POST request.
  all Provides a link to get all available sandboxes according to the user's domain, via a GET request.
  blueprint Provides a link to get the details of the sandbox's blueprint via a GET request.

sandbox components

Description

Gets details about the components (resources, services, and Apps) of a particular sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).

Example header format for the sandbox components method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox components method returns details about all the components of a particular sandbox and the actions that can be performed on each component.

[
   {
      "id":"0daead01-8e57-4064-81d4-84911effa933",
      "name":"MyApp",
      "type":"Application",
      "component_type":"Generic App Model",
      "description":"",
      "active_deployment_name":"",
      "template_name":"",
      "app_lifecycle":"undeployed""attributes":[
         {
            "type":"string",
            "name":"user",
            "value":""
         }
      ],
      "connection_interfaces":[
         {
            "name":"SSH",
            "url":""
         }
      ]"_links":{
         "self":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933",
            "method":"GET"
         }
      }
   }{
      "id":"0daead01-8e57-4064-81d4-84911effa911",
      "name":"MySwitch",
      "type":"Resource",
      "component_type":"Generic Switch Model",
      "description":"",
      "attributes":[
         {
            "type":"string",
            "name":"vendor",
            "value":""
         }
      ],
      "connection_interfaces":[
         {
            "name":"Telnet",
            "url":""
         }
      ]"_links":{
         "self":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa911",
            "method":"GET"
         }
      }
   }
]

The response output properties of the sandbox components method are described in the following table.

Property Sub Property Description/Comments
id   The ID of the component. (string)
name   The name of the component. (string)
type   The component ("resource", "application", or "service"). (string)
component_type   The resource model. (string)
description   A short description of the component. (string)
active_deployment_name   (Available for App components) The name of the deployment path for the App. (string)
template_name   (Available for App components) The name of the App template. (string)
app_lifecycle   (Available for App components) The current state of the App ("undeployed"/"deployed"). (string)
attributes   The attributes of the resource model. (array)
  type The attribute type. (string)
  name The attribute name. (string)
  value The attribute value. (string)
connection_interfaces   The connection interfaces of the resource. (array)
  name The name of the connection interface. (string)
  url The URL of the connection interface. (string)
_links   The actions that can be performed on the component of a sandbox in the user's domain:
  self Provides a link to get the component's details via a GET request.

sandbox component id

Description

Gets details and available actions for a particular component (resource, service, or App) in a specific sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components/{component_id}

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, and the component ID from the sandbox components method and the blueprint start method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
component_id The id of the sandbox component (string).

Example header format for the sandbox component id method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox component id method returns details about a specific component of a particular sandbox, and the actions that can be performed on the component.

{
   "id":"0daead01-8e57-4064-81d4-84911effa933",
   "name":"MyApp",
   "type":"Application",
   "component_type":"Generic App Model",
   "description":"",
   "active_deployment_name":"",
   "template_name":"",
   "app_lifecycle":"undeployed""attributes":[
      {
         "type":"string",
         "name":"user",
         "value":""
      }
   ],
   "connection_interfaces":[
      {
         "name":"RDP",
         "url":""
      }
   ]"_links":{
      "self":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933",
         "method":"GET"
      },
      "commands":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933/commands",
         "method":"GET"
      }
   }
}

The response output properties of the sandbox component id method are described in the following table.

Property Sub Property Description/Comments
id   The ID of the component. (string)
name   The name of the component. (string)
type   The component ("resource", "application", or "service"). (string)
component_type   The resource model. (string)
description   A short description of the component. (string)
active_deployment_name   (Available for App components) The name of the deployment path for the App. (string)
template_name   (Available for App components) The name of the App template. (string)
app_lifecycle   (Available for App components) The current state of the App ("undeployed"/"deployed"). (string)
attributes   The attributes of the resource model. (array)
  type The attribute type. (string)
  name The attribute name. (string)
  value The attribute value. (string)
connection_ interfaces   The connection interfaces of the resource. (array)
  name The name of the connection interface. (string)
  url The URL of the connection interface of the component. (string)
_links   The actions that can be performed on the component of a sandbox in the user's domain:
  self Provides a link to get the component's details via a GET request.
  commands Provides a link to get all the resource commands for the component via a GET request.

sandbox component commands

Description

Gets details about all the commands and connected commands provided for a particular component (resource, service, or App) in a specific sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components/{component_id}/commands

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, and the component ID from the sandbox components method and the blueprint start method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
component_id The id of the sandbox component (string).

Example header format for the sandbox component commands method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox component commands method returns details about all the commands provided for a specific component of a particular sandbox and the actions that can be performed on each command.

[
   {
      "name":"my_command",
      "description":"",
      "params":[
         {
            "name":"param1",
            "description":"",
            "type":"numeric""possible values":[
               
            ],
            "default value":"""mandatory":false
         }
      ]"executions":[
         {
            "id":"0daead01-8e57-4064-81d4-84911effa911",
            "status":"Pending",
            "supports_Cancelation":"false",
            "_links":{
               
            }
         }
      ],
      "_links":{
         "self":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933/my_command",
            "method":"GET"
         },
         "start":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933/commands/my_command/start",
            "method":"POST"
         }
      }
   }

The response output properties of the sandbox component commands method are described in the following table.

Property Sub Property Description/Comments
name   The name of the command. (string)
description   A short description of the command. (string)
params   The parameters needed for the command execution. (array)
  name The parameter name. (string)
  description The parameter description. (string)
  type The parameter type ("string", "numeric", or "lookup"). (string)
  possible values All the possible values for this parameter. (array)
  default value The default value of the parameter. (string)
  mandatory Whether or not the parameter is mandatory for the command execution. (bool)
executions   The execution history for this command. (array)
  id The ID of the execution. (string)
  status The current status of the command execution ("pending", "running", "stopping", "canceled". (string)
  supports_cancellation Whether or not stopping the execution before it is completed is supported. (bool)
  _links The actions that can be performed on the execution (Get execution details, Delete execution)
_links   The actions that can be performed on a sandbox's component command in the user's domain:
  self Provides a link to get a command's details via a GET request.
  start Provides a link to start a command's execution via a POST request.
command_tag string (For connected commands only) Tag defined for the command. Options are "power" or "remote_<remote command name>"

component command name

Description

Gets details about a particular command for a specific component (resource, service, or App) in a sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components/{component_id}/commands/{command_name}

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, the component ID from the sandbox components method and the blueprint start method, and the command's name from the sandbox component commands method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
component_id The id of the sandbox component (string).
command_name The name of the component command (string).

Example header format for the component command name method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The component command name method returns details about a specific component command in a particular sandbox and the actions that can be performed on the command.

{
   "name":"my_command",
   "description":"",
   "params":[
      {
         "name":"param1",
         "description":"",
         "type":"numeric""possible values":[
            
         ],
         "default value":"""mandatory":false
      }
   ]"executions":[
      {
         "id":"0daead01-8e57-4064-81d4-84911effa911",
         "status":"Pending",
         "supports_Cancelation":"false",
         "_links":{
            "self":{
               "href":"/executions/0daead01-8e57-4064-81d4-84911effa911",
               "method":"GET"
            }"stop":{
               "href":"/executions/0daead01-8e57-4064-81d4-84911effa911",
               "method":"DELETE"
            }
         }
      }
   ],
   "_links":{
      "self":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933/commands/my-command",
         "method":"GET"
      },
      "start":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/components/0daead01-8e57-4064-81d4-84911effa933/commands/my-command/start",
         "method":"POST"
      }
   }
}

The response output properties of the component command name method are described in the following table.

Property Sub Property Description/Comments
name   The name of the command. (string)
description   A short description of the command. (string)
params   The parameters needed for the command execution. (array)
  name The parameter name. (string)
  description The parameter description. (string)
  type The parameter type ("string", "numeric", or "lookup"). (string)
  possible values All the possible values for this parameter. (array)
  default value The default value of the parameter. (string)
  mandatory Whether or not the parameter is mandatory for the command execution. (bool)
executions   The execution history for this command. (array)
  id The ID of the execution. (string)
  status The current status of the command execution ("pending", "running", "stopping", "canceled", (string)
  supports_cancellation Whether or not stopping the execution before it is completed is supported. (bool)
  _links The actions that can be performed on the execution (Get execution details, Delete execution)
_links   The actions that can be performed on the sandbox's component command in the user's domain:
  self Provides a link to get the command's details via a GET request.
  start Provides a link to get start the command's execution via a POST request.
command_tag string (For connected commands only) Tag defined for the command. Options are "power" or "remote_<remote command name>"

component command start

Description

Executes a particular command or connected command for a specific component (resource, service, or App) in a sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components/{component_id}/commands/{command_name}/start

HTTP method

POST

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, the component ID from the sandbox components method and the blueprint start method, and the command's name from the sandbox component commands method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
component_id The id of the sandbox component (string).
command_name The name of the component command (string).

Example header format for the component command start method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

The input parameters of the command in JSON format. The elements of the component command start method include.

Parameter Description/Comments
command_tag Tag defined for the connected command. Connected command tags are used to define categories of functionality.(string)

Possible values:

  • power
  • remote_<command name>: For example, "remote_save_snapshot" for vCenter VM save snapshot.

 

params

Any input parameters required for running the command must be included in the request. (array)

If you do not specify the input parameters, you will get the following error message: "No values were provided for the following mandatory inputs: {Parameter name}".
connected_ports_full_path List of connected ports to use in this operation. (array)

Include the full path from the root resource to each port, separated by slashes. For example: Switch20/Blade5/PowerPort1. Leave blank to perform the connected operation on all of the specified resource’s connected ports.
printOutput Whether or not the command output is displayed in the console or command line. (bool) 
{
   "params":[
      {
         "name":"Version",
         "value":"1.0.223.7"
      }
   ],
   "printOutput":"true/false"
}
{
  "command_tag": "power",
  "params": [
    {
      "name": "Version",
      "value": "1.0.223.7"
    }
  ],
  "connected_ports_full_path": [
    "Switch20/Blade5/PowerPort1"
  ],
  "printOutput": true
}

Response

The component command start method returns details about a specific execution of the sandbox component command. The response includes the command's execution ID and the actions that can be performed on the execution.

{
   "executionId":"1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
   "supports_cancellation":true"_links":{
      "self":{
         "href":"/execution/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"GET"
      },
      "stop":{
         "href":"/executions/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"DELETE"
      }
   }
}

The response output properties of the component command start method are described in the following table.

Property Sub Property Description/Comments
executionId   The ID of the execution. (string)
supports_cancellation   Whether or not stopping the execution before it is completed is supported. (bool)
_links   The actions that can be performed on the execution:
  self Provides a link to get a the execution's details via a GET request.
  stop Provides a link to end the execution via a DELETE request.

sandbox activity

Description

Gets the content of CloudShell Portal's Activity Feed for a particular sandbox. This displays information about actions performed in the sandbox by the user and automation process.

The maximum number of entries in the response is configured by the administrator. If this number of entries is exceeded, the response will include multiple pages. For more information, see Setting the response page size for the Sandbox API live documentation pages.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/activity?tail=100&from_event_id

HTTP method

GET

Request

URL Parameters Description/Comments
sandbox_identifier

The id of the sandbox.

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.
Query parameters

You may add the following optional parameters to the end of the method's URL to filter the number of events. For example - displaying the last 100 errors:

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/activity?tail=100&error_only=true

error_only Returns only "error" type events. (bool)
since Time from which to return all events. Time must be specified in ISO 8601 format (for example PT23H).(string)
tail

Last number of events to return. (integer)
from_event_id ID of the first event in the response page to display, which is returned in the next_event_id property of the response. (string)

Example header format for the sandbox activity method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

By default, the method's response includes all the events that occurred during the sandbox's lifecycle.

Response

The sandbox activity method returns the events from the Activity Feed of a particular sandbox. The response includes :

{
   "num_returned_events":"20",
   "more_pages":"false",
   "next_event_id":"99434",
   "events":[
      {
         "id":"82159835-2d95-46a9-95ec-9251963d203d",
         "event_type":"success",
         "event_text":"Sandbox 'MyBlueprint' has started",
         "output":"Null",
         "time":"2017-01-15T09:51:17Z"
	  "execution_server": null
      },
      {
         "id":"79549eaf-7f1a-4180-a88b-e7da27e5075b",
         "event_type":"success",
         "event_text":"'Deploy' resource command on 'vCenter VM From...' started",
         "output":"Null",
         "time":"2017-01-15T09:51:17Z"
	  "execution_server": "WIN-ES-NY"
      }
   ]
}

The response output properties of the sandbox activity method are described in the following table.

Property Sub Property Description/Comments
number_of_returned_events   The number of events in the Activity Feed that match the filter criteria in the request. (integer)
more_pages   (Relevant if the response includes multiple pages) true indicates that there are additional events that are not displayed in this response page (bool)
next_event_id   (Relevant if the response includes multiple pages) The ID of the first event on the next page of the response. (integer)

Note: To get the next page, run the method again with this value in the from_event_id input parameter.
events   The details of the Activity Feed events (array)
  id The ID of the event (string)
  event_type The type of event ("success"/"error") (string)
  event_text The text displayed in the Activity Feed for the event (string)
  output (Events related to command execution) Text displayed as output of the command (string)
  time The time in which the Activity Feed event was logged (string)

 

execution_server

Name of the execution server that executed the command. (string)

sandbox output

Description

Gets the content of CloudShell Portal's Output console for a particular ACTIVE sandbox. This displays execution information related to running blueprint and resource commands.

The maximum number of entries in the response is configured by the administrator. If this number of entries is exceeded, the response will include multiple pages. For more information, see Setting the response page size for the Sandbox API live documentation pages.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/output

HTTP method

GET

Request

URL Parameters Description/Comments
sandbox_identifier

The id of the sandbox.

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.
Query parameters

You may add the following optional parameters to the end of the method's URL to filter the number of events. For example - displaying the last 100 events:

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/activity?tail=100

tail

Last number of entries to return. (integer)
from_entry_id ID of the first entry in the response page to display, which is returned in the next_entry_id property of the response (string)
since Time from which to return all entries. Time must be specified in ISO 8601 format (for example PT23H).(string)

Example header format for the sandbox output method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

By default, the method returns all the output messages that were displayed during the sandbox's lifecycle.

Response

The sandbox output method returns the entries from the Output console of a particular sandbox. The response includes :

{
   "number_of_returned_entries":"2",
   "next_entry_id":"99434",
   "more_pages":"false",
   "entries":[
      {
         "id":"82159835-2d95-46a9-95ec-9251963d203d",
         "time":"2017-01-15T09:51:17Z",
         "text":"Beginning sandbox setup"
      },
      {
         "id":"79549eaf-7f1a-4180-a88b-e7da27e5075b",
         "time":"2017-01-15T09:51:20Z",
         "text":"Resource: \"\" is now: Online"
      }
   ],
   "_links":{
      "self":{
         "href":"/sandboxes/994bd534-740a-45f5-851f-ff452f2a17a2/output",
         "method":"GET"
      }
   }
}

The response properties of the sandbox output method are described in the following table.

Property Sub Property Description/Comments
number_of_returned_entries   The number of entries in the Output console that match the filter criteria in the request. (integer)
next_entry_id   (Relevant if the response includes multiple pages) The ID of the first entry on the next page of the response (integer)

Note: To get the next page, run the method again with this value in the from_entry_id input parameter.
more_pages   (Relevant if the response includes multiple pages) true indicates that there are additional entries that are not displayed in this response page (bool)
entries   The details of the output console entry (array)
  id The ID of the entry (string)
  time The time in which the Output entry was logged (string)
  text The text displayed in the Output console for this entry (string)
_links   The actions that can be performed on the Output console entries of a sandbox in the user's domain:
  self Provides a link to get the Output console entries for the sandbox via a GET request.

sandbox extend

Description

Extends the duration of a particular sandbox by a specified timeframe.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/extend

HTTP method

POST

Request

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.

Example header format for the sandbox extend method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

The scheduling parameter of the sandbox in JSON format. The elements of the sandbox extend method include:

Parameter Description/Comments
extended_time

The additional duration required for the sandbox. Time must be specified in ISO 8601 format (for example PT23H). (string)

If you do not specify a value, the following error message will be displayed: "Parameter is not a valid extended time". 

{
   "extended_time":"PT2H5M"
}

Response

The sandbox extend method returns details about the extended sandbox. The output includes details about the sandbox ID and the new time of the sandbox's duration:

{
   "id":"994bd534-740a-45f5-851f-ff452f2a17a2",
   "name":"Test Blprnt2",
   "start_time":"2017-01-01T10:30:00Z",
   "end_time":"2017-01-01T12:35:00Z",
   "remaining_time":"PT24H30M"
}

The response output properties of the sandbox extend method are described in the following table.

Property Sub Property Description/Comments
id   The ID of the sandbox. (string)
name   The name of the sandbox. (string)
start_time   The time when the sandbox started (string)
end_time   The time when the extended sandbox ends. (string)
remaining_time   The time left for the sandbox (string)

sandbox stop

Description

Ends a sandbox per specified sandbox ID. Returns a successful response when the sandbox is stopped.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/stop

HTTP method

POST

Request

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.

Example header format for the sandbox stop method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

A successful response is displayed when the sandbox stop method ends the sandbox:

{
   "result":"success",
   "_links":{
      "all":{
         "href":"/sandboxes",
         "method":"GET"
      }
   }
}

sandbox commands

Description

Gets details for all the blueprint commands in the sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/commands

HTTP method

GET

Request

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL.

Example header format for the sandbox commands method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox commands method returns details about the blueprint commands in a particular sandbox and the actions that can be performed on each command.

[
   {
      "name":"my_command",
      "description":"",
      "params":[
         {
            "name":"param1",
            "description":"",
            "type":"numeric""possible values":[
               
            ],
            "default value":"""mandatory":false
         }
      ]"executions":[
         {
            "id":"0daead01-8e57-4064-81d4-84911effa911",
            "status":"Pending",
            "supports_Cancelation":"false",
            "_links":{
               
            }
         }
      ],
      "_links":{
         "self":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/commands/my-command",
            "method":"GET"
         },
         "start":{
            "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/commands/my-command/start",
            "method":"POST"
         }
      }
   }
[

The response output properties of the sandbox commands method are described in the following table.

Property Sub Property Description/Comments
name   The name of the command. (string)
description   A short description of the command. (string)
params   The parameters needed for the command execution. (array)
  name The parameter name. (string)
  description The parameter description. (string)
  type The parameter type ("string", "numeric", or "lookup"). (string)
  possible values All the possible values for this parameter. (array)
  default value The default value of the parameter. (string)
  mandatory Whether or not the parameter is mandatory for the command execution. (bool)
executions   The execution history for this command. (array)
  id The ID of the execution. (string)
  status The current status of the command execution ("pending", "running", "stopping", "canceled", (string)
  supports_cancellation Whether or not stopping the execution before it is completed is supported. (bool)
  _links The actions that can be performed on the execution (Get execution details, Delete execution)
_links   The actions that can be performed on a sandbox's blueprint command in the user's domain:
  self Provides a link to get a command's details via a GET request.
  start Provides a link to get start a command's execution via a POST request.

sandbox command name

Description

Gets details about a particular blueprint command in a specific sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/commands/{command_name}

HTTP method

GET

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, and the command's name from the sandbox commands method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
command_name The name of the command (string).

Example header format for the sandbox command name method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandbox command name method returns details about a specific command for a particular sandbox and the actions that can be performed on the command.

{
   "name":"my_command",
   "description":"",
   "params":[
      {
         "name":"param1",
         "description":"",
         "type":"numeric""possible values":[
            
         ],
         "default value":"""mandatory":false
      }
   ]"executions":[
      {
         "id":"0daead01-8e57-4064-81d4-84911effa911",
         "status":"Pending",
         "supports_Cancelation":"false",
         "_links":{
            "self":{
               "href":"/executions/0daead01-8e57-4064-81d4-84911effa911",
               "method":"GET"
            }"stop":{
               "href":"/executions/0daead01-8e57-4064-81d4-84911effa911",
               "method":"DELETE"
            }
         }
      }
   ],
   "_links":{
      "self":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/commands/my-command",
         "method":"GET"
      },
      "start":{
         "href":"/sandboxes/0daead01-8e57-4064-81d4-84911effa000/commands/my-command/start",
         "method":"POST"
      }
   }
}

The response output properties of the sandbox command name method are described in the following table.

Property Sub Property Description/Comments
name   The name of the command. (string)
description   A short description of the command. (string)
params   The parameters needed for the command execution. (array)
  name The parameter name. (string)
  description The parameter description. (string)
  type The parameter type ("string", "numeric", or "lookup"). (string)
  possible values All the possible values for this parameter. (array)
  default value The default value of the parameter. (string)
  mandatory Whether or not the parameter is mandatory for the command execution. (bool)
executions   The execution history for this command. (array)
  id The ID of the execution. (string)
  status The current status of the command execution ("pending", "running", "stopping", "canceled". (string)
  supports_cancellation Whether or not stopping the execution before it is completed is supported. (bool)
  _links The actions that can be performed on the execution (Get execution details, Delete execution)
_links   The actions that can be performed on the sandbox's blueprint command in the user's domain:
  self Provides a link to get the command's details via a GET request.
  start Provides a link to start the command's execution via a POST request.

sandbox command start

Description

Executes a particular command for a specific sandbox.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/{sandbox_identifier}/components/{component_id}/commands/{command_name}/start

HTTP method

POST

Request

Note: You can get the sandbox ID from the sandboxes method, blueprint start method, and from the sandbox ID segment in the CloudShell Portal URL, the component ID from the sandbox components method and the blueprint start method, and the command's name from the sandbox component commands method.

Parameter Description/Comments
sandbox_identifier

The id of the sandbox (string).
component_id The id of the sandbox component (string).
command_name The name of the component command (string).

Example header format for the sandbox command start method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

The input parameters of the command in JSON format. The elements of the sandbox command start method include.

Parameter Description/Comments
params Any input parameters required for running the command must be included in the request. If you do not specify the input parameters, you will get the following error message: "No values were provided for the following mandatory inputs: {Parameter name}". (Array)
printOutput Whether or not the command output is displayed in the console or command line. (bool) 
{
   "params":[
      {
         "name":"string",
         "value":"string"
      }
   ]
}

Response

The sandbox command start method returns details about a specific execution of the sandbox command. The response includes the command's execution ID and the actions that can be performed on the execution.

{
   "executionId":"1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
   "supports_cancellation":true"_links":{
      "self":{
         "href":"/execution/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"GET"
      },
      "stop":{
         "href":"/executions/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"DELETE"
      }
   }
}

The response output properties of the sandbox command start method are described in the following table.

Property Sub Property Description/Comments
executionId   The ID of the execution. (string)
supports_cancellation   Whether or not stopping the execution before it is completed is supported. (bool)
_links   The actions that can be performed on the execution:
  self Provides a link to get the execution's details via a GET request.
  stop Provides a link to end the execution via a DELETE request.

execution id

Description

Gets details about a specific execution of a sandbox or component command, per specified execution ID.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/executions/{execution_id}

HTTP method

GET

Request

Parameter Description/Comments
execution_id

The id of the command's execution (string).

Note: You can get the execution ID from the component command start and the blueprint start methods.

Example header format for the execution id method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The execution id method returns details about a specific execution of a sandbox or component command and the actions that can be performed on the execution.

{
   "id":"1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
   "supports_cancellation":"true",
   "started":"""ended":"",
   "status":"",
   "output":"",
   "_links":{
      "self":{
         "href":"/executions/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"GET"
      },
      "stop":{
         "href":"/executions/1DEB29BF-22B0-4CF6-B7BE-02173520EB81",
         "method":"DELETE"
      }
   }
}

The response output properties of the execution id method are described in the following table.

Property Sub Property Description/Comments
id   The ID of the execution. (string)
supports_cancellation   Whether or not stopping the execution before it is completed is supported. (bool)
started   The date and time at which the execution started. (string)
ended   The date and time at which the execution ended. (string)
status   The current status of the command execution - "pending", "running", "stopping", "canceled". (string)
output   (If the command returns an output message) The command's output. (string)
_links   The actions that can be performed on the execution:
  self Provides a link to get the execution's details via a GET request.
  stop (If the execution supports cancellation and is still running) Provides a link to end the execution via a DELETE request.

execution stop

Description

Ends an execution of a component or sandbox command, per specified execution ID. Returns a successful response when the execution is stopped.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/executions/{execution_id}

HTTP method

DELETE

Request

Parameter Description/Comments
execution_id

The id of the command's execution (string).

Note: You can get the execution ID from the component command start and the blueprint start methods.

Example header format for the execution stop method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

A successful response is displayed when the execution stop method ends the execution:

{
"result": "success",
}


sandbox owner identifier

Description

.

URL

http://{CloudShell Sandbox API Gateway IP address}:{port#}/api/v2/sandboxes/owners/{owner_identifier}

HTTP method

GET

Request

Parameter Description/Comments
owner_identifier

The name of the user (string).

Example header format for the sandboxes method:

Authorization: Basic <authorization token returned from the login method>

Content-Type: application/json

Response

The sandboxes method returns a list of all the sandboxes and the actions that can be performed on each sandbox.

[
  {
    "name": "Sanity Testing on Latest Build",
    "id": "fa4a313a-061d-4a40-9815-9730dd7c916f",
    "description": "Blueprint with preconfigured sanity tests to be run on the latest build.",
    "state": "Ready",
    "blueprint": {
      "name": "Sanity Testing Blueprint",
      "id": "506f1880-5ba0-48ad-9385-d259edcf885b"
    }
  },
  {
    "name": "System Diagnostics Test",
    "id": "0b0747f3-b3bb-4de1-b0f0-9c15b7327bb9",
    "description": "Blueprint that automates system diagnostics checks on the local network.",
    "state": "Ready",
    "blueprint": {
      "name": "System Diagnostics Blueprint",
      "id": "07e70b79-3cba-4f1a-a957-fb4b0552fb33"
    }

The response output properties of the sandboxes method are described in the following table.

Property Sub Property Description/Comments
name   The name of the sandbox. (string)
id   The ID of the sandbox. (string)
description   A text description of the sandbox. (string)
state   The current state of the sandbox. Possible values: Pending, Setup, Ready, Teardown, Error, Ended. (string)
blueprint   The details of the sandbox's blueprint (Array)
  name The name of the blueprint (string)
  id The id of the blueprint (string)

jh