全部产品
Search
文档中心

云服务器 ECS:StartTerminalSession - 开始终端会话

更新时间:Mar 13, 2024

调用StartTerminalSession基于会话管理功能创建一个会话。您可以通过指定ECS实例ID与该实例建立一个WebSocket会话,通过接口返回的WebSocketUrl可以远程连接到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代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:StartTerminalSessionWrite
  • Instance
    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

请求参数

名称类型必填描述示例值
RegionIdstring

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

cn-hangzhou
InstanceIdarray

实例 ID 列表。

string

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

i-bp1eifrtpxa9tb****
PortNumberinteger

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

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

22
CommandLinestring

发起会话后,指定执行的命令内容。长度不能超过 512 个字符。

说明 指定了CommandLine后,不能再指定PortNumberTargetServer
ssh root@192.168.0.246
TargetServerstring

指定通过实例访问 VPC 内目标服务地址。

说明 当该参数不为空时,PortNumber表示通过托管实例访问 VPC 内目标服务的端口号。
192.168.0.246
Usernamestring

指定连接时的用户名称。

testUser

返回参数

名称类型描述示例值
object
RequestIdstring

请求 ID。

EB5173B0-8E80-564E-AAD1-3135412*****
SessionIdstring

会话 ID。

s-hz023od0x9****
SecurityTokenstring

附加在 WebSocket 的请求头部,用于系统校验本次请求。

d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrlstring

远程连接 ECS 实例的 WebSocket 会话对应的 URL。包含了会话 ID(SessionId)以及用于系统校验的SecurityToken

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

示例

正常返回示例

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

错误码

HTTP status code错误码错误信息描述
400RegionId.ApiNotSupportedThe api is not supported in this region.指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
400PortNumber.InvalidThe port number is invalid.端口号非法。
403InstanceIds.ExceedLimitThe number of instance IDs exceeds the upper limit.目标实例数量超过上限。
403SessionCount.ExceedLimitThe number of sessions exceeds the upper limit.处于连接状态的会话数量超过上限。
403Operation.ForbiddenThe operation is not permitted.该操作是不被允许的。
403PortForwarding.NotSupportedPort forwarding is not supported currently.端口转发功能暂未支持。
403UserBehavior.SessionManagerDisabledThe api is disabled by user behavior.用户通过会话管理远程连接功能已关闭。建议确保会话管理已开启(全地域)来进行远程管理。
403InvalidCommandLine.ConflictThe parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.参数CommandLine不能与参数PortNumber或TargetServer一起指定。
403InvalidTargetServer.MissingPortNumberThe parameter PortNumber must be specified with parameter TargetServer.使用参数TargetServer时必须同时指定参数PortNumber。
403InvalidCommandLine.LengthLimitExceededThe length of the parameter CommandLine exceeded the limit of 512 characters.参数CommandLine的内容长度超过了512个字符的限制。
403InvalidInstanceIds.CountLimitExceededThe count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.使用了TargetServer或CommandLine参数时,Instances的数量超过了最大限制,限制Instances数量仅为1。
403Username.ExceedLimitThe length of the username exceeds the upper limit.用户名长度超过上限。
404InvalidRegionId.NotFoundThe RegionId provided does not exist in our records.提供的RegionId不存在
404InvalidInstance.NotFoundThe specified instances not found.指定的实例ID不存在。
500InternalError.DispatchAn error occurred when you dispatched the request.发送请求时发生错误,请稍后重试。

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

变更历史

变更时间变更内容概要操作
2024-03-12OpenAPI 错误码发生变更、OpenAPI 入参发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
    删除错误码:404
    删除错误码:500
入参OpenAPI 入参发生变更
    新增入参:Username
2023-08-16OpenAPI 错误码发生变更、OpenAPI 入参发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 403 变更
    删除错误码:400
    删除错误码:404
    删除错误码:500
入参OpenAPI 入参发生变更
    新增入参:CommandLine
    新增入参:TargetServer
2023-05-12OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
    错误码 403 变更
    删除错误码:404
    删除错误码:500
2023-03-15OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
    删除错误码:403
    删除错误码:404
    删除错误码:500