StartTerminalSession - Elastic Compute Service

呼叫 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 分鐘沒有資料傳輸，雲端助手會關閉連線。
同一地域下，已建立並可用的工作階段不能超過 100 個，單台 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
InstanceId	array	是	執行個體所在地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲地域列表。
	string	否	指定的 ECS 執行個體 ID。N 表示可以同時指定多台 ECS 執行個體，最多可指定 1 台 ECS 執行個體。N 的取值範圍：1。	i-bp1eifrtpxa9tb****
PortNumber	integer	否	執行個體 ID 列表。	22
CommandLine	string	否	指定 ECS 執行個體的連接埠號，用於資料轉發。一旦設定該參數，雲端助手 Agent 的資料轉發會傳到指定的連接埠號，用於連接埠轉發。例如，SSH 使用 22 連接埠。預設值為空，表示不設定資料轉發的連接埠號。	ssh root@192.168.0.246
TargetServer	string	否	發起工作階段後，指定執行的命令內容。長度不能超過 512 個字元。說明指定了 `CommandLine` 後，不能再指定 `PortNumber` 和 `TargetServer`。	192.168.0.246
Username	string	否	指定透過執行個體存取 VPC 內目標服務位址。說明當該參數不為空時，`PortNumber` 表示透過託管執行個體存取 VPC 內目標服務的連接埠號。	testUser
ConnectionType	string	否	指定連線時的使用者名稱。	Intranet
PasswordName	string	否	遠端連線執行個體所需 WebSocket URL 的網路類型。 Internet：公網（預設） Intranet：內網。	axtSecretPassword
ClientToken	string	否	在 Windows 執行個體中使用 Session Manager 時使用者的密碼名稱。長度不得超過 255 個字元。當您希望以非預設使用者（System）在 Windows 執行個體中使用 Session Manager 時，需要同時傳入 Username 和該參數。為降低密碼洩露的風險，需要將密碼明文託管在系統維運管理的參數倉庫中，此處僅傳入密碼的名稱。更多資訊，請參見加密參數。	123e4567-e89b-12d3-a456-426655440000
EncryptionOptions	object	否	保證請求冪等性。從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 只支援 ASCII 字元，且不能超過 64 個字元。更多資訊，請參見如何保證冪等性。
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.
400	PortNumber.Invalid	The port number is invalid.
400	InvalidParameter.ConnectionType	The specified parameter ConnectionType is not valid.
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.
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.
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.
403	InvalidOperation.ConnectionTypeUnsupported	The operation is not supported for the parameter 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.
403	InvalidParameter.EncryptionOptionsKMSKeyId	The specified parameter EncryptionOptions.KMSKeyId is not valid.
403	InvalidParameter.EncryptionOptionsMode	The specified parameter EncryptionOptions.Mode is not valid.
403	MissingParameter.EncryptionOptionsKMSKeyId	The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied.
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.
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.

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。