Todos los productos
Search

Este producto

    Elastic Compute Service:StartTerminalSession

    Centro de documentos

    Elastic Compute Service:StartTerminalSession

    Última actualización: Sep 20, 2026

    Invoca StartTerminalSession para crear una sesión basada en la función de administración de sesiones. Puede establecer una sesión de WebSocket con una instancia de ECS al especificar el ID de la instancia. La WebSocketUrl que devuelve esta operación permite establecer una conexión remota con la instancia de ECS.

    Descripción de la operación

    Descripción de la operación

    Al personalizar un cliente de conexión remota mediante código, puede invocar esta operación para obtener la WebSocketUrl para establecer una conexión remota con una instancia de ECS. Tenga en cuenta los siguientes puntos:

    • La instancia de ECS especificada debe estar en estado Running.

    • La instancia de ECS especificada debe tener instalado el agente de Cloud Assistant. Puede invocar DescribeCloudAssistantStatus para comprobar si el agente de Cloud Assistant está instalado en la instancia de ECS y consultar el número de versión del agente de Cloud Assistant.

    • Después de invocar esta operación, la WebSocketUrl es válida durante 10 minutos.

    • Una vez establecida una sesión, Cloud Assistant cierra la conexión si no se transmiten datos durante 3 minutos.

    • En una sola región, se pueden crear y mantener activas un máximo de 100 sesiones. Un máximo de 20 sesiones pueden estar en estado conectado para una sola instancia de ECS. El límite de ancho de banda para una sola conexión de sesión es de 200 KB/s.

    • La función de reenvío de puertos solo admite el reenvío de puertos TCP. No se admite UDP.

    • Para cerrar permanentemente una sesión e invalidar la WebSocketUrl, invoque la operación EndTerminalSession.

    Pruébelo ahora

    Pruebe esta API en OpenAPI Explorer sin necesidad de firma manual. Las llamadas exitosas generan automáticamente código SDK acorde a sus parámetros. Descárguelo con seguridad de credenciales integrada para uso local.

    Test

    Autorización de RAM

    La siguiente tabla describe la autorización necesaria para invocar esta API. Puede definirla en una directiva de Resource Access Management (RAM). A continuación, se detallan las columnas de la tabla:

    • Action: Estas acciones se utilizan en el elemento Action de las declaraciones de directivas de permisos de RAM para otorgar permisos que permitan realizar la operación.

    • API: La API que debe invocarse para llevar a cabo la acción.

    • Nivel de acceso: Nivel de acceso predefinido que se concede para cada API. Valores válidos: create, list, get, update y delete.

    • Tipo de recurso: Tipo de recurso que admite autorización para ejecutar la acción. Indica si la acción es compatible con permisos a nivel de recurso. El recurso especificado debe ser compatible con la acción; de lo contrario, la directiva no surtirá efecto.

      • En las API con permisos a nivel de recurso, los tipos de recursos obligatorios se marcan con un asterisco (*). Especifique el Alibaba Cloud Resource Name (ARN) correspondiente en el elemento Resource de la directiva.

      • Para las API sin permisos a nivel de recurso, se muestra All Resources. Utilice un asterisco (*) en el elemento Resource de la directiva.

    • Clave de condición: Claves de condición definidas por el servicio. Permiten un control granular y se aplican ya sea solo a acciones o a acciones asociadas con recursos específicos. Además de las claves de condición específicas del servicio, Alibaba Cloud proporciona un conjunto de common condition keys aplicables a todos los servicios compatibles con RAM.

    • Acción dependiente: Acciones dependientes necesarias para ejecutar la acción principal. Para completar la operación, el usuario de RAM o el rol de RAM debe contar con permisos para realizar todas las acciones dependientes.

    Action

    Nivel de acceso

    Tipo de recurso

    Clave de condición

    Acción dependiente

    ecs:StartTerminalSession

    update

    *Instance.

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

    Parámetros de la solicitud

    Parámetro

    Tipo

    Obligatorio

    Descripción

    Ejemplo
    RegionId

    string

    Sí

    El ID de la región de la instancia. Puede llamar a DescribeRegions para consultar la lista de regiones más reciente.

    cn-hangzhou
    InstanceId

    array

    Sí

    La lista de ID de instancias.

    string

    No

    El ID de la instancia de ECS especificada. N indica que puede especificar varias instancias de ECS a la vez. Se puede especificar un máximo de 1 instancia de ECS. Valores válidos de N: 1.

    i-bp1eifrtpxa9tb****
    PortNumber

    integer

    No

    El número de puerto de la instancia de ECS para el reenvío de datos. Una vez configurado este parámetro, el agente de Cloud Assistant reenvía los datos al puerto especificado para el reenvío de puertos. Por ejemplo, SSH utiliza el puerto 22.

    Valor predeterminado: vacío, lo que indica que no se establece ningún número de puerto para el reenvío de datos.

    22
    CommandLine

    string

    No

    El comando que se ejecutará después de iniciar la sesión. El comando puede tener una longitud de hasta 512 caracteres.

    Nota

    Después de especificar CommandLine, no puede especificar PortNumber ni TargetServer.

    ssh root@192.168.0.246
    TargetServer

    string

    No

    La dirección del servidor de destino en la VPC a la que desea acceder a través de la instancia.

    Nota

    Cuando este parámetro no está vacío, PortNumber especifica el número de puerto del servidor de destino en la VPC a la que desea acceder a través de la instancia administrada.

    192.168.0.246
    Username

    string

    No

    El nombre de usuario utilizado para la conexión.

    testUser
    ConnectionType

    string

    No

    El tipo de red de la URL de WebSocket necesaria para establecer una conexión remota con la instancia. Valores válidos:

    • Internet: Internet. Este es el valor predeterminado.

    • Intranet: red interna.

    Intranet
    PasswordName

    string

    No

    El nombre de la contraseña del usuario al utilizar Session Manager en una instancia de Windows. El nombre puede tener una longitud de hasta 255 caracteres. Cuando desee utilizar Session Manager en una instancia de Windows como un usuario no predeterminado (System), especifique tanto Username como este parámetro. Para reducir el riesgo de filtraciones de contraseñas, almacene la contraseña en texto plano en el repositorio de parámetros de administración de operaciones y especifique aquí solo el nombre de la contraseña. Para obtener más información, consulte Parámetros de cifrado.

    axtSecretPassword
    ClientToken

    string

    No

    El token de cliente que se utiliza para garantizar la idempotencia de la solicitud. Puede utilizar el cliente para generar el token, pero asegúrese de que el token sea único entre las diferentes solicitudes. El valor de ClientToken solo puede contener caracteres ASCII y no puede superar los 64 caracteres de longitud. Para obtener más información, consulte Cómo garantizar la idempotencia.

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

    object

    No

    La configuración de cifrado de la sesión.

    Enabled

    boolean

    No

    Especifica si se debe habilitar el cifrado de extremo a extremo para la conexión de la sesión.

    true
    KMSKeyId

    string

    No

    El ID de la clave de KMS. Precauciones:

    • Solo se admiten claves simétricas de KMS.

    • Este parámetro solo se puede especificar cuando el modo de cifrado se establece en Kms.

    xxx
    Mode

    string

    No

    El modo de cifrado de clave secreta. Valores válidos:

    • Auto: Utiliza una clave negociada automáticamente para cifrar la sesión.

    • Kms: Utiliza una clave de KMS para cifrar la sesión.

    • Valor predeterminado: Auto.

    Precauciones:

    • Este parámetro solo se puede especificar cuando el cifrado de sesión está habilitado.

    Auto

    Elementos de la respuesta

    Elemento

    Tipo

    Descripción

    Ejemplo

    object

    RequestId

    string

    El ID de la solicitud.

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

    string

    El token de seguridad que se añade al encabezado de la solicitud de WebSocket para la verificación de la solicitud por parte del sistema.

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

    string

    El ID de la sesión.

    s-hz023od0x9****
    WebSocketUrl

    string

    La URL de la sesión de WebSocket para establecer una conexión remota con la instancia de ECS. La URL contiene el ID de la sesión (SessionId) y el SecurityToken utilizado para la verificación del sistema.

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

    Ejemplos

    Respuesta exitosa

    JSON Formato

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

    Códigos de error

    Código de estado HTTP

    Código de error

    Mensaje de error

    Descripción
    400 RegionId.ApiNotSupported The api is not supported in this region. La operación de API no es compatible en la región especificada. Compruebe si el valor del parámetro RegionId es correcto.
    400 PortNumber.Invalid The port number is invalid.
    400 InvalidParameter.ConnectionType The specified parameter ConnectionType is not valid. El parámetro ConnectionType especificado no es válido.
    400 InvalidClientToken.Malformed The specified parameter clientToken is not valid. El parámetro idempotente especificado no es válido.
    500 InternalError.Dispatch An error occurred when you dispatched the request. Ocurrió un error al enviar la solicitud. Inténtelo de nuevo más tarde.
    403 InvalidParameterCharacter The specified parameter %s contains illegal characters.
    403 InstanceIds.ExceedLimit The number of instance IDs exceeds the upper limit. El número de instancias de destino excede el límite superior.
    403 SessionCount.ExceedLimit The number of sessions exceeds the upper limit. El número de sesiones en estado conectado excede el límite superior.
    403 Operation.Forbidden The operation is not permitted. La operación no está permitida.
    403 PortForwarding.NotSupported Port forwarding is not supported currently. La función de reenvío de puertos no es compatible.
    403 UserBehavior.SessionManagerDisabled The api is disabled by user behavior. La función de conexión remota de gestión de sesiones para el usuario está deshabilitada. Asegúrese de que la gestión de sesiones esté habilitada (en todas las regiones) para la administración remota.
    403 InvalidCommandLine.Conflict The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine. El parámetro CommandLine no se puede especificar junto con el parámetro PortNumber o TargetServer.
    403 InvalidTargetServer.MissingPortNumber The parameter PortNumber must be specified with parameter TargetServer. El parámetro PortNumber debe especificarse cuando se utiliza el parámetro TargetServer.
    403 InvalidCommandLine.LengthLimitExceeded The length of the parameter CommandLine exceeded the limit of 512 characters. La longitud del contenido del parámetro CommandLine supera el límite de 512 caracteres.
    403 InvalidInstanceIds.CountLimitExceeded The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified. Cuando se utiliza el parámetro TargetServer o CommandLine, el número de instancias supera el límite máximo. Solo se permite una instancia.
    403 Username.ExceedLimit The length of the username exceeds the upper limit. La longitud del nombre de usuario excede el límite superior.
    403 InvalidOperation.SecurityGroupRuleDenied The operation is not allowed by the security group inbound rules of the specified instance. Las reglas de entrada del security group asociado con la instancia especificada no permiten esta operación.
    403 InvalidTargetServer.LengthLimitExceeded The length of the parameter TargetServer exceeded the limit of 128 characters. La longitud del parámetro TargetServer supera el límite de 128 caracteres.
    403 InvalidOperation.ConnectionTypeUnsupported The operation is not supported for the parameter ConnectionType. El parámetro ConnectionType especificado no admite esta operación.
    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. No se puede especificar el parámetro EncryptionOptions.Mode cuando el cifrado de sesión no está habilitado.
    403 InvalidParameter.EncryptionOptionsKMSKeyId The specified parameter EncryptionOptions.KMSKeyId is not valid. El parámetro EncryptionOptions.KMSKeyId especificado no es válido.
    403 InvalidParameter.EncryptionOptionsMode The specified parameter EncryptionOptions.Mode is not valid. El parámetro EncryptionOptions.Mode especificado no es válido.
    403 MissingParameter.EncryptionOptionsKMSKeyId The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied. El parámetro EncryptionOptions.KMSKeyId no puede estar vacío.
    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. No se pueden especificar los parámetros PortNumber o TargetServer cuando el cifrado de sesión está habilitado.
    403 IdempotentParameterMismatch The specified parameter has changed while using an already used clientToken. Los parámetros de la solicitud no coinciden con la solicitud que tiene el mismo ClientToken.
    403 IdempotentProcessing The previous idempotent request(s) is still processing. La solicitud idempotente anterior aún se está procesando. Inténtelo de nuevo más tarde.
    404 InvalidRegionId.NotFound The RegionId provided does not exist in our records. El RegionId especificado no existe. Verifique si el producto está disponible en esta región.
    404 InvalidInstance.NotFound The specified instances not found. La instancia especificada no existe.

    Consulte Códigos de error para ver la lista completa.

    Notas de la versión

    Consulte Notas de la versión para ver la lista completa.