StartTerminalSession - 云服务器 ECS

接口说明

当您通过代码定制化远程连接客户端时，可以调用该接口获取远程连接ECS实例的WebSocketUrl。调用该接口时您需要注意：

指定的ECS实例必须处于运行中（Running）状态。
指定的ECS实例必须安装了云助手Agent。您可以调用DescribeCloudAssistantStatus查询ECS实例是否已安装云助手Agent，并可以查询云助手Agent的版本号。
- 如果您的ECS实例没有安装云助手Agent，请调用InstallCloudAssistant安装。
- 云助手Agent的版本需要高于以下版本才支持会话管理功能。如果您需要升级云助手Agent版本，请参见升级或禁止升级云助手Agent。
  - Linux操作系统：2.2.3.256
  - Windows操作系统：2.1.3.256
成功调用该接口后，WebSocketUrl有效时长为10分钟。
同一地域下，已创建并可用的会话不能超过1000个，单台ECS实例处于连接状态的会话不能超过20个。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数


名称	类型	是否必选	示例值	描述
Action	String	是	StartTerminalSession	系统规定参数。取值：StartTerminalSession。
RegionId	String	是	cn-hangzhou	实例所在地域ID。您可以调用DescribeRegions查看最新的阿里云地域列表。
InstanceId.N	String	是	i-bp1eifrtpxa9tb****	指定的ECS实例ID。N表示可以同时指定多台ECS实例，最多可指定10台ECS实例。N的取值范围：1~10。
PortNumber	Integer	否	22	指定ECS实例的端口号，用于数据转发。一旦设置该参数，云助手Agent的数据转发会传到指定的端口号，用于端口转发。例如，SSH使用22端口。默认值为空，表示不设置数据转发的端口号。
CommandLine	String	否	ssh root@192.168.0.246	发起会话后，指定执行的命令内容。长度不能超过512个字符。说明指定了`CommandLine`后，不能再指定`PortNumber`和`TargetServer`。
TargetServer	String	否	192.168.0.246	指定通过实例访问VPC内目标服务地址。说明当该参数不为空时，`PortNumber`表示通过托管实例访问VPC内目标服务的端口号。

返回数据


名称	类型	示例值	描述
RequestId	String	EB5173B0-8E80-564E-AAD1-3135412*****	请求ID。
SessionId	String	s-hz023od0x9****	会话ID。
SecurityToken	String	d86c2df2-d19c-4bd8-b817-a19ef123****	附加在WebSocket的请求头部，用于系统校验本次请求。
WebSocketUrl	String	wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9**&token=d86c2df2-d19c-4bd8-b817-a19ef123**	远程连接ECS实例的WebSocket会话对应的URL。包含了会话ID（`SessionId`）以及用于系统校验的`SecurityToken`。

示例

请求示例

https://ecs.aliyuncs.com/?Action=StartTerminalSession
&RegionId=cn-hangzhou
&InstanceId.1=i-bp1eifrtpxa9tb****
&公共请求参数

正常返回示例

XML格式

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

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

JSON格式

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

{
  "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****"
}

错误码


HttpCode	错误码	错误信息	描述
400	RegionId.ApiNotSupported	The api is not supported in this region.	指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
400	PortNumber.Invalid	The port number is invalid.	端口号非法。
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	目标实例数量超过上限。
403	SessionCount.ExceedLimit	The number of sessions exceeds the upper limit.	处于连接状态的会话数量超过上限。
403	Operation.Forbidden	The operation is not permitted.	该操作是不被允许的。
403	PortForwarding.NotSupported	Port forwarding is not supported currently.	端口转发功能暂未支持。
403	UserBehavior.SessionManagerDisabled	The api is disabled by user behavior.	用户通过会话管理远程连接功能已关闭。建议确保会话管理已开启（全地域）来进行远程管理。
403	InvalidCommandLine.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.	参数CommandLine不能与参数PortNumber或TargetServer一起指定。
403	InvalidTargetServer.MissingPortNumber	The parameter PortNumber must be specified with parameter TargetServer.	使用参数TargetServer时必须同时指定参数PortNumber。
403	InvalidCommandLine.LengthLimitExceeded	The length of the parameter CommandLine exceeded the limit of 512 characters.	参数CommandLine的内容长度超过了512个字符的限制。
403	InvalidInstanceIds.CountLimitExceeded	The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.	使用了TargetServer或CommandLine参数时，Instances的数量超过了最大限制，限制Instances数量仅为1。
404	InvalidInstance.NotFound	The specified instances not found.	指定的实例ID不存在。
500	InternalError.Dispatch	An error occurred when you dispatched the request.	发送请求时发生错误，请稍后重试。

访问错误中心查看更多错误码。