StartTerminalSession - 开始终端会话-专有宿主机(DDH)-阿里云帮助中心

调用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 分钟。
在会话建立后，3 分钟没有数据传输，云助手会关闭链接。
同一地域下，已创建并可用的会话不能超过 1000 个，单台 ECS 实例处于连接状态的会话不能超过 20 个，单个会话连接的带宽限制为 200kb/s。
端口转发功能，目前只支持 TCP 端口转发，不支持 UDP。
若想永久关闭会话，并使 WebSocketUrl 失效，请调用 EndTerminalSession 接口。

调试

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

调试

授权信息

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

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ecs:StartTerminalSession

update

*Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	实例所在地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
RegionId	string	是	实例所在地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
InstanceId	array	是	实例 ID 列表。
	string	否	指定的 ECS 实例 ID。N 表示可以同时指定多台 ECS 实例，最多可指定 10 台 ECS 实例。N 的取值范围：1~10。	i-bp1eifrtpxa9tb****
PortNumber	integer	否	指定 ECS 实例的端口号，用于数据转发。一旦设置该参数，云助手 Agent 的数据转发会传到指定的端口号，用于端口转发。例如，SSH 使用 22 端口。默认值为空，表示不设置数据转发的端口号。	22
CommandLine	string	否	发起会话后，指定执行的命令内容。长度不能超过 512 个字符。说明指定了`CommandLine`后，不能再指定`PortNumber`和`TargetServer`。	ssh root@192.168.0.246
TargetServer	string	否	指定通过实例访问 VPC 内目标服务地址。说明当该参数不为空时，`PortNumber`表示通过托管实例访问 VPC 内目标服务的端口号。	192.168.0.246
Username	string	否	指定连接时的用户名称。	testUser
ConnectionType	string	否	远程连接实例所需 WebSocket URL 的网络类型。 Internet：公网（默认） Intranet：内网。	Intranet
PasswordName	string	否	在 Windows 实例中使用 Session Manager 时用户的密码名称。长度不得超过 255 个字符。当您希望以非默认用户（System）在 Windows 实例中使用 Session Manager 时，需要同时传入 Username 和该参数。为降低密码泄露的风险，需要将密码明文托管在系统运维管理的参数仓库中，此处仅传入密码的名称。更多信息，请参见加密参数。	axtSecretPassword
ClientToken	string	否	保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。	123e4567-e89b-12d3-a456-426655440000
EncryptionOptions	object	否	会话加密配置项。
Enabled	boolean	否	开启会话连接端到端加密。	true
KMSKeyId	string	否	KMS 秘钥 ID。注意事项：仅支持 KMS 对称密钥。仅当加密模式为 Kms 时，支持指定该参数。	xxx
Mode	string	否	加密模式。可选值： Auto：使用自动协商密钥加密会话。 Kms：使用 KMS 密钥加密会话。默认值：Auto。注意事项：仅当开启会话加密时，支持指定该参数。	Auto

返回参数

名称	类型	描述	示例值
	object
RequestId	string	请求 ID。	EB5173B0-8E80-564E-AAD1-3135412*****
SessionId	string	会话 ID。	s-hz023od0x9****
SecurityToken	string	附加在 WebSocket 的请求头部，用于系统校验本次请求。	d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrl	string	远程连接 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	错误码	错误信息	描述
400	RegionId.ApiNotSupported	The api is not supported in this region.	指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
400	PortNumber.Invalid	The port number is invalid.
400	InvalidParameter.ConnectionType	The specified parameter ConnectionType is not valid.	指定的参数ConnectionType不合法。
400	InvalidClientToken.Malformed	The specified parameter clientToken is not valid.	指定的幂等参数不合法。
500	InternalError.Dispatch	An error occurred when you dispatched the request.	发送请求时发生错误，请稍后重试。
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。
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	用户名长度超过上限。
403	InvalidOperation.SecurityGroupRuleDenied	The operation is not allowed by the security group inbound rules of the specified instance.	指定的实例的安全组入方向规则不允许该操作。
403	InvalidTargetServer.LengthLimitExceeded	The length of the parameter TargetServer exceeded the limit of 128 characters.	参数TargetServer的长度超过了128个字符的限制。
403	InvalidOperation.ConnectionTypeUnsupported	The operation is not supported for the parameter ConnectionType.	指定的参数ConnectionType不支持该操作。
403	InvalidPasswordName.LengthLimitExceeded	The length of the parameter PasswordName exceeds the limit of 255 characters.
403	InvalidEncryptionOptionsMode.EncryptionDisabled	EncryptionOptions.Mode cannot be specified when encryption is disabled.	当会话加密未开启时，无法指定参数 EncryptionOptions.Mode。
403	InvalidParameter.EncryptionOptionsKMSKeyId	The specified parameter EncryptionOptions.KMSKeyId is not valid.	指定的参数EncryptionOptions.KMSKeyId 不合法。
403	InvalidParameter.EncryptionOptionsMode	The specified parameter EncryptionOptions.Mode is not valid.	指定的参数 EncryptionOptions.Mode 不合法。
403	MissingParameter.EncryptionOptionsKMSKeyId	The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied.	参数 EncryptionOptions.KMSKeyId 不能为空。
403	UnsupportedAgentVersion.Encryption	The cloud assistant agent version on instance %s do not support encryption.
403	InvalidEncryptionOptions.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter EncryptionOptions.	开启会话加密时，不允许指定参数PortNumber或TargetServer。
403	IdempotentParameterMismatch	The specified parameter has changed while using an already used clientToken.	指定的客户令牌已经被使用。
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	先前的幂等请求仍在处理中，请稍后重试。
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	地域信息错误
404	InvalidInstance.NotFound	The specified instances not found.	指定的实例ID不存在。

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

变更历史

更多信息，参考变更详情。