Todos os produtos
Search
Central de documentação

Elastic Compute Service:CreateCommand

Última atualização: Sep 20, 2026

Cria um comando do Cloud Assistant do tipo de script Shell, PowerShell ou Bat.

Descrição da operação

Descrição da operação

  • Você pode criar os seguintes tipos de comandos:
    • Scripts Bat para instâncias Windows (RunBatScript).

    • Scripts PowerShell para instâncias Windows (RunPowerShellScript).

    • Scripts Shell para instâncias Linux (RunShellScript).

  • Você pode especificar o parâmetro Timeout para definir o período máximo de tempo limite para a execução do comando em instâncias ECS. Se o comando atingir o tempo limite, o Agente do Cloud Assistant encerra forçosamente o processo do comando cancelando o PID do comando.
    • Para uma execução única, após o tempo limite do comando, o status de execução (InvokeRecordStatus) do comando na instância ECS especificada muda para Failed.

    • Para uma execução agendada:
      • O período de tempo limite entra em vigor para cada registro de execução.

      • Após o tempo limite de uma execução específica, o status (InvokeRecordStatus) do registro de execução muda para Failed.

      • O tempo limite de uma execução anterior não afeta a próxima execução.

  • Você pode manter de 500 a 50.000 comandos do Cloud Assistant em uma região. Você também pode solicitar um aumento de cota. Para obter informações sobre como consultar e aumentar cotas, consulte Gerenciamento de cotas.

  • Você pode especificar o parâmetro WorkingDir para definir o caminho de execução do comando. Para instâncias Linux, o caminho padrão é o diretório home do usuário root, que é /root. Para instâncias Windows, o caminho padrão é o diretório onde o processo do Agente do Cloud Assistant está localizado, como C:\Windows\System32.

  • Você pode especificar EnableParameter=true para ativar o recurso de parâmetro personalizado. Ao definir CommandContent, você pode definir parâmetros personalizados no formato {{parameter}} e passar pares chave-valor de parâmetros personalizados ao executar o comando chamando InvokeCommand. Por exemplo, se você criar o comando echo {{name}} e passar o par chave-valor <name, Jack> usando o parâmetro Parameters ao chamar InvokeCommand, o parâmetro personalizado será substituído automaticamente. Um novo comando echo Jack é gerado e executado na instância.

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:CreateCommand

create

*Command.

acs:ecs:{#regionId}:{#accountId}:command/*

Nenhuma Nenhuma

Parâmetros da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Exemplo

RegionId

string

Sim

O ID da região. Você pode chamar DescribeRegions para consultar a lista de regiões mais recente.

cn-hangzhou

Name

string

Sim

O nome do comando. Todos os conjuntos de caracteres são suportados. O nome pode ter até 128 caracteres.

testName

Description

string

Não

A descrição do comando. Todos os conjuntos de caracteres são suportados. A descrição pode ter até 512 caracteres.

testDescription

Type

string

Sim

O tipo do comando. Valores válidos:

  • RunBatScript: cria um script Bat para execução em instâncias Windows.

  • RunPowerShellScript: cria um script PowerShell para execução em instâncias Windows.

  • RunShellScript: cria um script Shell para execução em instâncias Linux.

RunShellScript

CommandContent

string

Sim

O conteúdo do comando codificado em Base64.

  • O valor deste parâmetro deve ser codificado em Base64 e não pode exceder 24 KB de tamanho após a codificação.

  • O conteúdo do comando suporta parâmetros personalizados. Para ativar o recurso de parâmetro personalizado, especifique EnableParameter=true:

    • Os parâmetros personalizados são definidos colocando o nome do parâmetro entre {{}}. Espaços e quebras de linha antes e depois do nome do parâmetro em {{}} são ignorados.

    • O número de parâmetros personalizados não pode exceder 20.

    • Os nomes dos parâmetros personalizados podem conter letras (a-z, A-Z), dígitos (0-9), hifens (-) e sublinhados (_). O prefixo acs:: para especificar parâmetros de ambiente não integrados não é suportado. Outros caracteres não são suportados. Os nomes dos parâmetros não diferenciam maiúsculas de minúsculas.

    • Cada nome de parâmetro pode ter até 64 bytes de comprimento.

  • Você pode especificar parâmetros de ambiente integrados como parâmetros personalizados. Quando o comando é executado, o Cloud Assistant substitui automaticamente os parâmetros pelos valores correspondentes do ambiente. Os seguintes parâmetros de ambiente integrados são suportados:

    • {{ACS::RegionId}}: o ID da região.

    • {{ACS::AccountId}}: o UID da conta Alibaba Cloud.

    • {{ACS::InstanceId}}: o ID da instância. Quando o comando é enviado para várias instâncias e você deseja usar {{ACS::InstanceId}} como um parâmetro de ambiente integrado, certifique-se de que a versão do Agente do Cloud Assistant não seja anterior às seguintes versões:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

    • {{ACS::InstanceName}}: o nome da instância. Quando o comando é enviado para várias instâncias e você deseja usar {{ACS::InstanceName}} como um parâmetro de ambiente integrado, certifique-se de que a versão do Agente do Cloud Assistant não seja anterior às seguintes versões:

      • Linux: 2.2.3.344

      • Windows: 2.1.3.344

    • {{ACS::InvokeId}}: o ID de execução do comando. Para usar {{ACS::InvokeId}} como um parâmetro de ambiente integrado, certifique-se de que a versão do Agente do Cloud Assistant não seja anterior às seguintes versões:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

    • {{ACS::CommandId}}: o ID do comando. Quando você executa um comando chamando RunCommand e deseja usar {{ACS::CommandId}} como um parâmetro de ambiente integrado, certifique-se de que a versão do Agente do Cloud Assistant não seja anterior às seguintes versões:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

ZWNobyAxMjM=

WorkingDir

string

Não

O diretório onde o comando é executado na instância ECS. O diretório pode ter até 200 caracteres.

Valor padrão:

  • Instâncias Linux: o diretório home do usuário root, que é /root.

  • Instâncias Windows: o diretório onde o processo do Agente do Cloud Assistant está localizado, como C:\Windows\System32.

Nota

Se você definir este parâmetro para um diretório diferente, certifique-se de que o diretório exista na instância.

/home/user

Timeout

integer

Não

O período máximo de tempo limite para a execução do comando na instância ECS. Unidade: segundos. Se o comando não puder ser executado por algum motivo, ocorrerá um tempo limite. Após o tempo limite, o processo do comando é encerrado forçosamente cancelando o PID do comando.

Valor padrão: 60.

60

EnableParameter

boolean

Não

Especifica se o comando usa parâmetros personalizados.

Valor padrão: false.

false

ContentEncoding

string

Não

O modo de codificação do conteúdo do comando (CommandContent). Valores válidos:

  • PlainText: sem codificação. O conteúdo é transmitido em texto simples.

  • Base64: codificação Base64.

Valor padrão: Base64.

Nota

Se um valor inválido for especificado, ele será tratado como Base64.

PlainText

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 ClientToken suporta apenas caracteres ASCII e não pode exceder 64 caracteres. Para obter mais informações, consulte Como garantir a idempotência.

123e4567-e89b-12d3-a456-426655440000

ResourceGroupId

string

Não

O ID do grupo de recursos ao qual o comando pertence.

rg-123******

Launcher

string

Não

O programa de inicialização para a execução do script. O valor não pode exceder 1 KB de comprimento.

python3 -u {{ACS::ScriptFileName|Ext(".py")}}

Tag

array<object>

Não

As tags.

object

Não

As tags.

Key

string

Não

A chave da tag do comando. Valores válidos de N: 1 a 20. A chave da tag não pode ser uma string vazia.

Se você usar uma única tag para filtrar recursos, a contagem de recursos com a tag especificada não pode exceder 1.000. Se você usar várias tags para filtrar recursos, a contagem de recursos que possuem todas as tags especificadas não pode exceder 1.000. Se a contagem de recursos exceder 1.000, chame ListTagResources para consultar os recursos.

A chave da tag pode ter até 64 caracteres e não pode começar com aliyun ou acs:. Não pode conter http:// ou https://.

TestKey

Value

string

Não

O valor da tag do comando. Valores válidos de N: 1 a 20. O valor da tag pode ser uma string vazia.

O valor da tag pode ter até 128 caracteres e não pode conter http:// ou https://.

TestValue

Elementos de resposta

Elemento

Tipo

Descrição

Exemplo

object

CommandId

string

O ID do comando.

c-7d2a745b412b4601b2d47f6a768d****

RequestId

string

O ID da solicitação.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

Exemplos

Resposta de sucesso

JSON formato

{
  "CommandId": "c-7d2a745b412b4601b2d47f6a768d****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

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 CmdParam.EmptyKey You must specify the parameter names.
400 CmdParam.InvalidParamName Invalid parameter name. The name can contain only lowercase letters (a to z), uppercase letters (A to Z), numbers (0 to 9), hyphens (-), and underscores (_).
400 CmdContent.DecodeError The CommandContent can not be base64 decoded. O valor do parâmetro CommandContent especificado não pode ser decodificado em Base64. Verifique se o valor do parâmetro está correto.
400 InvalidParameter.WorkingDir The specified parameter WorkingDir is not valid. O parâmetro WorkingDir 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 CmdContent.ExceedLimit The length of the command content exceeds the upper limit. O conteúdo do seu comando é muito longo. Simplifique o conteúdo do seu comando.
403 CmdName.ExceedLimit The length of the command name exceeds the upper limit. O nome do comando excede o comprimento máximo.
403 CmdDesc.ExceedLimit The length of the command description exceeds the upper limit. O comprimento da descrição do comando excede o limite superior.
403 CmdCount.ExceedQuota The total number of commands in the current region exceeds the quota. O número de comandos do Cloud Assistant na região atual excedeu o limite.
403 CmdParamCount.ExceedLimit The maximum number of custom parameters is exceeded. O número de parâmetros personalizados no conteúdo do comando excede o limite superior.
403 CmdParamName.ExceedLimit The maximum length of a parameter name is exceeded. O nome do seu parâmetro personalizado excede o limite de comprimento.
403 Operation.Forbidden The operation is not permitted. A operação não é permitida.
403 InvalidStatus.ResourceGroup You cannot perform an operation on a resource group that is being created or deleted. As operações não são permitidas enquanto o grupo de recursos está sendo criado ou excluído.
403 InvalidParameterCharacter.CommandName The command Name contains illegal characters. O nome do comando contém caracteres inválidos.
403 InvalidParameterCharacter.CommandDescription The command Description contains illegal characters. A descrição do comando contém caracteres inválidos.
403 InvalidParameterCharacter.CommandWorkingDir The command WorkingDir contains illegal characters. O caminho de execução do comando contém caracteres inválidos.
403 InvalidLauncher.LengthLimitExceeded The length of the parameter Launcher exceeds the limit of 1 KB characters. O comprimento do parâmetro Launcher excede o limite de 1 KB.
403 InvalidTimeout.ExceedLimit The specified parameter Timeout exceeds the upper limit.
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 InvalidCmdType.NotFound The specified command type does not exist.
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 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. O grupo de recursos não foi encontrado nos registros.

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.