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

Cria uma sessão com base no recurso de gerenciamento de sessões chamando StartTerminalSession. Você pode estabelecer uma sessão WebSocket com uma instância do Elastic Compute Service (ECS) especificando o ID da instância e conectar-se remotamente à instância usando a URL do WebSocket retornada na resposta.

Descrição da operação

Ao personalizar um cliente de conexão remota usando código, você pode chamar esta operação para obter a URL do WebSocket para conectar-se remotamente a uma instância ECS. Observe os seguintes itens ao chamar esta operação:

A instância ECS especificada deve estar no estado Running.
O Cloud Assistant Agent deve estar instalado na instância ECS especificada. Você pode chamar DescribeCloudAssistantStatus para consultar 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 sua instância ECS, chame InstallCloudAssistant para instalá-lo.
- O Cloud Assistant Agent deve ser de uma versão 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 a atualização do Cloud Assistant Agent.
  - Sistema operacional Linux: 2.2.3.256
  - Sistema operacional Windows: 2.1.3.256
Após esta operação ser chamada com sucesso, a URL do WebSocket é válida por 10 minutos.
Após o estabelecimento de uma sessão, o Cloud Assistant encerrará a conexão se nenhum dado for transmitido dentro de 3 minutos.
Na mesma região, o número de sessões criadas e ativas não pode exceder 100. O número de sessões no estado conectado para uma única instância ECS não pode exceder 20. O limite de largura de banda para uma única conexão de sessão é de 200 Kbit/s.
O recurso de encaminhamento de porta suporta apenas encaminhamento de porta TCP e não suporta UDP.
Para encerrar permanentemente uma sessão e invalidar a URL do WebSocket, chame 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

*Instance

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 as regiões mais recentes.	cn-hangzhou
InstanceId	array	Sim	A lista de IDs de instâncias.
	string	Não	O ID da instância ECS. Você pode especificar apenas uma instância ECS. Valores válidos de N: 1.	i-bp1eifrtpxa9tb****
PortNumber	integer	Não	O número da porta da instância ECS usada para encaminhamento de porta. Se você especificar este parâmetro, o Cloud Assistant Agent encaminhará os dados para a porta especificada. Por exemplo, o SSH usa a porta 22. Valor padrão: vazio, o que indica que nenhum número de porta é especificado para o encaminhamento de porta.	22
CommandLine	string	Não	O comando a ser executado após o início da sessão. O valor não pode exceder 512 caracteres de comprimento. Nota Se você especificar `CommandLine`, não poderá especificar `PortNumber` ou `TargetServer`.	ssh root@192.168.0.246
TargetServer	string	Não	O endereço do serviço de destino na VPC que é acessado por meio da instância. Nota Se este parâmetro não estiver vazio, `PortNumber` especifica o número da porta do serviço de destino na VPC acessado por meio da instância gerenciada.	192.168.0.246
Username	string	Não	O nome de usuário usado para conectar-se à instância.	testUser
ConnectionType	string	Não	O tipo de rede da URL do WebSocket necessária para conectar-se remotamente à instância. Valores válidos: Internet: a Internet (padrão). Intranet: a rede interna.	Intranet
PasswordName	string	Não	O nome da senha do usuário usada ao usar o Session Manager em uma instância Windows. O valor não pode exceder 255 caracteres de comprimento. Se você quiser usar o Session Manager em uma instância Windows como um usuário não padrão (diferente de System), deverá especificar tanto `Username` quanto este parâmetro. Para reduzir o risco de vazamento de senha, a senha em texto simples deve ser hospedada no repositório de parâmetros do CloudOps Orchestration Service, e você só precisa passar o nome da senha aqui. Para obter mais informações, consulte Criptografar um parâmetro.	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 deve garantir que ele seja exclusivo entre diferentes solicitações. O ClientToken pode conter apenas caracteres ASCII e não pode exceder 64 caracteres de comprimento. Para obter mais informações, consulte Garantir 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 Key Management Service (KMS). Precauções: Apenas chaves simétricas do KMS são suportadas. Você pode especificar este parâmetro apenas quando o modo de criptografia estiver definido como Kms.	xxx
Mode	string	Não	O modo de criptografia. Valores válidos: Auto: usa chaves negociadas automaticamente para criptografar a sessão. Kms: usa chaves do KMS para criptografar a sessão. Valor padrão: Auto. Precauções: Você pode especificar este parâmetro 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*****
SessionId	string	O ID da sessão.	s-hz023od0x9****
SecurityToken	string	O token de segurança anexado ao cabeçalho da solicitação WebSocket, que é usado pelo sistema para verificar a solicitação.	d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrl	string	A URL correspondente à sessão WebSocket para conectar-se remotamente à instância ECS. Ela inclui o ID da sessão (`SessionId`) e o `SecurityToken` usado para 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*****",
  "SessionId": "s-hz023od0x9****",
  "SecurityToken": "d86c2df2-d19c-4bd8-b817-a19ef123****",
  "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.	Esta 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 de idempotência 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 máximo.
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 por meio do gerenciamento de sessão 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.	Você deve especificar o parâmetro PortNumber ao usar o parâmetro TargetServer.
403	InvalidCommandLine.LengthLimitExceeded	The length of the parameter CommandLine exceeded the limit of 512 characters.	O comprimento do valor 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 de 1.
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	O tamanho 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 tamanho do parâmetro TargetServer excede o limite de 128 caracteres.
403	InvalidOperation.ConnectionTypeUnsupported	The operation is not supported for the parameter ConnectionType.	Esta operação não é suportada para o parâmetro ConnectionType especificado.
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 está desativada.
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 aos de uma solicitação anterior com o mesmo ClientToken.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	Uma 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 serviço está disponível na 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.