Script Runtime Service for vSphere 1.0

Script Runtime Service for vSphere (SRS) enables vSphere users andservices (clients) to manage PowerCLI instances and run PowerCLI scripts. SRS clients authenticate once with vSphere credentials or access token. SRS clients can create PowerCLI instances and run scripts within. PowerCLI runs server-side and automatically connects to target vCenter servers. SRS tracks history of script outputs.

Getting Started with Script Runtime Service for vSphere (SRS) API in 5 steps

1. Obtain SRS API Key

SRS uses VC SSO as Identity and Authentication Server. SRS supports basic authentication passing username and password which are used only to acquire HoK Saml token for SRS solution. When basic is used SRS uses username and password to present them to the SSO server and exchange them for SAML token. SRS uses the SAML token to Connect PowerCLI to VC services in further operations.
On successful authentication SRS issues an API Key which authorizes further SRS API calls.

POST https://{api-host}/api/auth/login

Example basic authentication request:

curl -X POST "https://{api-host}/api/auth/login" -H "accept: \*/\*" -H "Authorization: Basic dXNlcjpwYXNzd29yZA=="

Response:

x-srs-api-key: b3133982-93ea-4f92-ba03-2e122c1e0fd8

x-srs-api-key header contains the issued authorization token which should be used to authorize the further SRS API calls

2. Create a Runspace (PowerShell instance) requesting SRS to connect PowerCLI to the target vCenter Servers

POST https://{api-host}/api/runspaces

Example:

curl -X POST "https://{api-host}/api/runspaces" -H "accept: application/json" -H "X-SRS-API-KEY: b3133982-93ea-4f92-ba03-2e122c1e0fd8" -H "Content-Type: application/json" -d "{\"name\":\"MyRunspace\",\"run_vc_connection_script\":true}"

Response:

{
  "name": "MyRunspace",
  "id": "pcli-3e21e354-e59a-4fcb-a355-0bab10908cd1",
  "state": "creating",
  "error_details": null,
  "run_vc_connection_script": true,
  "vc_connection_script_id": null,
  "creation_time": "2020-06-03T11:54:29.6271143+00:00"
}

2.1. Wait runspace to become ready.

The Runspace needs a small amount of time to become ‘Ready’. Get the Runspace and check its state.

GET https://{api-host}/api/runspaces/{id}

Example:

curl -X GET "https://{api-host}/api/runspaces/pcli-3e21e354-e59a-4fcb-a355-0bab10908cd1" -H "accept: application/json" -H "X-SRS-API-KEY: b3133982-93ea-4f92-ba03-2e122c1e0fd8"<br/>

Response:

{
  "name": "MyRunspace",
  "id": "pcli-3e21e354-e59a-4fcb-a355-0bab10908cd1",
  "state": "ready",
  "error_details": null,
  "run_vc_connection_script": true,
  "vc_connection_script_id": "51b3ee0e-8c66-49c3-a1e5-4b448024a581",
  "creation_time": "2020-06-03T11:58:07.4530423+00:00"
}

3. Request a Script Execution

POST https://{api-host}/api/script-executions

{
    "runspase_id":"<runspace id>",
    "script":"Get-VIAccount"
}

Example:

curl -X POST "https://{api-host}/api/script-executions" -H "accept: application/json" -H "X-SRS-API-KEY: b3133982-93ea-4f92-ba03-2e122c1e0fd8" -H "Content-Type: application/json" -d "{\"runspace_id\":\"pcli-3e21e354-e59a-4fcb-a355-0bab10908cd1\",\"name\":\"get vi accounts\",\"script\":\"Get-VIAccount\"}"

Response:

{
  "id": "c6927736-84db-4e53-8e72-e8d0c95dca2b",
  "name": "get vi accounts",   
  "output_objects_format": "text",
  "state": "running",
  "start_time": "2020-06-03T12:01:28.9273601+00:00"
}

4. Get the Script Execution Status

GET https://{api-host}/api/script-executions/{script-id}

Example:

curl -X GET "https://{api-host}/api/script-executions/c6927736-84db-4e53-8e72-e8d0c95dca2b" -H "accept: application/json" -H "X-SRS-API-KEY: b3133982-93ea-4f92-ba03-2e122c1e0fd8"<br/>

Response:

{
  "id": "c6927736-84db-4e53-8e72-e8d0c95dca2b",
  "runspace_id": null,
  "name": "get vi accounts",
  "script": null,
  "script_parameters": null,
  "output_objects_format": "text",
  "state": "success",
  "reason": null,
  "start_time": "2020-06-03T12:01:28.9273601+00:00",
  "end_time": "2020-06-03T12:01:29.9480608+00:00"
}

5. Get the Script Execution Output

GET https://{api-host}/api/script-executions/{script-id}/output

Example:

curl -X GET "https://{api-host}/api/script-executions/c6927736-84db-4e53-8e72-e8d0c95dca2b/output?limit=20" -H "accept: application/json" -H "X-SRS-API-KEY: b3133982-93ea-4f92-ba03-2e122c1e0fd8"

Response:

[
  "Name                 Domain               Description        Server<br/>
  ----                 ------               -----------         ------<br/>
  sshd                                      sshd PrivSep       10.23.80.118<br/>
  eam                                       eam                10.23.80.118<br/>"
]

API Categories



Feedback

Was this page helpful?