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 for the instance. The URL of the WebSocket session returned by the operation can be used to connect to the instance.
Operation description
The session management feature is in public preview. To use this feature, log on to the ECS console with your Alibaba Cloud account and enable this feature.
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 is used to connect to the instance. Take note of the following items:
-
The ECS instance must be in the Running (Running) state.
-
Cloud Assistant Agent must be installed on the ECS instance. You can call the DescribeCloudAssistantStatus operation to check whether Cloud Assistant Agent is installed on the ECS instance and query the version number of the installed Cloud Assistant Agent.
-
If Cloud Assistant Agent is not installed on the ECS instance, call the InstallCloudAssistant operation to install Cloud Assistant Agent.
-
Only the Cloud Assistant Agent versions that are later than the following ones support the session management feature. You can upgrade Cloud Assistant Agent. For information about how to upgrade Cloud Assistant Agent, see Update or disable updates for Cloud Assistant Agent.
- 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
Authorization information
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
RegionId | string | Yes | The region ID. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
InstanceId | array | Yes | The instance IDs. | |
string | Yes | The ID of instance N. You can specify up to 10 instance IDs in a single request. Valid values of N: 1 to 10. | i-bp1eifrtpxa9tb**** | |
PortNumber | integer | No | The port number of the instance. The port is used to forward data. After this parameter is configured, Cloud Assistant Agent forwards data to the specified port for forwarding. Example: 22. This parameter is empty by default, which indicates that no port is configured to forward data. | 22 |
CommandLine | string | No | If you set this parameter to the IP address of an instance, the PortNumber parameter specifies the port number of the instance. Note
If you specify CommandLine , you do not need to specify PortNumber or TargetServer .
| ssh root@192.168.0.246 |
TargetServer | string | No | The IP address of the instance. Note
If you set this parameter to the IP address of an instance, the PortNumber parameter specifies the port number of the instance.
| 192.168.0.246 |
Response parameters
Examples
Sample success responses
JSON
format
{
"RequestId": "EB5173B0-8E80-564E-AAD1-3135412*****",
"SessionId": "s-hz023od0x9****",
"SecurityToken": "d86c2df2-d19c-4bd8-b817-a19ef123****",
"WebSocketUrl": "wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | RegionId.ApiNotSupported | The api is not supported in this region. | The API operation cannot be called in the specified region. Check whether the specified RegionId parameter is valid. |
400 | PortNumber.Invalid | The port number is invalid. | The port number is invalid. |
403 | InstanceIds.ExceedLimit | The number of instance IDs exceeds the upper limit. | The number of specified instance IDs exceeds the upper limit. |
403 | SessionCount.ExceedLimit | The number of sessions exceeds the upper limit. | The number of sessions in the connected state exceeds the upper limit. |
403 | Operation.Forbidden | The operation is not permitted. | The operation is not supported. |
403 | PortForwarding.NotSupported | Port forwarding is not supported currently. | Port forwarding is not supported. |
403 | UserBehavior.SessionManagerDisabled | The api is disabled by user behavior. | - |
403 | InvalidCommandLine.Conflict | The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine. | - |
403 | InvalidTargetServer.MissingPortNumber | The parameter PortNumber must be specified with parameter TargetServer. | - |
403 | InvalidCommandLine.LengthLimitExceeded | The length of the parameter CommandLine exceeded the limit of 512 characters. | - |
403 | InvalidInstanceIds.CountLimitExceeded | The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified. | - |
404 | InvalidRegionId.NotFound | The RegionId provided does not exist in our records. | The RegionId provided does not exist |
404 | InvalidInstance.NotFound | The specified instances not found. | The specified instance ID does not exist. |
500 | InternalError.Dispatch | An error occurred when you dispatched the request. | An error occurred while the request is being sent. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2024-03-12 | The Error code has changed. The request parameters of the API has changed | see changesets | ||||||||||||||||
| ||||||||||||||||||
2023-08-16 | The Error code has changed. The request parameters of the API has changed | see changesets | ||||||||||||||||
| ||||||||||||||||||
2023-05-12 | The Error code has changed | see changesets | ||||||||||||||||
| ||||||||||||||||||
2023-03-15 | The Error code has changed | see changesets | ||||||||||||||||
|