調(diào)用StartTerminalSession基于會(huì)話管理功能創(chuàng)建一個(gè)會(huì)話。您可以通過指定ECS實(shí)例ID與該實(shí)例建立一個(gè)WebSocket會(huì)話，通過接口返回的WebSocketUrl可以遠(yuǎn)程連接到ECS實(shí)例。
接口說明
當(dāng)您通過代碼定制化遠(yuǎn)程連接客戶端時(shí)，可以調(diào)用該接口獲取遠(yuǎn)程連接 ECS 實(shí)例的 WebSocketUrl。調(diào)用該接口時(shí)您需要注意：
- 指定的 ECS 實(shí)例必須處于運(yùn)行中（Running）狀態(tài)。
- 指定的 ECS 實(shí)例必須安裝了云助手 Agent。您可以調(diào)用 DescribeCloudAssistantStatus 查詢 ECS 實(shí)例是否已安裝云助手 Agent，并可以查詢云助手 Agent 的版本號(hào)。
- 如果您的 ECS 實(shí)例沒有安裝云助手 Agent，請調(diào)用 InstallCloudAssistant 安裝。
- 云助手 Agent 的版本需要高于以下版本才支持會(huì)話管理功能。如果您需要升級云助手 Agent 版本，請參見升級或禁止升級云助手 Agent。
- Linux 操作系統(tǒng)：2.2.3.256
- Windows 操作系統(tǒng)：2.1.3.256
- 成功調(diào)用該接口后，WebSocketUrl 有效時(shí)長為 10 分鐘。
- 同一地域下，已創(chuàng)建并可用的會(huì)話不能超過 1000 個(gè)，單臺(tái) ECS 實(shí)例處于連接狀態(tài)的會(huì)話不能超過 20 個(gè)。
調(diào)試
您可以在OpenAPI Explorer中直接運(yùn)行該接口，免去您計(jì)算簽名的困擾。運(yùn)行成功后，OpenAPI Explorer可以自動(dòng)生成SDK代碼示例。
授權(quán)信息
下表是API對應(yīng)的授權(quán)信息，可以在RAM權(quán)限策略語句的Action元素中使用，用來給RAM用戶或RAM角色授予調(diào)用此API的權(quán)限。具體說明如下：
- 操作：是指具體的權(quán)限點(diǎn)。
- 訪問級別：是指每個(gè)操作的訪問級別，取值為寫入（Write）、讀取（Read）或列出（List）。
- 資源類型：是指操作中支持授權(quán)的資源類型。具體說明如下：
- 對于必選的資源類型，用背景高亮的方式表示。
- 對于不支持資源級授權(quán)的操作，用
全部資源表示。
- 條件關(guān)鍵字：是指云產(chǎn)品自身定義的條件關(guān)鍵字。
- 關(guān)聯(lián)操作：是指成功執(zhí)行操作所需要的其他權(quán)限。操作者必須同時(shí)具備關(guān)聯(lián)操作的權(quán)限，操作才能成功。
| 操作 | 訪問級別 | 資源類型 | 條件關(guān)鍵字 | 關(guān)聯(lián)操作 |
|---|---|---|---|---|
| ecs:StartTerminalSession | update | *Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| 無 |
請求參數(shù)
| 名稱 | 類型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| RegionId | string | 是 | 實(shí)例所在地域 ID。您可以調(diào)用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
| InstanceId | array | 是 | 實(shí)例 ID 列表。 | |
| string | 是 | 指定的 ECS 實(shí)例 ID。N 表示可以同時(shí)指定多臺(tái) ECS 實(shí)例，最多可指定 10 臺(tái) ECS 實(shí)例。N 的取值范圍：1~10。 | i-bp1eifrtpxa9tb**** | |
| PortNumber | integer | 否 | 指定 ECS 實(shí)例的端口號(hào)，用于數(shù)據(jù)轉(zhuǎn)發(fā)。一旦設(shè)置該參數(shù)，云助手 Agent 的數(shù)據(jù)轉(zhuǎn)發(fā)會(huì)傳到指定的端口號(hào)，用于端口轉(zhuǎn)發(fā)。例如，SSH 使用 22 端口。 默認(rèn)值為空，表示不設(shè)置數(shù)據(jù)轉(zhuǎn)發(fā)的端口號(hào)。 | 22 |
| CommandLine | string | 否 | 發(fā)起會(huì)話后，指定執(zhí)行的命令內(nèi)容。長度不能超過 512 個(gè)字符。 說明
指定了 CommandLine后，不能再指定PortNumber和TargetServer。
| ssh root@192.168.0.246 |
| TargetServer | string | 否 | 指定通過實(shí)例訪問 VPC 內(nèi)目標(biāo)服務(wù)地址。 說明
當(dāng)該參數(shù)不為空時(shí)， PortNumber表示通過托管實(shí)例訪問 VPC 內(nèi)目標(biāo)服務(wù)的端口號(hào)。
| 192.168.0.246 |
| Username | string | 否 | 指定連接時(shí)的用戶名稱。 | testUser |
返回參數(shù)
示例
正常返回示例
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****"
}錯(cuò)誤碼
| HTTP status code | 錯(cuò)誤碼 | 錯(cuò)誤信息 | 描述 |
|---|---|---|---|
| 400 | RegionId.ApiNotSupported | The api is not supported in this region. | 指定地域下不支持調(diào)用 API。請檢查 RegionId 參數(shù)取值是否正確。 |
| 400 | PortNumber.Invalid | The port number is invalid. | 端口號(hào)非法。 |
| 403 | InstanceIds.ExceedLimit | The number of instance IDs exceeds the upper limit. | 目標(biāo)實(shí)例數(shù)量超過上限。 |
| 403 | SessionCount.ExceedLimit | The number of sessions exceeds the upper limit. | 處于連接狀態(tài)的會(huì)話數(shù)量超過上限。 |
| 403 | Operation.Forbidden | The operation is not permitted. | 該操作是不被允許的。 |
| 403 | PortForwarding.NotSupported | Port forwarding is not supported currently. | 端口轉(zhuǎn)發(fā)功能暫未支持。 |
| 403 | UserBehavior.SessionManagerDisabled | The api is disabled by user behavior. | 用戶通過會(huì)話管理遠(yuǎn)程連接功能已關(guān)閉。建議確保會(huì)話管理已開啟（全地域）來進(jìn)行遠(yuǎn)程管理。 |
| 403 | InvalidCommandLine.Conflict | The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine. | 參數(shù)CommandLine不能與參數(shù)PortNumber或TargetServer一起指定。 |
| 403 | InvalidTargetServer.MissingPortNumber | The parameter PortNumber must be specified with parameter TargetServer. | 使用參數(shù)TargetServer時(shí)必須同時(shí)指定參數(shù)PortNumber。 |
| 403 | InvalidCommandLine.LengthLimitExceeded | The length of the parameter CommandLine exceeded the limit of 512 characters. | 參數(shù)CommandLine的內(nèi)容長度超過了512個(gè)字符的限制。 |
| 403 | InvalidInstanceIds.CountLimitExceeded | The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified. | 使用了TargetServer或CommandLine參數(shù)時(shí)，Instances的數(shù)量超過了最大限制，限制Instances數(shù)量僅為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. | 指定的實(shí)例的安全組入方向規(guī)則不允許該操作。 |
| 403 | InvalidTargetServer.LengthLimitExceeded | The length of the parameter TargetServer exceeded the limit of 128 characters. | 參數(shù)TargetServer的長度超過了128個(gè)字符的限制。 |
| 404 | InvalidRegionId.NotFound | The RegionId provided does not exist in our records. | 提供的RegionId不存在 |
| 404 | InvalidInstance.NotFound | The specified instances not found. | 指定的實(shí)例ID不存在。 |
| 500 | InternalError.Dispatch | An error occurred when you dispatched the request. | 發(fā)送請求時(shí)發(fā)生錯(cuò)誤，請稍后重試。 |
訪問錯(cuò)誤中心查看更多錯(cuò)誤碼。
變更歷史
| 變更時(shí)間 | 變更內(nèi)容概要 | 操作 |
|---|---|---|
| 2024-12-05 | OpenAPI 描述信息更新、OpenAPI 錯(cuò)誤碼發(fā)生變更 | 查看變更詳情 |
| 2024-07-18 | OpenAPI 錯(cuò)誤碼發(fā)生變更 | 查看變更詳情 |
| 2024-04-28 | OpenAPI 錯(cuò)誤碼發(fā)生變更 | 查看變更詳情 |
| 2024-03-12 | OpenAPI 錯(cuò)誤碼發(fā)生變更、OpenAPI 入?yún)l(fā)生變更 | 查看變更詳情 |
| 2023-08-16 | OpenAPI 錯(cuò)誤碼發(fā)生變更、OpenAPI 入?yún)l(fā)生變更 | 查看變更詳情 |
| 2023-05-12 | OpenAPI 錯(cuò)誤碼發(fā)生變更 | 查看變更詳情 |
| 2023-03-15 | OpenAPI 錯(cuò)誤碼發(fā)生變更 | 查看變更詳情 |