调用StartTerminalSession基于会话管理功能创建一个会话。您可以通过指定ECS实例ID与该实例建立一个WebSocket会话,通过接口返回的WebSocketUrl可以远程连接到ECS实例。

接口说明

会话管理功能正在邀测中,如需使用请提交工单

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

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

调试

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

请求参数

名称 类型 是否必选 示例值 描述
Action String StartTerminalSession

系统规定参数。取值:StartTerminalSession

RegionId String cn-hangzhou

实例所在地域ID。您可以调用DescribeRegions查看最新的阿里云地域列表。

PortNumber Integer 22

指定ECS实例的端口号,用于数据转发。一旦设置该参数,云助手客户端的数据转发会传到指定的端口号,用于端口转发。例如,SSH使用22端口。

默认值为空,表示不设置数据转发的端口号。

InstanceId.N String i-bp1eifrtpxa9tb****

指定的ECS实例ID。N表示可以同时指定多台ECS实例,最多可指定10台ECS实例。N的取值范围:1~10

返回数据

名称 类型 示例值 描述
RequestId String EB5173B0-8E80-564E-AAD1-31354123DCF4

请求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>
    <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格式

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

错误码

HttpCode 错误码 错误信息 描述
400 RegionId.ApiNotSupported The api is not supported in this region. 指定地域下不支持调用API。请检查RegionId参数取值是否正确。
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. 该操作是不被允许的
404 InvalidInstance.NotFound The specified instances not found. 指定的实例ID不存在。
500 InternalError.Dispatch An error occurred when you dispatched the request. 发送请求时发生错误,请稍后重试。

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