All Products
Search

This Product

    Elastic Compute Service:StartTerminalSession

    Document Center

    Elastic Compute Service:StartTerminalSession

    Last Updated:Sep 20, 2026

    Memanggil StartTerminalSession untuk membuat sesi berdasarkan fitur manajemen sesi. Anda dapat membuat sesi WebSocket dengan Instance ECS dengan menentukan ID instans. WebSocketUrl yang dikembalikan oleh operasi ini memungkinkan Anda membuat koneksi jarak jauh ke Instance ECS.

    Deskripsi operasi

    Deskripsi operasi

    Saat Anda menyesuaikan klien koneksi jarak jauh menggunakan kode, Anda dapat memanggil operasi ini untuk mendapatkan WebSocketUrl guna membuat koneksi jarak jauh ke Instance ECS. Perhatikan hal-hal berikut:

    • Instance ECS yang ditentukan harus dalam status Berjalan.

    • Instance ECS yang ditentukan harus memiliki Agen Asisten Cloud yang terinstal. Anda dapat memanggil DescribeCloudAssistantStatus untuk memeriksa apakah Agen Asisten Cloud terinstal pada Instance ECS dan mengkueri nomor versi Agen Asisten Cloud.

    • Setelah operasi ini dipanggil, WebSocketUrl berlaku selama 10 menit.

    • Setelah sesi dibuat, Asisten Cloud akan menutup koneksi jika tidak ada data yang ditransmisikan selama 3 menit.

    • Dalam satu wilayah, maksimum 100 sesi dapat dibuat dan aktif. Maksimum 20 sesi dapat berada dalam status terhubung untuk satu Instance ECS. Batas bandwidth untuk satu koneksi sesi adalah 200 KB/s.

    • Fitur penerusan port hanya mendukung penerusan port TCP. UDP tidak didukung.

    • Untuk menutup sesi secara permanen dan membatalkan WebSocketUrl, panggil operasi EndTerminalSession.

    Coba sekarang

    Coba API ini di OpenAPI Explorer tanpa perlu penandatanganan manual. Panggilan yang berhasil akan secara otomatis menghasilkan contoh kode SDK sesuai dengan parameter Anda. Unduh kode tersebut dengan kredensial bawaan yang aman untuk penggunaan lokal.

    Test

    RAM authorization

    Tabel berikut menjelaskan otorisasi yang diperlukan untuk memanggil API ini. Anda dapat menentukannya dalam kebijakan Resource Access Management (RAM). Kolom pada tabel dijelaskan sebagai berikut:

    • Action: Aksi yang dapat digunakan dalam elemen Action pada pernyataan kebijakan izin RAM untuk memberikan izin guna melakukan operasi tersebut.

    • API: API yang dapat Anda panggil untuk melakukan aksi tersebut.

    • Access level: Tingkat akses yang telah ditentukan untuk setiap API. Nilai yang valid: create, list, get, update, dan delete.

    • Resource type: Jenis resource yang mendukung otorisasi untuk melakukan aksi tersebut. Ini menunjukkan apakah aksi tersebut mendukung izin tingkat resource. Resource yang ditentukan harus kompatibel dengan aksi tersebut. Jika tidak, kebijakan tersebut tidak akan berlaku.

      • Untuk API dengan izin tingkat resource, jenis resource yang diperlukan ditandai dengan tanda bintang (*). Tentukan Nama Sumber Daya Alibaba Cloud (ARN) yang sesuai dalam elemen Resource pada kebijakan.

      • Untuk API tanpa izin tingkat resource, ditampilkan sebagai All Resources. Gunakan tanda bintang (*) dalam elemen Resource pada kebijakan.

    • Condition key: Kunci kondisi yang didefinisikan oleh layanan. Kunci ini memungkinkan kontrol granular, berlaku baik hanya untuk aksi maupun untuk aksi yang terkait dengan resource tertentu. Selain kunci kondisi spesifik layanan, Alibaba Cloud menyediakan serangkaian common condition keys yang berlaku di semua layanan yang didukung RAM.

    • Dependent action: Aksi dependen yang diperlukan untuk menjalankan aksi tersebut. Untuk menyelesaikan aksi tersebut, pengguna RAM atau role RAM harus memiliki izin untuk melakukan semua aksi dependen.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecs:StartTerminalSession

    update

    *Instance.

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

    Parameter permintaan

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    ID wilayah instans. Anda dapat memanggil DescribeRegions untuk mengkueri daftar wilayah terbaru.

    cn-hangzhou
    InstanceId

    array

    Yes

    Daftar ID instans.

    string

    No

    ID instans Instance ECS yang ditentukan. N menunjukkan bahwa Anda dapat menentukan beberapa Instance ECS sekaligus. Maksimum 1 Instance ECS dapat ditentukan. Nilai valid N: 1.

    i-bp1eifrtpxa9tb****
    PortNumber

    integer

    No

    Nomor Port Instance ECS untuk penerusan data. Setelah parameter ini ditetapkan, Agen Asisten Cloud meneruskan data ke Port yang ditentukan untuk penerusan port. Misalnya, SSH menggunakan Port 22.

    Nilai default: kosong, yang menunjukkan bahwa tidak ada nomor Port yang ditetapkan untuk penerusan data.

    22
    CommandLine

    string

    No

    Perintah yang akan dijalankan setelah sesi dimulai. Perintah dapat memiliki panjang hingga 512 karakter.

    Catatan

    Setelah Anda menentukan CommandLine, Anda tidak dapat menentukan PortNumber atau TargetServer.

    ssh root@192.168.0.246
    TargetServer

    string

    No

    Alamat server tujuan di VPC yang ingin Anda akses melalui instans.

    Catatan

    Saat parameter ini tidak kosong, PortNumber menentukan nomor port server tujuan di VPC yang ingin Anda akses melalui instans terkelola.

    192.168.0.246
    Username

    string

    No

    Nama pengguna yang digunakan untuk koneksi.

    testUser
    ConnectionType

    string

    No

    Jenis jaringan URL WebSocket yang diperlukan untuk membuat koneksi jarak jauh ke instans. Nilai valid:

    • Internet: Internet. Ini adalah nilai default.

    • Intranet: jaringan internal.

    Intranet
    PasswordName

    string

    No

    Nama kata sandi untuk pengguna saat menggunakan Session Manager pada instans Windows. Nama dapat memiliki panjang hingga 255 karakter. Saat Anda ingin menggunakan Session Manager pada instans Windows sebagai pengguna non-default (System), tentukan Username dan parameter ini. Untuk mengurangi risiko kebocoran kata sandi, simpan kata sandi teks biasa di repositori parameter manajemen operasi dan tentukan hanya nama kata sandi di sini. Untuk informasi selengkapnya, lihat Encryption parameters.

    axtSecretPassword
    ClientToken

    string

    No

    Token klien yang digunakan untuk memastikan idempotensi permintaan. Anda dapat menggunakan klien untuk menghasilkan token, tetapi pastikan token tersebut unik di antara permintaan yang berbeda. Nilai ClientToken hanya dapat berisi karakter ASCII dan tidak boleh melebihi 64 karakter. Untuk informasi selengkapnya, lihat How to ensure idempotence.

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

    object

    No

    Konfigurasi enkripsi sesi.

    Enabled

    boolean

    No

    Apakah akan mengaktifkan enkripsi end-to-end untuk koneksi sesi.

    true
    KMSKeyId

    string

    No

    ID kunci KMS. Catatan:

    • Hanya kunci simetris KMS yang didukung.

    • Parameter ini hanya dapat ditentukan saat mode enkripsi diatur ke Kms.

    xxx
    Mode

    string

    No

    Mode enkripsi kunci rahasia. Nilai valid:

    • Auto: Menggunakan kunci yang dinegosiasikan secara otomatis untuk mengenkripsi sesi.

    • Kms: Menggunakan kunci KMS untuk mengenkripsi sesi.

    • Nilai default: Auto.

    Catatan:

    • Parameter ini hanya dapat ditentukan saat enkripsi sesi diaktifkan.

    Auto

    Elemen respons

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    ID permintaan.

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

    string

    Token keamanan yang ditambahkan ke header permintaan WebSocket untuk verifikasi sistem atas permintaan.

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

    string

    ID sesi.

    s-hz023od0x9****
    WebSocketUrl

    string

    URL sesi WebSocket untuk membuat koneksi jarak jauh ke Instance ECS. URL tersebut berisi ID sesi (SessionId) dan SecurityToken yang digunakan untuk verifikasi sistem.

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

    Contoh

    Respons sukses

    JSONformat

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

    Kode kesalahan

    HTTP status code

    Error code

    Error message

    Description
    400 RegionId.ApiNotSupported The api is not supported in this region. Pemanggilan API tidak didukung di wilayah tertentu. Periksa apakah nilai parameter RegionId benar.
    400 PortNumber.Invalid The port number is invalid.
    400 InvalidParameter.ConnectionType The specified parameter ConnectionType is not valid. Parameter ConnectionType yang ditentukan tidak valid.
    400 InvalidClientToken.Malformed The specified parameter clientToken is not valid. Parameter idempoten yang ditentukan tidak valid.
    500 InternalError.Dispatch An error occurred when you dispatched the request. Terjadi kesalahan saat mengirim permintaan. Coba lagi nanti.
    403 InvalidParameterCharacter The specified parameter %s contains illegal characters.
    403 InstanceIds.ExceedLimit The number of instance IDs exceeds the upper limit. Jumlah instans target melebihi batas atas.
    403 SessionCount.ExceedLimit The number of sessions exceeds the upper limit. Jumlah sesi yang terhubung melebihi batas atas.
    403 Operation.Forbidden The operation is not permitted. Operasi tidak diizinkan.
    403 PortForwarding.NotSupported Port forwarding is not supported currently. Fitur penerusan port tidak didukung.
    403 UserBehavior.SessionManagerDisabled The api is disabled by user behavior. Fitur koneksi jarak jauh melalui manajemen sesi dinonaktifkan untuk pengguna. Pastikan manajemen sesi diaktifkan (di semua wilayah) untuk manajemen jarak jauh.
    403 InvalidCommandLine.Conflict The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine. Parameter CommandLine tidak dapat ditentukan bersama dengan parameter PortNumber atau TargetServer.
    403 InvalidTargetServer.MissingPortNumber The parameter PortNumber must be specified with parameter TargetServer. Parameter PortNumber harus ditentukan saat menggunakan parameter TargetServer.
    403 InvalidCommandLine.LengthLimitExceeded The length of the parameter CommandLine exceeded the limit of 512 characters. Panjang konten parameter CommandLine melebihi batas 512 karakter.
    403 InvalidInstanceIds.CountLimitExceeded The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified. Saat menggunakan parameter TargetServer atau CommandLine, jumlah instans melebihi batas maksimum. Hanya satu instans yang diizinkan.
    403 Username.ExceedLimit The length of the username exceeds the upper limit. Panjang nama pengguna melebihi batas atas.
    403 InvalidOperation.SecurityGroupRuleDenied The operation is not allowed by the security group inbound rules of the specified instance. Aturan arah masuk dari grup keamanan yang terkait dengan instans yang ditentukan tidak mengizinkan operasi ini.
    403 InvalidTargetServer.LengthLimitExceeded The length of the parameter TargetServer exceeded the limit of 128 characters. Panjang parameter TargetServer melebihi batas 128 karakter.
    403 InvalidOperation.ConnectionTypeUnsupported The operation is not supported for the parameter ConnectionType. Parameter ConnectionType yang ditentukan tidak mendukung operasi ini.
    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. Parameter EncryptionOptions.Mode tidak dapat ditentukan saat enkripsi sesi tidak diaktifkan.
    403 InvalidParameter.EncryptionOptionsKMSKeyId The specified parameter EncryptionOptions.KMSKeyId is not valid. Parameter EncryptionOptions.KMSKeyId yang ditentukan tidak valid.
    403 InvalidParameter.EncryptionOptionsMode The specified parameter EncryptionOptions.Mode is not valid. Parameter EncryptionOptions.Mode yang ditentukan tidak valid.
    403 MissingParameter.EncryptionOptionsKMSKeyId The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied. Parameter EncryptionOptions.KMSKeyId tidak boleh kosong.
    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. Parameter PortNumber atau TargetServer tidak dapat ditentukan saat enkripsi sesi diaktifkan.
    403 IdempotentParameterMismatch The specified parameter has changed while using an already used clientToken. Parameter permintaan tidak cocok dengan permintaan yang memiliki ClientToken yang sama.
    403 IdempotentProcessing The previous idempotent request(s) is still processing. Permintaan idempoten sebelumnya masih diproses. Coba lagi nanti.
    404 InvalidRegionId.NotFound The RegionId provided does not exist in our records. RegionId yang ditentukan tidak ada. Periksa apakah produk tersedia di wilayah ini.
    404 InvalidInstance.NotFound The specified instances not found. Instans yang ditentukan tidak ada.

    Lihat Error Codes untuk daftar lengkap.

    Catatan rilis

    Lihat Release Notes untuk daftar lengkap.