InvokeCommand - : Central de Documentação do Alibaba Cloud

Notas de uso

As instâncias do ECS nas quais você deseja executar o comando do Cloud Assistant devem atender aos seguintes requisitos. Se várias instâncias do ECS forem especificadas e uma delas não atender aos requisitos para a execução do comando, a chamada falhará. Você deve especificar instâncias que atendam aos requisitos e chamar a operação InvokeCommand novamente.
- As instâncias devem estar no estado Em execução (Running). Você pode chamar a operação DescribeInstances para consultar os estados das instâncias.
- O Cloud Assistant Agent deve estar instalado nas instâncias. Para obter mais informações, consulte Instalar o Cloud Assistant Agent.
- Antes de executar comandos do PowerShell nas instâncias, verifique se as instâncias possuem o módulo PowerShell configurado.
O comando pode ser executado apenas uma vez nas instâncias.
O comando pode ser executado várias vezes nas instâncias com base em um agendamento.
- O agendamento é especificado pelo parâmetro Frequency. Os resultados de cada execução de um comando não afetam a próxima execução do comando.
- Se você deseja especificar um agendamento usando uma expressão cron, pode especificar um fuso horário com base nos requisitos do seu negócio. Se você não especificar um fuso horário, o agendamento será determinado pelo horário do sistema da instância. Verifique se o horário ou o fuso horário da instância atende aos requisitos do seu negócio. Para obter mais informações sobre fusos horários, consulte Configurar o serviço NTP para instâncias do ECS que executam CentOS 6 ou Configurar o serviço NTP para instâncias Windows.
  
  Para garantir que as tarefas agendadas possam ser executadas conforme esperado, verifique se a versão do Cloud Assistant Agent não é anterior às seguintes. Você pode configurar um comando para ser executado em um intervalo fixo com base em uma expressão de taxa, executado apenas uma vez em um horário especificado ou executado em horários designados com base em uma expressão cron. Se o código de erro ClientNeedUpgrade for retornado, você deverá atualizar o Cloud Assistant Agent para a versão mais recente. Para obter mais informações, consulte Atualizar ou desabilitar atualizações do Cloud Assistant Agent.
- Linux: 2.2.3.282
- Windows: 2.1.3.282
Os comandos podem falhar na execução devido a exceções de status da instância, exceções de rede ou exceções no Cloud Assistant Agent. Se um comando falhar na execução, nenhuma informação de execução será gerada. Para obter mais informações, consulte Verificar resultados da execução e solucionar problemas comuns.
Se você habilitar o recurso de parâmetro personalizado ao criar o comando, deverá especificar parâmetros personalizados (Parameters) para executar o comando.
Antes de executar um comando em instâncias, especialmente em instâncias novas, recomendamos que você chame a operação DescribeCloudAssistantStatus para consultar o estado do Cloud Assistant Agent instalado nas instâncias e verificar se o valor de retorno de CloudAssistantStatus é true.

Depuração

O OpenAPI Explorer calcula automaticamente o valor da assinatura. Para sua conveniência, recomendamos que você chame esta operação no OpenAPI Explorer. O OpenAPI Explorer gera dinamicamente o código de exemplo da operação para diferentes SDKs.

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
Action	String	Sim	InvokeCommand	A operação que você deseja realizar. Defina o valor como InvokeCommand.
RegionId	String	Sim	cn-hangzhou	O ID da região do comando. Você pode chamar a operação DescribeRegions para consultar a lista de regiões mais recente.
ResourceGroupId	String	Não	rg-bp67acfmxazb4p****	O ID do grupo de recursos ao qual atribuir as execuções do comando. Ao definir este parâmetro, observe os seguintes itens: As instâncias especificadas por InstanceId.N devem pertencer ao grupo de recursos especificado. Após a execução do comando, você pode chamar a operação DescribeInvocations ou DescribeInvocationResults com ResourceGroupId definido para consultar os resultados da execução no grupo de recursos especificado.
CommandId	String	Sim	c-e996287206324975b5fbe1d****	O ID do comando. Você pode chamar a operação DescribeCommands para consultar todos os IDs de comandos disponíveis. null Os comandos comuns do Cloud Assistant podem ser executados com base em seus nomes. Para obter mais informações, consulte Visualizar e executar comandos comuns do Cloud Assistant.
RepeatMode	String	Não	Once	Especifica como executar o comando. Valores válidos: Once: executa o comando imediatamente. Period: executa o comando de acordo com um agendamento. Se você definir este parâmetro como `Period`, deverá especificar `Frequency`. NextRebootOnly: executa o comando na próxima vez que a instância for iniciada. EveryReboot: executa o comando toda vez que a instância for iniciada. Valor padrão: Se você não especificar `Frequency`, o valor padrão é `Once`. Se você especificar `Frequency`, `Period` será usado como o valor de RepeatMode, independentemente de RepeatMode estar definido como Period. Observe os seguintes itens: Você pode chamar a operação StopInvocation para interromper as execuções pendentes ou agendadas do comando. Se você definir este parâmetro como `Period` ou `EveryReboot`, poderá definir `IncludeHistory` como true para chamar a operação DescribeInvocationResults para consultar os resultados de execuções agendadas históricas.
Timed	Boolean	Não	true	null Este parâmetro não tem efeito e não é mais utilizado.
Frequency	String	Não	0 /20 * * ?	O agendamento para executar o comando. Você pode configurar um comando para ser executado em um intervalo fixo com base em uma expressão de taxa, executado apenas uma vez em um horário especificado ou executado em horários designados com base em uma expressão cron. Para executar o comando em um intervalo fixo, use uma expressão de taxa para especificar o intervalo. Você pode especificar o intervalo em segundos, minutos, horas ou dias. Esta opção é adequada para cenários nos quais as tarefas precisam ser executadas em um intervalo fixo. Especifique o intervalo no seguinte formato: `rate(<Valor do intervalo de execução><Unidade do intervalo de execução>)`. Por exemplo, especifique `rate(5m)` para executar o comando a cada 5 minutos. Observe os seguintes limites ao definir um intervalo: O intervalo especificado pode variar de 60 segundos a 7 dias, mas deve ser maior que o período de tempo limite da tarefa agendada. O intervalo é o tempo decorrido entre duas execuções consecutivas. O intervalo é independente do tempo necessário para executar o comando uma vez. Por exemplo, suponha que você defina o intervalo como 5 minutos e que leve 2 minutos para executar o comando cada vez. Cada vez que o comando é executado, o sistema aguarda 3 minutos antes de executá-lo novamente. Uma tarefa não é executada imediatamente após ser criada. Por exemplo, suponha que você defina o intervalo como 5 minutos para uma tarefa. A tarefa começa a ser executada 5 minutos após ser criada. Para executar o comando apenas uma vez em um horário especificado, especifique um momento no tempo e um fuso horário. Especifique o momento no formato `at(yyyy-MM-dd HH:mm:ss <Fuso horário>)`, que indica `at(Ano-Mês-Dia Hora:Minuto:Segundo <Fuso horário>)`. Se você não especificar um fuso horário, o fuso horário UTC será usado por padrão. O fuso horário suporta os seguintes formatos: O nome do fuso horário. Exemplos: `Asia/Shanghai` e `America/Los_Angeles`. O deslocamento de horário em relação ao GMT. Exemplos: `GMT+8:00` (UTC+8) e `GMT-7:00` (UTC-7). Se você usar o formato GMT, não adicione zeros à esquerda no valor da hora. A abreviação do fuso horário. Somente UTC é suportado. Por exemplo, para configurar um comando para ser executado apenas uma vez às 13:15:30 em 6 de junho de 2022 (horário de Xangai), defina o horário como `at(2022-06-06 13:15:30 Asia/Shanghai)`. Para configurar um comando para ser executado apenas uma vez às 13:15:30 em 6 de junho de 2022 (UTC-7), defina o horário como `at(2022-06-06 13:15:30 GMT-7:00)`. Para executar um comando em horários específicos, use uma expressão cron para definir o agendamento. Especifique um agendamento no formato `<Expressão cron> <Fuso horário>`. A expressão cron está no formato `<segundos> <minutos> <horas> <dia do mês> <mês> <dia da semana> <ano (opcional)>`. O sistema calcula os horários de execução do comando com base na expressão cron e no fuso horário especificados e executa o comando conforme agendado. Se você não especificar um fuso horário, o fuso horário do sistema da instância na qual deseja executar o comando será usado por padrão. Para obter mais informações sobre expressões cron, consulte Expressões cron. O fuso horário suporta os seguintes formatos: O nome do fuso horário. Exemplos: `Asia/Shanghai` e `America/Los_Angeles`. O deslocamento de horário em relação ao GMT. Exemplos: `GMT+8:00` (UTC+8) e `GMT-7:00` (UTC-7). Se você usar o formato GMT, não adicione zeros à esquerda no valor da hora. A abreviação do fuso horário. Somente UTC é suportado. Por exemplo, para configurar um comando para ser executado às 10:15:00 todos os dias em 2022 (horário de Xangai), defina o agendamento como `0 15 10 ? * * 2022 Asia/Shanghai`. Para configurar um comando para ser executado a cada meia hora das 10:00:00 às 11:30:00 todos os dias em 2022 (UTC+8), defina o agendamento como `0 0/30 10-11 * ? 2022 GMT +8:00`. Para configurar um comando para ser executado a cada 5 minutos das 14:00:00 às 14:55:00 em todos os meses de outubro a cada dois anos a partir de 2022 em UTC, defina o agendamento como `0 0/5 14 * 10 ? 2022/2 UTC`. null O intervalo mínimo deve ser de 10 segundos ou mais e não pode ser menor que o período de tempo limite das execuções agendadas.
Parameters	Map	Não	{"name":"Jack", "accessKey":"LTAIdyv******aRY"}	Os pares de chave-valor dos parâmetros personalizados a serem passados quando o recurso de parâmetro personalizado está habilitado. Número de parâmetros personalizados: 0 a 10. As chaves em uma coleção Map podem ter até 64 caracteres e não podem ser strings vazias. Os valores em uma coleção Map podem ser strings vazias. O tamanho dos parâmetros personalizados codificados em Base64 e do conteúdo original do comando não pode exceder 18 KB. Os nomes dos parâmetros personalizados especificados no valor de Parameters devem estar incluídos nos parâmetros personalizados especificados quando você criou o comando. Você pode usar strings vazias para representar os parâmetros que não são passados. Se você deseja desabilitar o recurso de parâmetro personalizado, pode deixar este parâmetro vazio.
Username	String	Não	test	O nome de usuário a ser usado para executar o comando nas instâncias. O nome de usuário pode ter até 255 caracteres. Para instâncias Linux, o nome de usuário root é usado por padrão. Para instâncias Windows, o nome de usuário System é usado por padrão. Você também pode especificar outros nomes de usuário que já existam nas instâncias para executar o comando. Por questões de segurança, recomendamos que você execute comandos do Cloud Assistant como um usuário regular. Para obter mais informações, consulte Configurar um usuário regular para executar comandos do Cloud Assistant.
WindowsPasswordName	String	Não	axtSecretPassword	O nome da senha a ser usada para executar o comando em instâncias Windows. O nome pode ter até 255 caracteres. Se você não deseja usar o usuário padrão System para executar o comando em instâncias Windows, especifique tanto WindowsPasswordName quanto `Username`. Para mitigar o risco de vazamento de senhas, a senha é armazenada em texto simples no Operation Orchestration Service (OOS) Parameter Store, e apenas o nome da senha é passado usando WindowsPasswordName. Para obter mais informações, consulte Criptografar parâmetros e Configurar um usuário regular para executar comandos do Cloud Assistant. null Se você usar o nome de usuário root para instâncias Linux ou o nome de usuário System para instâncias Windows para executar o comando, não será necessário especificar WindowsPasswordName.
InstanceId.N	String	Não	i-bp185dy2o3o6n****	O ID da instância N na qual executar o comando. Você pode especificar até 50 IDs de instância em cada solicitação. Valores válidos de N: 1 a 50.
ContainerId	String	Não	ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****	O ID do contêiner. Somente strings hexadecimais de 64 bits são suportadas. Você pode usar IDs de contêiner prefixados com `docker://`, `containerd://` ou `cri-o://` para especificar runtimes de contêiner. Observe os seguintes itens: Se você especificar este parâmetro, o Cloud Assistant executará scripts no contêiner especificado da instância. Se você especificar este parâmetro, verifique se a versão do Cloud Assistant Agent instalada nas instâncias Linux é 2.2.3.344 ou posterior. Para obter informações sobre como consultar a versão do Cloud Assistant Agent, consulte Instalar o Cloud Assistant Agent. Para obter informações sobre como atualizar o Cloud Assistant Agent, consulte Atualizar ou desabilitar atualizações do Cloud Assistant Agent. Se você especificar este parâmetro, `Username` especificado em uma solicitação para chamar esta operação e `WorkingDir` especificado em uma solicitação para chamar a operação CreateCommand não terão efeito. Você pode executar o comando apenas no diretório de trabalho padrão do contêiner usando o usuário padrão do contêiner. Para obter mais informações, consulte Usar o Cloud Assistant para executar comandos em contêineres. Se você especificar este parâmetro, somente scripts shell poderão ser executados em contêineres Linux. Você não pode adicionar um comando no formato semelhante a `#!/usr/bin/python` no início de um script para especificar um interpretador de script. Para obter mais informações, consulte Usar o Cloud Assistant para executar comandos em contêineres.
ContainerName	String	Não	test-container	O nome do contêiner. Observe os seguintes itens: Se você especificar este parâmetro, o Cloud Assistant executará scripts no contêiner especificado da instância. Se você especificar este parâmetro, verifique se a versão do Cloud Assistant Agent instalada nas instâncias Linux é 2.2.3.344 ou posterior. Para obter informações sobre como consultar a versão do Cloud Assistant Agent, consulte Instalar o Cloud Assistant Agent. Para obter informações sobre como atualizar o Cloud Assistant Agent, consulte Atualizar ou desabilitar atualizações do Cloud Assistant Agent. Se você especificar este parâmetro, `Username` especificado em uma solicitação para chamar esta operação e `WorkingDir` especificado em uma solicitação para chamar a operação CreateCommand não terão efeito. Você pode executar o comando apenas no diretório de trabalho padrão do contêiner usando o usuário padrão do contêiner. Para obter mais informações, consulte Usar o Cloud Assistant para executar comandos em contêineres. Se você especificar este parâmetro, somente scripts shell poderão ser executados em contêineres Linux. Você não pode adicionar um comando no formato semelhante a `#!/usr/bin/python` no início de um script para especificar um interpretador de script. Para obter mais informações, consulte Usar o Cloud Assistant para executar comandos em contêineres.
Timeout	Long	Não	60	O período de tempo limite para a execução do comando. Unidade: segundos. O período de tempo limite não pode ser inferior a 10 segundos. Um erro de tempo limite ocorre se o comando não puder ser executado porque o processo ficou lento ou porque um módulo específico ou o Cloud Assistant Agent não existe. Quando o período de tempo limite especificado termina, o processo do comando é encerrado forçosamente. Se você não especificar este parâmetro, o período de tempo limite especificado quando o comando foi criado será usado. Este período de tempo limite é aplicável apenas a esta execução. O período de tempo limite do comando não é modificado.
Tag.N.Key	String	Não	TestKey	A chave da tag N a ser adicionada à tarefa de comando. Valores válidos de N: 1 a 20. A chave da tag não pode ser uma string vazia. Se uma única tag for especificada para consultar recursos, até 1.000 recursos com essa tag poderão ser exibidos na resposta. Se várias tags forem especificadas para consultar recursos, até 1.000 recursos com todas essas tags poderão ser exibidos na resposta. Para consultar mais de 1.000 recursos com tags especificadas, chame a operação ListTagResources. A chave da tag pode ter até 64 caracteres e não pode começar com `acs:` ou `aliyun`. Não pode conter `http://` ou `https://`.
Tag.N.Value	String	Não	TestValue	O valor da tag N a ser adicionada à tarefa de 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://`.
ClientToken	String	Não	123e4567-e89b-12d3-a456-42665544****	O token do cliente usado para garantir a idempotência da solicitação. Você pode usar o cliente para gerar o token, mas deve garantir que o token seja único entre diferentes solicitações. O token pode conter apenas caracteres ASCII e não pode exceder 64 caracteres. Para obter mais informações, consulte Como garantir a idempotência.

Parâmetros de resposta

Parâmetro	Tipo	Exemplo	Descrição
InvokeId	String	t-7d2a745b412b4601b2d47f6a768d****	O ID da tarefa de comando.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****	O ID da solicitação.

Exemplos

Exemplos de solicitações

http(s)://ecs.aliyuncs.com/?Action=InvokeCommand
&CommandId=c-e996287206324975b5fbe1d****
&InstanceId.1=i-bp185dy2o3o6n****
&RegionId=cn-hangzhou
&Timed=true
&Frequency=0 */20 * * * *
&Parameters={"name":"Jack", "accessKey":"LTAIdyv******aRY"}
&Username=root
&<Common request parameters>

Exemplos de respostas bem-sucedidas

Formato XML

HTTP/1.1 200 OK
Content-Type:application/xml

<InvokeCommandResponse>
    <InvokeId>t-7d2a745b412b4601b2d47f6a768d****</InvokeId>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
</InvokeCommandResponse>

Formato JSON

HTTP/1.1 200 OK
Content-Type:application/json

{
  "InvokeId" : "t-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.	Esta operação não pode ser realizada na região especificada. Verifique se o parâmetro RegionId é válido.
400	MissingParam.InstanceId	The parameter instanceId is missing or empty.	InstanceId.N é obrigatório.
400	InvalidContainerId.Malformed	The specified parameter ContainerId is not valid.	Valor de ContainerId inválido.
400	InvalidContainerName.Malformed	The specified parameter ContainerName is not valid.	Valor de ContainerName inválido.
400	InvalidClientToken.Malformed	The specified parameter clientToken is not valid.	Valor de ClientToken inválido.
400	InvalidInstance.NotMatch	The specified instance type does not match the command.	O comando especificado não pode ser executado na instância especificada. Verifique se o estado da instância atende às condições para executar o comando do Cloud Assistant.
400	MissingParam.Frequency	The frequency must be specified when you create a timed task.	O parâmetro Frequency é obrigatório ao criar uma tarefa de comando agendada.
400	InvalidParam.Frequency	The specified frequency is invalid.	Valor de Frequency inválido. Verifique se o valor de Frequency especificado é válido.
400	Parameter.MissingValue	The parameter value of this command is required.	O parâmetro é obrigatório.
400	Parameter.Disabled	Parameters cannot be passed in when the command customization function is disabled.	O parâmetro Parameters foi especificado quando o recurso de parâmetro personalizado está desabilitado.
400	InvalidParameter.Parameters	The specified parameter Parameters is not valid.	Valor de Parameters inválido.
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	O número máximo de IDs de instância foi excedido.
403	Invocation.ExceedQuota	The invocation quota in the current region has been reached for today.	O número máximo diário de execuções de comando na região atual foi excedido.
403	ParameterCount.ExceedLimit	The maximum number of parameters is exceeded.	O número máximo de parâmetros personalizados especificados foi excedido.
403	ParameterKey.ExceedLimit	The maximum length of a parameter name is exceeded.	A chave de um parâmetro personalizado excede 64 caracteres.
403	CmdContent.ExceedLimit	The maximum length of a command is exceeded.	O comprimento máximo do comando foi excedido. Reduza o tamanho do seu comando.
403	ParameterKey.Duplicate	Parameter names cannot be duplicated.	Um parâmetro com o mesmo nome já existe. Os nomes dos parâmetros devem ser únicos.
403	Parameter.NotMatched	The passed-in parameters do not match the parameters defined when you created the command.	Os parâmetros personalizados passados não correspondem aos especificados quando o comando foi criado.
403	ParameterType.NotSupported	The type of parameter value is not supported.	Tipo de parâmetro personalizado inválido.
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	O comprimento máximo do nome de usuário foi excedido.
403	WindowsPasswordName.ExceedLimit	The length of the WindowsPasswordName exceeds the upper limit.	O comprimento máximo de WindowsPasswordName foi excedido.
403	WindowsPasswordName.Missed	WindowsPasswordName must be specified when you create a Windows task.	WindowsPasswordName é obrigatório.
403	ParameterStore.InvalidParameters	The parameter is invalid in Parameter Store.	O parâmetro personalizado no formato {{oos:?}} não foi encontrado.
403	Operation.Forbidden	The operation is not permitted.	A operação não é suportada.
403	IdempotentParameterMismatch	The specified parameter has changed while using an already used clientToken.	O token do cliente já está em uso.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	Uma solicitação idempotente anterior está sendo processada. Tente novamente mais tarde.
404	InvalidRepeatMode.NotFound	The specified repeat mode does not exist.	Valor de RepeatMode inválido.
404	InvalidInstance.NotFound	The specified instance does not exist.	A instância especificada não foi encontrada.
404	InvalidCmdId.NotFound	The specified command ID does not exist.	Valor de CommandId inválido. Você pode chamar a operação DescribeCommands para consultar todos os IDs de comandos disponíveis.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	O ID do grupo de recursos não foi encontrado.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	Ocorreu um erro ao enviar a solicitação. Tente novamente mais tarde.

Para obter uma lista de códigos de erro, consulte Códigos de erro do serviço.