Etapa de PowerShell

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 8 min. de leitura

    • Execute scripts do PowerShell em máquinas remotas de sua instância ServiceNow por meio de MID Server.

    O PowerShell foi criado no Windows .NET Framework e foi projetado para controlar e automatizar a administração de máquinas e aplicações Windows. ServiceNow oferece suporte ao PowerShell 3.0 a 5.1. O PowerShell 3.0 não é compatível com o Windows 2003 Server.

    Nota:
    Esta etapa exige uma assinatura IntegrationHub. Para obter mais informações, consulte Programações jurídicas - Visão geral do IntegrationHub.

    Funções e disponibilidade

    Disponível como uma etapa de ação de Designer de ações. Usuários com a função action_designer podem criar uma ação personalizada com uma ou mais etapas de ação.

    Campos

    Campo Descrição
    Conexão Tipo de conexão a ser usado.
    • Definir conexão em linha: Defina as informações de conexão na etapa de ação.
    • Usar alias de conexão: Defina as informações de conexão usando a tabela de alias de conexão. Usar um alias elimina a necessidade de configurar várias credenciais e perfis de informações de conexão ao usar uma ação em vários ambientes. Da mesma forma, se as informações de conexão forem alteradas, você não precisará atualizar sua ação personalizada.

    Para saber mais sobre conexões e credenciais, consulte Introdução a credenciais, conexões e aliases.
    Alias de Conexão Registro de alias de conexão e credencial que o sistema usa para executar a etapa de ação. Usuários com a função de administrador ou flow_designer podem criar ou selecionar um registro de conexão associado. Usar um alias elimina a necessidade de configurar várias credenciais e perfis de informações de conexão ao usar uma ação em vários ambientes. Da mesma forma, se as informações de conexão forem alteradas, você não precisará atualizar sua ação personalizada. Para saber mais sobre conexões e credenciais, consulte credenciais, conexões e aliases. O valor da credencial é exibido como uma cápsula de dados de Senha (criptografada bidirecionalmente) no painel de dados.
    Nota:
    Este campo está disponível quando Usar Alias de Conexão é selecionado na lista Conexão.
    Alias de credencial Alias de credencial que o sistema usa para executar a etapa de ação. Usuários com a função de administrador ou flow_designer podem criar ou selecionar um registro de conexão associado. Usar um alias elimina a necessidade de configurar várias credenciais ao usar uma ação em vários ambientes. Da mesma forma, se as informações de credencial forem alteradas, você não precisará atualizar sua ação personalizada. Para saber mais sobre conexões e credenciais, consulte credenciais, conexões e aliases. O valor da credencial é exibido como uma cápsula de dados de Senha (criptografada bidirecionalmente) no painel de dados.
    Nota:
    Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão.
    Host Especifique o nome de domínio totalmente qualificado do host de destino em que o sistema executa a etapa de ação. Por exemplo, host.domain.com.
    Nota:
    Este campo só está visível quando a Conexão é Definir conexão em linha.
    Porta Especifique a porta de comunicação na qual o host de destino escuta as conexões. Por exemplo, 5985. Deixe em branco para usar a porta padrão.
    Nota:
    Este campo só está visível quando a Conexão é Definir conexão em linha.
    Seleção de MID Opção para selecionar o MID Server ou Cluster do MID específico.
    • Seleção automática do MID Server: seleciona o MID Server automaticamente.
    • MID Server específico: usa o MID Server selecionado.
    • Cluster do MID específico: usa o Cluster do MID selecionado.
    Este campo fica disponível quando Definir conexão em linha é selecionado na lista Conexão.
    Aplicação MID Especifique a aplicação que o MID Server deve suportar para se qualificar para seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte à aplicação selecionada. Se você usar uma cápsula de dados para este campo, a cápsula deverá fazer referência ao nome da aplicação MID, não ao registro da aplicação MID. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão e Selecionar automaticamente o MID Server é selecionado na lista Seleção de MID.
    Capacidades Capacidades que o MID Server deve oferecer para estar qualificado para seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte aos recursos selecionados. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão e Selecionar automaticamente o MID Server é selecionado na lista Seleção de MID.
    MID Server Cápsula de dados que contém uma referência sys_id a um registro MID Server [ecc_agent_list]. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão e MID Server específico é selecionado na lista Seleção de MID.
    Cluster do MID Cápsula de dados para o cluster MID que você deseja usar. Este campo fica disponível quando Definir conexão em linha é selecionado na lista Conexão, Cluster MID específico estiver selecionado na lista Seleção de MID.
    Tipo de comunicação Remota O local onde o script do PowerShell é executado, como o MID ou um servidor remoto.
    • Remoto explícito (mais comum): estabeleça uma conexão com e execute o script em um servidor remoto.
    • Remoting implícito (avançado): execute um script em um MID Server ao importar os módulos necessários de um servidor remoto. Se selecionado, defina os campos Prefixo do nome remoto e Módulos para importar. Para obter o desempenho ideal, importe somente os módulos necessários para a etapa. Se estiver em branco, todos os módulos disponíveis serão importados do servidor.
    • Execute em um MID Server ou faça com que seu script estabeleça uma sessão remota: execute um script diretamente em um MID Serverou defina especificações de comunicação remota no script. Este valor é o padrão.
    Nota:
    Para invocar uma função em um comando de script do PowerShell ou arquivo de script do PowerShell, o comando deve definir o bloco de parâmetros da função se a função tiver parâmetros de entrada. Este requisito se aplica à comunicação remota explícita e implícita. Para obter informações adicionais sobre o bloco de parâmetros, consulte a documentação da Microsoft sobre parâmetros do Windows PowerShell em https://technet.microsoft.com/.
    Prefixo do nome remoto O caminho do arquivo, excluindo nomes de arquivo, para os módulos a serem carregados do servidor remoto.
    Nota:
    Este campo só está visível quando o Tipo de comunicação remota for Comunicação remota implícita (Avançado).
    Módulos a serem importados A lista separada por vírgulas de módulos a serem importados do servidor remoto no caminho de arquivo definido.
    Nota:
    Este campo só está visível quando o Tipo de comunicação remota é Comunicação remota explícita (Mais comum) ou Comunicação remota implícita (Avançado).
    Testar etapa do PowerShell Botão para testar a credencial configurada para a etapa do PowerShell. Para obter mais informações, consulte Testar uma credencial para a etapa PowerShell.
    Tipo de script O tipo de script a ser executado no host do PowerShell.
    • Script em linha: insira o script a ser executado no campo Comando da etapa.
    • Arquivo de script do MID Server: selecione o script do PowerShell a ser executado na tabela MID Server Arquivos de script [ecc_agent_script_file]. Este é o valor padrão e separa a lógica de script da ação, permitindo que você atualize o script sem precisar modificar e reimplantar a ação.
    MID Server Script Script PowerShell predefinido da tabela [ MID Server Arquivos de script [ecc_agent_script_file].
    Nota:
    Este campo só estará disponível se o Tipo de script for Arquivo de script do MID Server.
    Caminho do script Caminho somente leitura para o script MID Server selecionado.
    Nota:
    Este campo só está visível quando o Tipo de script for Arquivo de script do MID Server.
    Variáveis de entrada Os pares de nome-valor opcionais que representam os valores das variáveis de script do PowerShell. Você pode usar entradas de ação e dados de outras etapas no script do PowerShell. Defina os seguintes campos para cada variável:
    • Nome: o nome da variável de script para a qual um valor será passado. O nome não pode corresponder a uma variável do PowerShell reservada ou proibida. Alguns nomes de variáveis são reservados para processamento interno e não devem ser usados como variáveis de entrada. Consulte Variáveis reservadas em variáveis de script do PowerShell.
    • Tipo: o tipo de variável do PowerShell. Selecione texto sem formatação, criptografado ou booliano. Se criptografado for selecionado, o valor aparecerá em texto sem formatação neste campo e só será criptografado quando passar para a Fila do ECC.
    • Valor: o valor a ser mapeado para a variável. Insira manualmente um valor ou arraste uma cápsula de dados para o campo.
    Comando O script do PowerShell em linha a ser executado no host de destino.
    Nota:
    Este campo só está visível quando o Tipo de script é Script embutido.

    Campos de avaliação de erro de ação

    Campo Descrição
    Se esta etapa falhar Opção para continuar executando a próxima etapa ou ir para a avaliação de erro. Para usar o código de status da etapa ou a mensagem para uma condição de erro de ação personalizada, consulte Avaliação de erro de ação.

    Variáveis de script do PowerShell

    Para acessar variáveis de entrada do campo Comando, você deve chamá-las usando uma sintaxe especial. A sintaxe usada depende do valor de uma propriedade do sistema. Se o tipo de comunicação remota for Executar em um MID Server ou seu script estabelecer uma sessão remota, algumas variáveis reservadas estarão disponíveis além das variáveis de entrada.

    Sintaxe de variável de entrada

    Por padrão, prefixe os nomes de variáveis com um caractere $. Por exemplo, se uma variável de entrada for chamada message, use $message para acessar a variável no script.

    Se o parâmetro mid.powershell.command.script.parameter_passing estiver definido como falso, prefixe o nome da variável com $env:SNC_. Por exemplo, se uma variável de entrada for chamada message, use $env:SNC_message para acessar a variável no script. Para saber mais sobre o parâmetro mid.powershell.command.script.parameter_passing, consulte Parâmetros do MID Server.

    Variáveis reservadas

    Quando o tipo de comunicação remota for Executar em um MID Server ou seu script estabelecer uma sessão remota, as seguintes variáveis estarão disponíveis para uso no script. Variáveis reservadas não podem ser usadas como nomes de variáveis de entrada personalizadas.

    Variável reservada Descrição
    $computador Endereço IP do host definido no registro do alias de conexão.
    $cred Objeto de credencial que contém as credenciais definidas no registro de conexão. Use esta variável com qualquer cmdlet do PowerShell que ofereça suporte ao parâmetro de credencial. Por exemplo, New-PSSession -credential $cred.
    $log_info Se a propriedade mid.property.powershell.log_info estiver definida como verdadeiro, adicionará informações de registro em log a um script do PowerShell.

    Os nomes de variáveis a seguir são reservados para processamento interno e não devem ser usados como variáveis de entrada.

    • script
    • useCred
    • isMid
    • isDiscovery
    • depurar
    • usuário
    • password
    • executionScriptDirectory
    • midScriptDirectory
    • hresult