StartTerminalSession - Elastic Compute Service - Alibaba Cloud ドキュメントセンター

StartTerminalSession を呼び出して、セッション管理の特徴に基づく会話を作成します。インスタンス ID を指定することで、ECS インスタンスとの WebSocket 会話を確立できます。この操作によって返される WebSocketUrl を使用して、ECS インスタンスへのリモート接続を確立できます。

操作説明

操作の説明

コードを使用してリモート接続クライアントをカスタマイズする場合、この操作を呼び出して ECS インスタンスへのリモート接続を確立するための WebSocketUrl を取得できます。以下の項目に注意してください。

指定する ECS インスタンスは実行中状態である必要があります。
指定する ECS インスタンスにクラウドアシスタントエージェントがインストールされている必要があります。 DescribeCloudAssistantStatus を呼び出して、ECS インスタンスにクラウドアシスタントエージェントがインストールされているかどうかを確認し、クラウドアシスタントエージェントのバージョン番号をクエリできます。
- ECS インスタンスにクラウドアシスタントエージェントがインストールされていない場合は、 InstallCloudAssistant を呼び出してインストールします。
- 会話管理の特徴をサポートするには、クラウドアシスタントエージェントが以下のバージョンより新しい必要があります。クラウドアシスタントエージェントをスペックアップするには、「クラウドアシスタントエージェントのスペックアップまたはスペックアップの無効化」を参照してください。
  - Linux オペレーティングシステム: 2.2.3.256
  - Windows オペレーティングシステム: 2.1.3.256
この操作が呼び出された後、WebSocketUrl は 10 分間有効です。
会話が確立された後、3 分間データが送信されない場合、クラウドアシスタントによって接続がシャットダウンされます。
単一のリージョンでは、最大 100 個の会話を作成してアクティブな状態にできます。単一の ECS インスタンスに対して、接続状態にできる会話の最大数は 20 です。単一の会話接続の帯域幅制限は 200 KB/s です。
ポートフォワーディングの特徴は TCP ポートフォワーディングのみをサポートしています。UDP はサポートされていません。
会話を完全に閉じて WebSocketUrl を無効にするには、EndTerminalSession 操作を呼び出します。

今すぐお試しください

この API を OpenAPI Explorer でお試しください。手作業による署名は必要ありません。呼び出しに成功すると、入力したパラメーターに基づき、資格情報が組み込まれた SDK コードが自動的に生成されます。このコードをダウンロードしてローカルで使用できます。

テスト

RAM 認証

下表に、この API を呼び出すために必要な認証情報を示します。認証情報は、RAM (Resource Access Management) ポリシーを使用して定義できます。以下で各列名について説明します。

アクション：特定のリソースに対して実行可能な操作。ポリシー構文ではAction要素として指定します。
API：アクションを具体的に実行するための API。
アクセスレベル：各 API に対して事前定義されているアクセスの種類。有効な値：create、list、get、update、delete。
リソースタイプ：アクションが作用するリソースの種類。リソースレベルでの権限をサポートするかどうかを示すことができます。ポリシーの有効性を確保するため、アクションの対象として適切なリソースを指定してください。
- リソースレベルの権限を持つ API の場合、必要なリソースタイプはアスタリスク (*) でマークされます。ポリシーのResource要素で対応する ARN を指定してください。
- リソースレベルの権限を持たない API の場合、「すべてのリソース」と表示され、ポリシーのResource要素でアスタリスク (*) でマークされます。
条件キー：サービスによって定義された条件のキー。このキーにより、きめ細やかなアクセス制御が可能になります。この制御は、アクション単体に適用することも、特定のリソースに対するアクションに適用することもできます。Alibaba Cloud は、サービス固有の条件キーに加えて、すべての RAM 統合サービスに適用可能な一連の共通条件キーを提供しています。
依存アクション：ある特定のアクションを実行するために、前提として実行が必要となる他のアクション。依存アクションの権限も RAM ユーザーまたは RAM ロールに付与する必要があります。

アクション

アクセスレベル

リソースタイプ

条件キー

依存アクション

ecs:StartTerminalSession

update

*Instance。

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

ecs:SessionStartAs

なし

リクエストパラメーター

パラメーター	型	必須 / 任意	説明	例
RegionId	string	必須	インスタンスのリージョン ID。 DescribeRegions を呼び出して、最新のリージョンリストをクエリできます。	cn-hangzhou
InstanceId	array	必須	インスタンス ID のリスト。
	string	任意	指定された ECS インスタンスのインスタンス ID。N は、一度に複数の ECS インスタンスを指定できることを示します。最大 1 個の ECS インスタンスを指定できます。N の有効な値: 1。	i-bp1eifrtpxa9tb****
PortNumber	integer	任意	データ転送用の ECS インスタンスのポート番号。このパラメーターが設定されると、クラウドアシスタントエージェントはポートフォワーディングのために指定されたポートにデータを転送します。たとえば、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 インスタンスで会話マネージャーを使用する際のユーザーのパスワード名。名前の長さは最大 255 文字です。 Windows インスタンスで会話マネージャーをデフォルト以外のユーザー (System) として使用する場合、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*****
SecurityToken	string	リクエストのシステム検証のために WebSocket リクエストヘッダーに追加されるセキュリティトークン。	d86c2df2-d19c-4bd8-b817-a19ef123****
SessionId	string	会話 ID。	s-hz023od0x9****
WebSocketUrl	string	ECS インスタンスへのリモート接続を確立するための WebSocket 会話の URL。URL には、会話 ID (SessionId) とシステム検証に使用される SecurityToken が含まれています。	wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9**&token=d86c2df2-d19c-4bd8-b817-a19ef123**

例

成功レスポンス

JSONJSON

{
  "RequestId": "EB5173B0-8E80-564E-AAD1-3135412*****",
  "SecurityToken": "d86c2df2-d19c-4bd8-b817-a19ef123****",
  "SessionId": "s-hz023od0x9****",
  "WebSocketUrl": "wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****"
}

エラーコード

HTTP ステータスコード	エラーコード	エラーメッセージ	説明
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	InvalidParameterCharacter	The specified parameter %s contains illegal characters.
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 パラメーターを使用する場合、インスタンス数が最大値を超えています。許可されるインスタンスは 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.	リクエストパラメーターが、同じ ClientToken を持つリクエストと一致しません。
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	直前の冪等リクエストはまだ処理中です。しばらくしてからもう一度お試しください。
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	指定された RegionId は存在しません。このリージョンでプロダクトが利用可能かどうかを確認してください。
404	InvalidInstance.NotFound	The specified instances not found.	指定されたインスタンスが存在しません。

完全なリストについては、「エラーコード」をご参照ください。

変更履歴

完全なリストについては、「変更履歴」をご参照ください。