Invoke-WSManAction

Módulo:

Microsoft.WSMan.Management

Invoca uma ação no objeto especificado pelo URI de recurso e os seletores.

Sintaxe

Invoke-WSManAction
      [-Action] <String>
      [-ConnectionURI <Uri>]
      [-FilePath <String>]
      [-OptionSet <Hashtable>]
      [[-SelectorSet] <Hashtable>]
      [-SessionOption <SessionOption>]
      [-ValueSet <Hashtable>]
      [-ResourceURI] <Uri>
      [-Credential <PSCredential>]
      [-Authentication <AuthenticationMechanism>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Invoke-WSManAction
      [-Action] <String>
      [-ApplicationName <String>]
      [-ComputerName <String>]
      [-FilePath <String>]
      [-OptionSet <Hashtable>]
      [-Port <Int32>]
      [[-SelectorSet] <Hashtable>]
      [-SessionOption <SessionOption>]
      [-UseSSL]
      [-ValueSet <Hashtable>]
      [-ResourceURI] <Uri>
      [-Credential <PSCredential>]
      [-Authentication <AuthenticationMechanism>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Description

O Invoke-WSManAction executa uma ação no objeto especificado por RESOURCE_URI, em que os parâmetros são especificados por pares de valores-chave.

Este cmdlet usa a camada de conexão/transporte do WSMan para realizar a ação.

Exemplos

Exemplo 1: Invocar um método

Invoke-WSManAction -Action startservice -ResourceURI wmicimv2/win32_service  -SelectorSet @{name="spooler"} -Authentication default

xsi         : http://www.w3.org/2001/XMLSchema-instance
p           : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim         : http://schemas.dmtf.org/wbem/wscim/1/common
lang        : en-US
ReturnValue : 0

Este comando chama o método StartService da instância da classe WMI Win32_Service que corresponde ao serviço de Spooler.

O valor de retorno indica se a ação foi ou não bem-sucedida. Nesse caso, um valor de retorno 0 indica êxito. Um valor de retorno de 5 indica que o serviço já foi iniciado.

Exemplo 2: Invocar um método

Invoke-WSManAction -Action stopservice -ResourceURI wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath:input.xml -Authentication default

xsi         : http://www.w3.org/2001/XMLSchema-instance
p           : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim         : http://schemas.dmtf.org/wbem/wscim/1/common
lang        : en-US
ReturnValue : 0

Esse comando chama o método StopService no serviço Spooler usando a entrada de um arquivo. O arquivo, Input.xml, contém o seguinte conteúdo:

<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />

O valor de retorno indica se a ação foi ou não bem-sucedida. Nesse caso, um valor de retorno 0 indica êxito. Um valor de retorno de 5 indica que o serviço já foi iniciado.

Exemplo 3: Invocar um método com valores de parâmetro especificados

Invoke-WSManAction -Action create -ResourceURI wmicimv2/win32_process -ValueSet @{commandline="notepad.exe";currentdirectory="C:\"}

xsi         : http://www.w3.org/2001/XMLSchema-instance
p           : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Process
cim         : http://schemas.dmtf.org/wbem/wscim/1/common
lang        : en-US
ProcessId   : 6356
ReturnValue : 0

Esse comando chama o método Create da classe Win32_Process. Ele passa o método dois valores Notepad.exe de parâmetro e C:\. Como resultado, um novo processo é criado para executar o Bloco de Notas e o diretório atual do novo processo é definido como C:\.

Exemplo 4: Invocar um método em um computador remoto

Invoke-WSManAction -Action startservice -ResourceURI wmicimv2/win32_service  -SelectorSet @{name="spooler"} -ComputerName server01 -Authentication default

xsi         : http://www.w3.org/2001/XMLSchema-instance
p           : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim         : http://schemas.dmtf.org/wbem/wscim/1/common
lang        : en-US
ReturnValue : 0

Este comando chama o método StartService da instância da classe WMI Win32_Service que corresponde ao serviço de Spooler. Como o parâmetro ComputerName está especificado, o comando é executado no computador remoto servidor01.

O valor de retorno indica se a ação foi ou não bem-sucedida. Nesse caso, um valor de retorno 0 indica êxito. Um valor de retorno de 5 indica que o serviço já foi iniciado.

Parâmetros

-Action

Especifica o método a ser executado no objeto de gerenciamento especificado pelo ResourceURI e pelos seletores.

Tipo:	String
Cargo:	1
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ApplicationName

Especifica o nome do aplicativo na conexão. O valor padrão do parâmetro ApplicationName é WSMAN. O identificador completo para o ponto de extremidade remoto é no seguinte formato:

<Transport>://<Server>:<Port>/<ApplicationName>

Por exemplo:

http://server01:8080/WSMAN

Os Serviços de Informações da Internet (IIS), que hospedam a sessão, encaminham solicitações com esse ponto de extremidade para o aplicativo especificado. A configuração padrão de "WSMAN" é adequada para a maioria dos usos. Este parâmetro é projetado para ser utilizado quando diversos computadores estabelecem conexões remotas com um computador que esteja executando o Windows PowerShell. Nesse caso, o IIS hospeda o Web Services for Management (WS-Management) para maior eficiência.

Tipo:	String
Cargo:	Named
Valor padrão:	Wsman
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Authentication

Especifica o mecanismo de autenticação a ser usado no servidor. Os valores possíveis são:

• Basic - Básico é um esquema no qual o nome de usuário e a senha são enviados em texto não criptografado para o servidor ou proxy.
• Default - Use o método de autenticação implementado pelo protocolo WS-Management. Esse é o padrão.
• Digest - Digest é um esquema de desafio-resposta que usa uma cadeia de caracteres de dados especificada pelo servidor para o desafio.
• Kerberos - O computador cliente e o servidor se autenticam mutuamente usando certificados Kerberos.
• Negotiate - Negociar é um esquema de desafio-resposta que negocia com o servidor ou proxy para determinar o esquema a ser usado para autenticação. Por exemplo, esse valor de parâmetro permite uma negociação para determinar se o protocolo Kerberos ou NTLM será utilizado.
• CredSSP - Use a autenticação do Provedor de Suporte de Segurança de Credenciais (CredSSP), que permite ao usuário delegar credenciais. Esta opção foi criada para os comandos executados em um computador remoto, mas coletam dados ou executam comandos adicionais em outros computadores remotos.

Cuidado

O CredSSP delega as credenciais do usuário do computador local para um computador remoto. Essa prática aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, no momento em que as credenciais forem passadas a ele essas credenciais poderão ser usadas para controlar a sessão de rede.

Tipo:	AuthenticationMechanism
Aliases:	auth, am
Valores aceitos:	None, Default, Digest, Negotiate, Basic, Kerberos, ClientCertificate, Credssp
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa ação. Insira a impressão digital do certificado.

Certificados digitais são empregados na autenticação de clientes baseada em certificados. Eles podem ser mapeados somente para contas de usuário local; eles não funcionam com contas de domínio.

Para obter uma impressão digital do certificado, use o Get-Item comando ou Get-ChildItem na unidade Windows PowerShell Cert:.

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ComputerName

Especifica o computador no qual se deseja executar a operação de gerenciamento. O valor pode ser um nome de domínio totalmente qualificado, um nome NetBIOS ou um endereço IP. Use o nome do computador local, use localhost ou use um ponto (.) para especificar o computador local. O computador local é o padrão. Quando o computador remoto está em um domínio diferente do usuário, deve-se usar um nome de domínio totalmente qualificado. É possível redirecionar um valor desse parâmetro para o cmdlet.

Tipo:	String
Aliases:	cn
Cargo:	Named
Valor padrão:	Localhost
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ConnectionURI

Especifica o ponto de extremidade de conexão. O formato dessa cadeia de caracteres é:

<Transport>://<Server>:<Port>/<ApplicationName>

A seguinte cadeia de caracteres é um valor formatado corretamente para este parâmetro:

http://Server01:8080/WSMAN

O URI deve ser totalmente qualificado.

Tipo:	Uri
Aliases:	CURI, CU
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Credential

Especifica uma conta de usuário que tem permissão para executar esta ação. O padrão é o usuário atual. Digite um nome de usuário, como "Usuário01", "Domínio01\Usuário01" ou User@Domain.com. Ou insira um objeto PSCredential, como um retornado pelo Get-Credential cmdlet. Quando você digitar um nome de usuário, uma senha será solicitada.

Tipo:	PSCredential
Aliases:	cred, c
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-FilePath

Especifica o caminho de um arquivo usado para atualizar um recurso de gerenciamento. Você pode especificar o recurso de gerenciamento usando os parâmetros ResourceURI e SelectorSet. Por exemplo, o comando a seguir usa o parâmetro FilePath:

Invoke-WSManAction -Action stopservice -ResourceUri wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath c:\input.xml -Authentication default

Esse comando chama o método StopService no serviço Spooler usando a entrada de um arquivo. O arquivo, Input.xml, contém o seguinte conteúdo:

<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-OptionSet

Passa um conjunto de opções para um serviço para modificar ou refinar a natureza da solicitação. Elas são semelhantes às opções usadas nos shells de linha de comando porque são específicas para o serviço. Qualquer número de opções pode ser especificado.

O exemplo a seguir demonstra a sintaxe que passa os valores 1, 2 e 3 para os parâmetros a, b e c:

-OptionSet @{a=1;b=2;c=3}

Tipo:	Hashtable
Aliases:	os
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-Port

Especifica a porta a ser usada quando o cliente se conecta ao serviço WinRM. Quando o transporte é HTTP, a porta padrão é 80. Quando o transporte é HTTPS, a porta padrão é 443. Quando você usa HTTPS como o transporte, o valor do parâmetro ComputerName deve corresponder ao CN (nome comum) do certificado do servidor. No entanto, se o parâmetro SkipCNCheck for especificado como parte do parâmetro SessionOption, então o nome comum do certificado do servidor não precisará corresponder ao nome de host do servidor. O parâmetro SkipCNCheck deve ser utilizado apenas para computadores confiáveis.

Tipo:	Int32
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ResourceURI

Contém o Uniform Resource Identifier (URI) da instância ou classe do recurso. O URI é utilizado para identificar um tipo específico de recurso, como discos ou processos em um computador.

Um URI consiste em um prefixo e um caminho para um recurso. Por exemplo:

http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk

http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor

Tipo:	Uri
Aliases:	ruri
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-SelectorSet

Especifica um conjunto de pares de valor que são utilizados para selecionar instâncias do recurso de gerenciamento específico. SelectorSet é usado quando existe mais de uma instância do recurso. O valor de SelectorSet deve ser uma tabela de hash.

O exemplo a seguir mostra como inserir um valor para esse parâmetro:

-SelectorSet @{Name="WinRM";ID="yyy"}

Tipo:	Hashtable
Cargo:	2
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-SessionOption

Define um conjunto de opções estendidas para a sessão do WS-Management. Insira um objeto SessionOption que você cria usando o New-WSManSessionOption cmdlet. Para obter mais informações sobre as opções disponíveis, consulte New-WSManSessionOption.

Tipo:	SessionOption
Aliases:	so
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-UseSSL

Especifica que o protocolo SSL (Secure Sockets Layer) é usado para estabelecer uma conexão com o computador remoto. Por padrão, SSL não é usado.

O WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. O parâmetro UseSSL permite especificar a proteção adicional de HTTPS em vez de HTTP. Se o SSL não estiver disponível na porta utilizada para a conexão e o parâmetro for especificado, o comando falhará.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ValueSet

Especifica uma tabela de hash que ajuda a modificar um recurso de gerenciamento. Você especifica o recurso de gerenciamento usando os parâmetros ResourceURI e SelectorSet . O valor do parâmetro ValueSet deve ser uma tabela de hash.

Tipo:	Hashtable
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

XmlElement

Esse cmdlet retorna o resultado da operação como um objeto XmlElement .

Links Relacionados

• Invoke-WmiMethod
• Connect-WSMan
• Disable-WSManCredSSP
• Disconnect-WSMan
• Enable-WSManCredSSP
• Get-WSManCredSSP
• Get-WSManInstance
• New-WSManInstance
• New-WSManSessionOption
• Remove-WSManInstance
• Set-WSManInstance
• Set-WSManQuickConfig
• Test-WSMan