Creates a session by using the session management feature. When you call this operation, you can include the ID of an Elastic Compute Service (ECS) instance in the request to create a WebSocket session to the instance. The URL of the WebSocket session returned by the operation can be used to connect to the instance.

Description

The session management feature is currently in invitational preview. To use this feature, submit a ticket.

When you use custom code to connect to an ECS instance that serves as a client, you can call this operation to obtain the WebSocket URL that can be used to connect to the instance. When you call this operation to create a session to an ECS instance, take note of the following items:

  • The ECS instance must be in the Running (Running) state.
  • The Cloud Assistant client must be installed on the ECS instance. You can call the DescribeCloudAssistantStatus operation to check whether the Cloud Assistant client is installed on the ECS instance and query the version number of the installed Cloud Assistant client.
    • If the Cloud Assistant client is not installed on the ECS instance, call the InstallCloudAssistant operation to install the client.
    • Only the Cloud Assistant client versions that are later than the following ones support the session management feature. You can upgrade your Cloud Assistant client. For information about how to upgrade the Cloud Assistant client, see Update or disable updates for the Cloud Assistant client.
      • For Linux operating systems: 2.2.3.256
      • For Windows operating systems: 2.1.3.256
  • Each WebSocket URL returned by the StartTerminalSession operation remains valid for 10 minutes.
  • Up to 1,000 sessions can be created and available per region. Each ECS instance can have up to 10 sessions in the connected state.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes StartTerminalSession

The operation that you want to perform. Set the value to StartTerminalSession.

RegionId String Yes cn-hangzhou

The region ID of the ECS instance. You can call the DescribeRegions operation to query the most recent region list.

PortNumber Integer No 22

The port number of the ECS instance, which is used to forward data. After this parameter is specified, the Cloud Assistant client forwards data to the specified port for port forwarding. Example: 22.

This parameter is empty by default, which indicates that no port number is configured to forward data.

InstanceId.N String Yes i-bp1eifrtpxa9tb****

The IDs of ECS instances. Valid values of N: 1 to 10.

Response parameters

Parameter Type Example Description
RequestId String EB5173B0-8E80-564E-AAD1-31354123DCF4

The ID of the request.

SessionId String s-hz023od0x9****

The ID of the session.

SecurityToken String d86c2df2-d19c-4bd8-b817-a19ef123****

The security token included in the WebSocket request header. The system uses this token to authenticate the request.

WebSocketUrl String wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****

The URL of the WebSocket session that was created to the ECS instance. The URL includes the session ID (SessionId) and the authentication token (SecurityToken).

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=StartTerminalSession
&RegionId=cn-hangzhou
&InstanceId.1=i-bp1eifrtpxa9tb****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<StartTerminalSessionResponse>
    <SecurityToken>d86c2df2-d19c-4bd8-b817-a19ef123****</SecurityToken>
    <RequestId>EB5173B0-8E80-564E-AAD1-31354123DCF4</RequestId>
    <WebSocketUrl>wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&amp;token=d86c2df2-d19c-4bd8-b817-a19ef123****</WebSocketUrl>
    <SessionId>s-hz023od0x9****</SessionId>
</StartTerminalSessionResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "SecurityToken" : "d86c2df2-d19c-4bd8-b817-a19ef123****",
  "RequestId" : "EB5173B0-8E80-564E-AAD1-31354123DCF4",
  "WebSocketUrl" : "wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****",
  "SessionId" : "s-hz023od0x9****"
}

Error codes

HTTP status code Error code Error message Description
400 RegionId.ApiNotSupported The api is not supported in this region. The error message returned because the API operation cannot be called in the specified region. Check whether the RegionId parameter is valid.
403 InstanceIds.ExceedLimit The number of instance IDs exceeds the upper limit. The error message returned because more than 10 ECS instance IDs are specified.
404 Operation.Forbidden The operation is not permitted. The error message returned because the operation is not supported.
500 InternalError.Dispatch An error occurred when you dispatched the request. The error message returned because an error occurred when the request was being sent. Try again later.

For a list of error codes, visit the API Error Center.