StartTerminalSession - Elastic Compute Service: Central de Documentação do Alibaba Cloud

Invoca StartTerminalSession para criar uma sessão com base no recurso de gerenciamento de sessões. Você pode estabelecer uma sessão WebSocket com uma instância ECS especificando o ID da instância. O WebSocketUrl retornado por esta operação permite estabelecer uma conexão remota com a instância ECS.

Descrição da operação

Ao personalizar um cliente de conexão remota usando código, você pode invocar esta operação para obter o WebSocketUrl para estabelecer uma conexão remota com uma instância ECS. Observe os seguintes itens:

A instância ECS especificada deve estar no estado Running.
A instância ECS especificada deve ter o Cloud Assistant Agent instalado. Você pode invocar DescribeCloudAssistantStatus para verificar se o Cloud Assistant Agent está instalado na instância ECS e consultar o número da versão do Cloud Assistant Agent.
- Se o Cloud Assistant Agent não estiver instalado na instância ECS, invoque InstallCloudAssistant para instalá-lo.
- O Cloud Assistant Agent deve ser posterior às seguintes versões para oferecer suporte ao recurso de gerenciamento de sessões. Para atualizar o Cloud Assistant Agent, consulte Atualizar ou desativar atualizações do Cloud Assistant Agent.
  - Sistema operacional Linux: 2.2.3.256
  - Sistema operacional Windows: 2.1.3.256
Após a invocação desta operação, o WebSocketUrl é válido por 10 minutos.
Após o estabelecimento de uma sessão, o Cloud Assistant encerra a conexão se nenhum dado for transmitido por 3 minutos.
Em uma única região, no máximo 100 sessões podem ser criadas e estar ativas. No máximo 20 sessões podem estar no estado conectado para uma única instância ECS. O limite de largura de banda para uma única conexão de sessão é de 200 KB/s.
O recurso de encaminhamento de porta suporta apenas encaminhamento de porta TCP. UDP não é suportado.
Para fechar permanentemente uma sessão e invalidar o WebSocketUrl, invoque a operação EndTerminalSession.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

ecs:StartTerminalSession

update

*Instância.

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

ecs:SessionStartAs

Nenhuma

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
RegionId	string	Sim	O ID da região da instância. Você pode chamar DescribeRegions para consultar a lista de regiões mais recente.	cn-hangzhou
InstanceId	array	Sim	A lista de IDs de instâncias.
	string	Não	O ID da instância ECS especificada. N indica que você pode especificar várias instâncias ECS por vez. No máximo 1 instância ECS pode ser especificada. Valores válidos de N: 1.	i-bp1eifrtpxa9tb****
PortNumber	integer	Não	O número da porta da instância ECS para encaminhamento de dados. Após a definição deste parâmetro, o Cloud Assistant Agent encaminha os dados para a porta especificada para o encaminhamento de porta. Por exemplo, o SSH usa a porta 22. Valor padrão: vazio, o que indica que nenhum número de porta está definido para o encaminhamento de dados.	22
CommandLine	string	Não	O comando a ser executado após o início da sessão. O comando pode ter até 512 caracteres. Nota Após especificar CommandLine, você não pode especificar PortNumber ou TargetServer.	ssh root@192.168.0.246
TargetServer	string	Não	O endereço do servidor de destino na VPC que você deseja acessar por meio da instância. Nota Quando este parâmetro não estiver vazio, PortNumber especifica o número da porta do servidor de destino na VPC que você deseja acessar por meio da instância gerenciada.	192.168.0.246
Username	string	Não	O nome de usuário usado para a conexão.	testUser
ConnectionType	string	Não	O tipo de rede da URL do WebSocket necessária para estabelecer uma conexão remota com a instância. Valores válidos: Internet: Internet. Este é o valor padrão. Intranet: rede interna.	Intranet
PasswordName	string	Não	O nome da senha do usuário ao usar o Session Manager em uma instância Windows. O nome pode ter até 255 caracteres. Quando você deseja usar o Session Manager em uma instância Windows como um usuário não padrão (System), especifique tanto Username quanto este parâmetro. Para reduzir o risco de vazamento de senhas, armazene a senha em texto simples no repositório de parâmetros do gerenciamento de operações e especifique apenas o nome da senha aqui. Para mais informações, consulte Parâmetros de criptografia.	axtSecretPassword
ClientToken	string	Não	O token de cliente usado para garantir a idempotência da solicitação. Você pode usar o cliente para gerar o token, mas certifique-se de que o token seja exclusivo entre diferentes solicitações. O valor de ClientToken pode conter apenas caracteres ASCII e não pode exceder 64 caracteres. Para mais informações, consulte Como garantir a idempotência.	123e4567-e89b-12d3-a456-426655440000
EncryptionOptions	object	Não	A configuração de criptografia da sessão.
Enabled	boolean	Não	Especifica se a criptografia de ponta a ponta deve ser ativada para a conexão da sessão.	true
KMSKeyId	string	Não	O ID da chave do KMS. Precauções: Apenas chaves simétricas do KMS são suportadas. Este parâmetro pode ser especificado apenas quando o modo de criptografia estiver definido como Kms.	xxx
Mode	string	Não	O modo de criptografia de chave secreta. Valores válidos: Auto: Usa uma chave negociada automaticamente para criptografar a sessão. Kms: Usa uma chave do KMS para criptografar a sessão. Valor padrão: Auto. Precauções: Este parâmetro pode ser especificado apenas quando a criptografia da sessão estiver ativada.	Auto

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object
RequestId	string	O ID da solicitação.	EB5173B0-8E80-564E-AAD1-3135412*****
SecurityToken	string	O token de segurança que é anexado ao cabeçalho da solicitação WebSocket para a verificação da solicitação pelo sistema.	d86c2df2-d19c-4bd8-b817-a19ef123****
SessionId	string	O ID da sessão.	s-hz023od0x9****
WebSocketUrl	string	A URL da sessão WebSocket para estabelecer uma conexão remota com a instância ECS. A URL contém o ID da sessão (SessionId) e o SecurityToken usado para a verificação do sistema.	wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9**&token=d86c2df2-d19c-4bd8-b817-a19ef123**

Exemplos

Resposta de sucesso

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 erro

Código de status HTTP	Código de erro	Mensagem de erro	Descrição
400	RegionId.ApiNotSupported	The api is not supported in this region.	A operação de API não é suportada na região especificada. Verifique se o valor do parâmetro RegionId está correto.
400	PortNumber.Invalid	The port number is invalid.
400	InvalidParameter.ConnectionType	The specified parameter ConnectionType is not valid.	O parâmetro ConnectionType especificado é inválido.
400	InvalidClientToken.Malformed	The specified parameter clientToken is not valid.	O parâmetro idempotente especificado é inválido.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	Ocorreu um erro ao enviar a solicitação. Tente novamente mais tarde.
403	InvalidParameterCharacter	The specified parameter %s contains illegal characters.
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	O número de instâncias de destino excede o limite superior.
403	SessionCount.ExceedLimit	The number of sessions exceeds the upper limit.	O número de sessões conectadas excede o limite superior.
403	Operation.Forbidden	The operation is not permitted.	A operação não é permitida.
403	PortForwarding.NotSupported	Port forwarding is not supported currently.	O recurso de encaminhamento de porta não é suportado.
403	UserBehavior.SessionManagerDisabled	The api is disabled by user behavior.	O recurso de conexão remota de gerenciamento de sessão para o usuário está desativado. Certifique-se de que o gerenciamento de sessão esteja ativado (em todas as regiões) para o gerenciamento remoto.
403	InvalidCommandLine.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.	O parâmetro CommandLine não pode ser especificado junto com o parâmetro PortNumber ou TargetServer.
403	InvalidTargetServer.MissingPortNumber	The parameter PortNumber must be specified with parameter TargetServer.	O parâmetro PortNumber deve ser especificado quando o parâmetro TargetServer é usado.
403	InvalidCommandLine.LengthLimitExceeded	The length of the parameter CommandLine exceeded the limit of 512 characters.	O comprimento do conteúdo do parâmetro CommandLine excede o limite de 512 caracteres.
403	InvalidInstanceIds.CountLimitExceeded	The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.	Quando o parâmetro TargetServer ou CommandLine é usado, o número de instâncias excede o limite máximo. Apenas uma instância é permitida.
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	O comprimento do nome de usuário excede o limite superior.
403	InvalidOperation.SecurityGroupRuleDenied	The operation is not allowed by the security group inbound rules of the specified instance.	As regras de entrada do grupo de segurança associado à instância especificada não permitem esta operação.
403	InvalidTargetServer.LengthLimitExceeded	The length of the parameter TargetServer exceeded the limit of 128 characters.	O comprimento do parâmetro TargetServer excede o limite de 128 caracteres.
403	InvalidOperation.ConnectionTypeUnsupported	The operation is not supported for the parameter ConnectionType.	O parâmetro ConnectionType especificado não suporta esta operação.
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.	O parâmetro EncryptionOptions.Mode não pode ser especificado quando a criptografia de sessão não está ativada.
403	InvalidParameter.EncryptionOptionsKMSKeyId	The specified parameter EncryptionOptions.KMSKeyId is not valid.	O parâmetro EncryptionOptions.KMSKeyId especificado é inválido.
403	InvalidParameter.EncryptionOptionsMode	The specified parameter EncryptionOptions.Mode is not valid.	O parâmetro EncryptionOptions.Mode especificado é inválido.
403	MissingParameter.EncryptionOptionsKMSKeyId	The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied.	O parâmetro EncryptionOptions.KMSKeyId não pode estar vazio.
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.	O parâmetro PortNumber ou TargetServer não pode ser especificado quando a criptografia de sessão está ativada.
403	IdempotentParameterMismatch	The specified parameter has changed while using an already used clientToken.	Os parâmetros da solicitação não correspondem à solicitação com o mesmo ClientToken.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	A solicitação idempotente anterior ainda está sendo processada. Tente novamente mais tarde.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	O RegionId especificado não existe. Verifique se o produto está disponível nesta região.
404	InvalidInstance.NotFound	The specified instances not found.	A instância especificada não existe.

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.