Tüm Ürünler
Search

Bu Ürün

    :StartTerminalSession

    Belge Merkezi

    :StartTerminalSession

    Son Güncelleme:Oct 02, 2026

    Oturum yönetimi özelliğine dayalı bir oturum oluşturmak için StartTerminalSession işlemini çağırır. Örnek kimliğini belirterek bir ECS örneği ile WebSocket oturumu kurabilirsiniz. Bu işlem tarafından döndürülen WebSocketUrl, ECS örneğine uzak bağlantı kurmanızı sağlar.

    Operation description

    İşlem açıklaması

    Kod kullanarak bir uzak bağlantı istemcisini özelleştirdiğinizde, bir ECS örneğine uzak bağlantı kurmak için WebSocketUrl adresini almak üzere bu işlemi çağırabilirsiniz. Aşağıdaki hususlara dikkat edin:

    • Belirtilen ECS örneği Çalışıyor (Running) durumunda olmalıdır.

    • Belirtilen ECS örneğinde Cloud Assistant Agent yüklü olmalıdır. Cloud Assistant Agent'ın ECS örneğine yüklü olup olmadığını kontrol etmek ve Cloud Assistant Agent sürüm numarasını sorgulamak için DescribeCloudAssistantStatus işlemini çağırabilirsiniz.

    • Bu işlem çağrıldıktan sonra, WebSocketUrl 10 dakika boyunca geçerlidir.

    • Bir oturum kurulduktan sonra, 3 dakika boyunca hiçbir veri iletilmezse Cloud Assistant bağlantıyı kapatır.

    • Tek bir bölgede en fazla 100 oturum oluşturulabilir ve etkin olabilir. Tek bir ECS örneği için en fazla 20 oturum bağlı durumunda olabilir. Tek bir oturum bağlantısı için bant genişliği sınırı 200 KB/s'dir.

    • Bağlantı noktası yönlendirme özelliği yalnızca TCP bağlantı noktası yönlendirmesini destekler. UDP desteklenmez.

    • Bir oturumu kalıcı olarak kapatmak ve WebSocketUrl'yi geçersiz kılmak için EndTerminalSession işlemini çağırın.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecs:StartTerminalSession

    update

    *Instance

    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
    • ecs:SessionStartAs
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    Örneğin bölge kimliği. En son bölge listesini sorgulamak için DescribeRegions işlemini çağırabilirsiniz.

    cn-hangzhou
    RegionId

    string

    Yes

    Örnek kimliklerinin listesi.

    cn-hangzhou
    InstanceId

    array

    Yes

    Veri yönlendirme için ECS örneğinin bağlantı noktası numarası. Bu parametre ayarlandıktan sonra, Cloud Assistant Agent bağlantı noktası yönlendirme için verileri belirtilen bağlantı noktasına yönlendirir. Örneğin, SSH 22 numaralı bağlantı noktasını kullanır.

    Varsayılan değer: Boş, bu değer veri yönlendirme için herhangi bir bağlantı noktası numarası ayarlanmadığını gösterir.

    22

    string

    No

    The instance ID of the specified ECS instance. N indicates that you can specify multiple ECS instances at a time. A maximum of 1 ECS instance can be specified. Valid values of N: 1.

    i-bp1eifrtpxa9tb****
    PortNumber

    integer

    No

    Oturum başlatıldıktan sonra çalıştırılacak komut. Komut en fazla 512 karakter uzunluğunda olabilir.

    Not

    CommandLine parametresini belirledikten sonra PortNumber veya TargetServer parametrelerini belirtemezsiniz.

    ssh root@192.168.0.246
    CommandLine

    string

    No

    Örnek üzerinden erişmek istediğiniz VPC'deki hedef sunucunun adresi.

    Not

    Bu parametre boş olmadığında, PortNumber yönetilen örnek üzerinden erişmek istediğiniz VPC'deki hedef sunucunun bağlantı noktası numarasını belirtir.

    192.168.0.246
    TargetServer

    string

    No

    Bağlantı için kullanılan kullanıcı adı.

    testUser
    Username

    string

    No

    Örneğe uzak bağlantı kurmak için gereken WebSocket URL'sinin ağ türü. Geçerli değerler:

    • Internet: İnternet. Bu varsayılan değerdir.

    • Intranet: Dahili ağ.

    Intranet
    ConnectionType

    string

    No

    Windows örneğinde Oturum Yöneticisi kullanılırken kullanıcı için kullanılan parolanın adı. Ad en fazla 255 karakter uzunluğunda olabilir. Windows örneğinde Oturum Yöneticisi'ni varsayılan olmayan bir kullanıcı (System) olarak kullanmak istediğinizde, hem Username hem de bu parametreyi belirtin. Parola sızıntısı riskini azaltmak için düz metin parolayı işlemler yönetiminin parametre deposunda saklayın ve burada yalnızca parola adını belirtin. Daha fazla bilgi için Şifreleme parametreleri konusuna bakın.

    axtSecretPassword
    PasswordName

    string

    No

    İsteğin idempotent olmasını sağlamak için kullanılan istemci belirteci. Belirteci oluşturmak için istemciyi kullanabilirsiniz, ancak belirtecin farklı istekler arasında benzersiz olduğundan emin olun. ClientToken değeri yalnızca ASCII karakterler içerebilir ve uzunluğu 64 karakteri aşamaz. Daha fazla bilgi için İdempotans nasıl sağlanır konusuna bakın.

    123e4567-e89b-12d3-a456-426655440000
    ClientToken

    string

    No

    Oturum şifreleme yapılandırması.

    123e4567-e89b-12d3-a456-426655440000
    EncryptionOptions

    object

    No

    The session encryption configuration.

    Enabled

    boolean

    No

    Specifies whether to enable end-to-end encryption for the session connection.

    true
    KMSKeyId

    string

    No

    The KMS key ID. Note:

    • Only KMS symmetric keys are supported.

    • This parameter can be specified only when the encryption mode is set to Kms.

    xxx
    Mode

    string

    No

    The encryption pattern. Valid values:

    • Auto: Uses automatically negotiated secret key encryption for the session.

    • Kms: Uses a KMS key to encrypt the session.

    • Default value: Auto.

    Note:

    • This parameter can be specified only when session encryption is enabled.

    Auto

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    İstek kimliği.

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

    string

    İsteğin sistem doğrulaması için WebSocket istek üst bilgisine eklenen güvenlik belirteci.

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

    string

    Oturum kimliği.

    s-hz023od0x9****
    WebSocketUrl

    string

    ECS örneğine uzak bağlantı kurmak için WebSocket oturumunun URL'si. URL, oturum kimliğini (SessionId) ve sistem doğrulaması için kullanılan SecurityToken değerini içerir.

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

    Examples

    Success response

    JSON format

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

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    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 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.
    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.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.