Criar e executar scripts do PowerShell a partir do console do Configuration Manager

Aplica-se a: Configuration Manager (branch atual)

O Configuration Manager tem uma capacidade integrada de executar scripts do PowerShell. O PowerShell tem a vantagem de criar scripts sofisticados e automatizados que são compreendidos e compartilhados com uma comunidade maior. Os scripts simplificam a criação de ferramentas personalizadas para administrar software e permitem que você realize tarefas mundanas rapidamente, permitindo que você faça trabalhos grandes com mais facilidade e consistência.

Observação

Na versão 2006 e anterior, o Configuration Manager não habilita esse recurso opcional por padrão. É necessário habilitar esse recurso antes de usá-lo. Para obter mais informações, consulte Habilitar recursos opcionais de atualizações.

Com essa integração no Configuration Manager, você pode usar a funcionalidade Executar Scripts para fazer o seguinte:

  • Crie e edite scripts para uso com o Configuration Manager.
  • Gerencie o uso de scripts por meio de funções e escopos de segurança.
  • Suporte de pasta para scripts.
  • Execute scripts em coleções ou em computadores Windows gerenciados locais individuais.
  • Agende o tempo de execução de scripts em UTC em coleções ou computadores Windows gerenciados locais individuais.
  • Obtenha resultados de script rapidamente agregados de dispositivos cliente.
  • Monitore a execução do script e exiba os resultados do relatório da saída do script.

Aviso

  • Dado o poder dos scripts, lembramos que você deve ser intencional e cuidadoso com seu uso. Construímos salvaguardas adicionais para ajudá-lo; Funções e escopos segregados. Certifique-se de validar a precisão dos scripts antes de executá-los e confirme se eles são de uma fonte confiável, para evitar a execução indesejada de scripts. Preste atenção a caracteres estendidos ou outra ofuscação e eduque-se sobre como proteger os scripts. Saiba mais sobre a segurança do script do PowerShell
  • Determinados softwares antimalware podem disparar inadvertidamente eventos nos recursos do Configuration Manager Run Scripts ou CMPipot. É recomendável excluir %windir%\CCM\ScriptStore para que o software antimalware permita que esses recursos sejam executados sem interferência.

Pré-requisitos

  • Para executar scripts do PowerShell, o cliente deve executar o PowerShell versão 3.0 ou posterior. No entanto, se um script executado contiver funcionalidades de uma versão posterior do PowerShell, o cliente no qual você executará o script deverá estar executando essa versão do PowerShell.
  • Os clientes do Configuration Manager devem estar executando o cliente da versão 1706 ou posterior para executar scripts.
  • Para usar scripts, você deve ser membro da função de segurança apropriada do Configuration Manager.
  • Para importar e criar scripts – Sua conta deve ter permissões Criar para Scripts SMS.
  • Para aprovar ou negar scripts - Sua conta deve ter permissões de aprovação para scripts SMS.
  • Para executar scripts: sua conta deve ter permissões de Executar Script para Coleções.

Para obter mais informações sobre funções de segurança do Configuration Manager:
Escopos de segurança para scripts
de execuçãoFunções de segurança para scripts
de execução Fundamentos da administração baseada em funções.

Limitações

Atualmente, o recurso Executar Scripts dá suporte a:

  • Idiomas de script: PowerShell
  • Tipos de parâmetro: inteiro, cadeia de caracteres e lista.

Aviso

Lembre-se de que, ao usar parâmetros, ele abre uma área de superfície para um possível risco de ataque de injeção do PowerShell. Há várias maneiras de atenuar e contornar esse problema, como usar expressões regulares para validar a entrada de parâmetros ou usar parâmetros predefinidos. Uma prática recomendada comum é não incluir segredos nos scripts do PowerShell (sem senhas etc.). Saiba mais sobre a segurança de scripts do PowerShell

Executar autores e aprovadores de scripts

Executar Scripts usa o conceito de autores de script e aprovadores de script como funções separadas para implementação e execução de um script. Ter as funções de autor e aprovador separadas permite uma importante marca de processo para a poderosa ferramenta que é Executar Scripts. Há uma função adicional de executores de script que permite a execução de scripts, mas não a criação ou aprovação de scripts. Consulte Criar funções de segurança para scripts.

Scripts, funções, controle,

Por padrão, os usuários não podem aprovar um script de sua autoria. Como os scripts são poderosos, versáteis e potencialmente implantados em muitos dispositivos, você pode separar as funções entre a pessoa que cria o script e a pessoa que o aprova. Essas funções fornecem um nível adicional de segurança contra a execução de um script sem supervisão. Você pode desativar a aprovação secundária para facilitar os testes.

Aprovar ou negar um script

Os scripts devem ser aprovados, pela função de aprovador de script , antes de serem executados. Para aprovar um script:

  1. No console do Configuration Manager, clique em Biblioteca de Software.
  2. No espaço de trabalho Biblioteca de Software , clique em Scripts.
  3. Na lista Script , escolha o script que você deseja aprovar ou negar e, em seguida, na guia Página Inicial , no grupo Script , clique em Aprovar/Negar.
  4. Na caixa de diálogo Aprovar ou negar script , selecione Aprovar ou Negar para o script. Opcionalmente, insira um comentário sobre sua decisão. Se você negar um script, ele não poderá ser executado em dispositivos cliente.
    Script - Aprovação
  5. Conclua o assistente. Na lista Script , você verá a coluna Estado de Aprovação mudar dependendo da ação realizada.

Permitir que os usuários aprovem seus próprios scripts

Essa aprovação é usada principalmente para a fase de teste do desenvolvimento do script.

  1. No console do Configuration Manager, clique em Administração.
  2. No espaço de trabalho Administração , expanda Configuração do Site e clique em Sites.
  3. Na lista de sites, escolha seu site e, em seguida, na guia Página Inicial , no grupo Sites , clique em Configurações de Hierarquia.
  4. Na guia Geral da caixa de diálogo Propriedades das Configurações de Hierarquia , desmarque a caixa de seleção Os autores de script exigem aprovador de script adicional.

Importante

Como prática recomendada, você não deve permitir que um autor de script aprove seus próprios scripts. Ele só deve ser permitido em um ambiente de laboratório. Considere cuidadosamente o impacto potencial da alteração dessa configuração em um ambiente de produção.

Escopos de segurança

O recurso Executar Scripts usa escopos de segurança, um recurso existente do Configuration Manager, para controlar a criação e a execução de scripts por meio da atribuição de marcas que representam grupos de usuários. Para obter mais informações sobre como usar escopos de segurança, consulte Configurar administração baseada em função para o Configuration Manager.

Criar direitos de acesso para scripts

As três funções de segurança usadas para executar scripts não são criadas por padrão no Configuration Manager. Para criar as funções de executores de script, autores de scripts e aprovadores de scripts, siga as etapas descritas.

  1. No console do Configuration Manager, acesse Administração>Segurança>Funções de segurança
  2. Clique com o botão direito do mouse em uma função e clique em Copiar. A função que você copia tem permissões já atribuídas. Certifique-se de obter apenas as permissões desejadas.
  3. Dê à função personalizada um Nome e uma Descrição.
  4. Atribua ao direito de acesso as permissões descritas abaixo.

Permissões de acesso de segurança

Nome da função: Execução de scripts

  • Descrição: essas permissões permitem que essa função execute apenas scripts que foram criados e aprovados anteriormente por outras funções.
  • Permissões: Verifique se os itens a seguir estão definidos como Sim.
Categoria Permissão Estado
Coleção Executar script Sim
Site Leitura Sim
SMS Scripts Leitura Sim

Nome da função: Autores de script

  • Descrição: essas permissões permitem que essa função crie scripts, mas não podem aprová-los ou executá-los.
  • Permissões: verifique se as permissões a seguir estão definidas.
Categoria Permissão Estado
Coleção Executar script Não
Site Leitura Sim
SMS Scripts Criar Sim
SMS Scripts Leitura Sim
SMS Scripts Excluir Sim
SMS Scripts Modificar Sim

Nome da função: Aprovadores de Script

  • Descrição: essas permissões permitem que essa função aprove scripts, mas não podem criá-los ou executá-los.
  • Permissões: Verifique se as permissões a seguir estão definidas.
Categoria Permissão Estado
Coleção Executar script Não
Site Leitura Sim
SMS Scripts Leitura Sim
SMS Scripts Aprovar Sim
SMS Scripts Modificar Sim

Exemplo de permissões de scripts SMS para a função de autores de script

Exemplo de permissões de scripts SMS para a função de autores de script

Suporte de pasta para scripts

A partir da versão 2403, você pode organizar scripts usando pastas. Essa alteração permite uma melhor categorização e gerenciamento de scripts.

Abra o console do Configuration Manager e vá para o espaço de trabalho Biblioteca de Software. Na faixa de opções ou no menu de clique com o botão direito do mouse, em Scripts, selecione uma das seguintes opções:

  • Criar pasta
  • Excluir Pasta
  • Renomear pasta
  • Mover pastas
  • Definir Escopos de Segurança

Criar um script

  1. No console do Configuration Manager, clique em Biblioteca de Software.
  2. No espaço de trabalho Biblioteca de Software , clique em Scripts.
  3. Na guia Página Inicial , no grupo Criar , clique em Criar Script.
  4. Na página Script do assistente Criar Script , defina as seguintes configurações:
    • Nome do script - Insira um nome para o script. Embora você possa criar vários scripts com o mesmo nome, o uso de nomes duplicados torna mais difícil encontrar o script necessário no console do Configuration Manager.
    • Linguagem de script – atualmente, há suporte apenas para scripts do PowerShell.
    • Importar - Importa um script do PowerShell para o console. O script é exibido no campo Script .
    • Limpar - Remove o script atual do campo Script.
    • Script - Exibe o script importado no momento. Você pode editar o script neste campo conforme necessário.
  5. Conclua o assistente. O novo script é exibido na lista Script com um status de Aguardando aprovação. Antes de executar esse script em dispositivos cliente, você deve aprová-lo.

Importante

Evite executar scripts de uma reinicialização do dispositivo ou uma reinicialização do agente do Configuration Manager ao usar o recurso Executar Scripts. Isso pode levar a um estado de reinicialização contínuo. Se necessário, há aprimoramentos no recurso de notificação do cliente que permitem a reinicialização de dispositivos. A coluna de reinicialização pendente pode ajudar a identificar dispositivos que precisam de uma reinicialização.

Parâmetros de script

Adicionar parâmetros a um script proporciona maior flexibilidade para o seu trabalho. Você pode incluir até 10 parâmetros. A seguir, descrevemos a capacidade atual do recurso Executar scripts com parâmetros de script para: Cadeia de caracteres, tipos de dados inteiros . Listas de valores predefinidos também estão disponíveis. Se o script tiver tipos de dados não compatíveis, você receberá um aviso.

Na caixa de diálogo Criar script , clique em Parâmetros de script em Script.

Cada um dos parâmetros do script tem sua própria caixa de diálogo para adicionar mais detalhes e validação. Se houver um parâmetro padrão no script, ele será enumerado na interface do usuário do parâmetro e você poderá defini-lo. O Configuration Manager não substituirá o valor padrão, pois nunca modificará o script diretamente. Você pode pensar nisso como "valores sugeridos preenchidos previamente" são fornecidos na interface do usuário, mas o Configuration Manager não fornece acesso a valores "padrão" em tempo de execução. Isso pode ser contornado editando o script para ter os padrões corretos.

Importante

Os valores de parâmetro não podem conter aspas simples.

Há um problema conhecido em que valores de parâmetro que incluem ou estão incluídos em aspas simples não são passados para o script corretamente. Ao especificar valores de parâmetro padrão contendo um espaço em um script, use aspas duplas. Ao especificar valores de parâmetro padrão durante a criação ou execução de um Script, não é necessário colocar o valor padrão entre aspas duplas ou simples, independentemente de o valor conter um espaço ou não.

Validação de parâmetro

Cada parâmetro em seu script tem uma caixa de diálogo Propriedades de Parâmetro de Script para você adicionar validação para esse parâmetro. Depois de adicionar a validação, você receberá erros se estiver inserindo um valor para um parâmetro que não atende à validação.

Exemplo: FirstName

Neste exemplo, você pode definir as propriedades do parâmetro de cadeia de caracteres, FirstName.

Parâmetros de script — cadeia de caracteres

A seção de validação da caixa de diálogo Propriedades do parâmetro de script contém os seguintes campos para seu uso:

  • Minimum Length - número mínimo de caracteres do campo FirstName .
  • Comprimento máximo - número máximo de caracteres do campo Nome
  • RegEx - abreviação de Expressão Regular. Para obter mais informações sobre como usar a Expressão Regular, consulte a próxima seção, Usando a validação de Expressão Regular.
  • Erro personalizado - útil para adicionar sua própria mensagem de erro personalizada que substitui qualquer mensagem de erro de validação do sistema.

Usando a validação de expressão regular

Uma expressão regular é uma forma compacta de programação para verificar uma cadeia de caracteres em relação a uma validação codificada. Por exemplo, você pode marcar a ausência de um caractere alfabético maiúsculo no campo Nome colocando-o [^A-Z] no campo RegEx.

O processamento de expressões regulares para esta caixa de diálogo é suportado pelo .NET Framework. Para obter orientação sobre o uso de expressões regulares, consulte .NET Regular Expression e Regular Expression Language.

Exemplos de script

Aqui estão alguns exemplos que ilustram os scripts que você pode querer usar com esse recurso.

Criar uma nova pasta e arquivo

Este script cria uma nova pasta e um arquivo dentro da pasta, de acordo com a sua entrada de nomenclatura.

Param(
[Parameter(Mandatory=$True)]
[string]$FolderName,
[Parameter(Mandatory=$True)]
[string]$FileName
)

New-Item $FolderName -type directory
New-Item $FileName -type file

Obter versão do sistema operacional

Esse script usa o WMI para consultar o computador quanto à versão do sistema operacional.

Write-Output (Get-WmiObject -Class Win32_operatingSystem).Caption

Editar ou copiar scripts do PowerShell

Você pode Editar ou Copiar um script do PowerShell existente usado com o recurso Executar Scripts . Em vez de recriar um script que você precisa alterar, agora edite-o diretamente. Ambas as ações usam a mesma experiência do assistente de quando você cria um novo script. Quando você edita ou copia um script, o Configuration Manager não persiste o estado de aprovação.

Dica

Não edite um script que está sendo executado ativamente em clientes. Eles não terminarão de executar o script original e talvez você não obtenha os resultados pretendidos desses clientes.

Editar um script

  1. Vá para o nó Scripts no espaço de trabalho Biblioteca de Software .
  2. Selecione o script a ser editado e clique em Editar na faixa de opções.
  3. Altere ou reimporte o script na página Detalhes do script .
  4. Clique em Avançar para exibir o Resumo e em Fechar quando terminar de editar.

Copiar um script

  1. Vá para o nó Scripts no espaço de trabalho Biblioteca de Software .
  2. Selecione o script a ser copiado e clique em Copiar na faixa de opções.
  3. Renomeie o script no campo Nome do script e faça as edições adicionais necessárias.
  4. Clique em Avançar para exibir o Resumo e em Fechar quando terminar de editar.

Executar um script

Depois que um script é aprovado, ele pode ser executado em um único dispositivo ou em uma coleção. Uma vez iniciada a execução do script, ele é iniciado rapidamente por meio de um sistema de alta prioridade que atinge o tempo limite em uma hora. Os resultados do script são então retornados usando um sistema de mensagens de estado.

Para selecionar uma coleção de destinos para o script:

  1. No console do Configuration Manager, clique em Ativos e Conformidade.
  2. No espaço de trabalho Ativos e Conformidade, clique em Coleções de Dispositivos.
  3. Na lista Coleções de dispositivos , clique na coleção de dispositivos nos quais você deseja executar o script.
  4. Selecione uma coleção de sua escolha e clique em Executar Script.
  5. Na página Script do assistente para Executar Script , escolha um script na lista. Somente os scripts aprovados são mostrados.
  6. Clique em Avançar e conclua o assistente.

Importante

Se um script não for executado, por exemplo, porque um dispositivo de destino está desligado durante o período de uma hora, você deverá executá-lo novamente.

Agendar o tempo de execução dos scripts

A partir da versão 2309 do branch atual do Configuration Manager, agora você pode agendar o tempo de execução de scripts em UTC.

Agende a execução de script em uma coleção:

  1. No console do Configuration Manager, clique em Ativos e Conformidade.

  2. No espaço de trabalho Ativos e Conformidade, clique em Coleções de Dispositivos.

  3. Na lista Coleções de dispositivos , clique na coleção de dispositivos na qual você deseja agendar o script.

  4. Selecione uma coleção de sua escolha e clique em Executar Script.

  5. Na página Agendamento, marque a caixa de seleção Agendar o script para ser executado em e especifique o Horário do agendamento em UTC.

  6. Verifique os detalhes exibidos na página de resumo.

  7. Clique em Avançar e conclua o assistente.

    Captura de tela do script - agendamento.

Observação

Um máximo de vinte e cinco scripts programados serão processados a cada 5 minutos.

Execução do computador de destino

O script é executado como a conta do sistema ou do computador no(s) cliente(s) de destino. Esta conta tem acesso limitado à rede. Qualquer acesso a sistemas e locais remotos pelo script deve ser provisionado adequadamente.

Monitoramento de script

Depois de iniciar a execução de um script em uma coleção de dispositivos, use o procedimento a seguir para monitorar a operação. Você pode monitorar um script em tempo real enquanto ele é executado e, posteriormente, retornar ao status e aos resultados de uma determinada execução de Run Script. Os dados de status do script são limpos como parte da tarefa de manutenção Excluir Operações de Cliente Antigo ou exclusão do script.

Monitor de script - Status de execução do script

  1. No console do Configuration Manager, clique em Monitoramento.

  2. No espaço de trabalho Monitoramento , clique em Status do Script.

  3. Na lista Status do Script , você pode exibir os resultados de cada script executado em dispositivos cliente. Um código de saída de script de 0 geralmente indica que o script foi executado com êxito.

    Monitor de script — script truncado

Agendar script Monitoramento em uma coleção

  1. No console do Configuration Manager, clique em Monitoramento.

  2. No espaço de trabalho Monitoramento, clique no nó Scripts Agendados.

  3. Uma nova linha será exibida na lista de Scripts Agendados.

  4. Verifique se uma nova linha foi exibida na lista de Scripts agendados. A coluna state deve ter o valor Scheduled. A coluna ClientOperationId deve estar em branco. Verifique se as outras colunas, como Nome do Script, Horário agendado etc., têm valores apropriados.

  5. Após o Horário de agendamento, atualize o nó Scripts agendados . A coluna de estado deve ter o valor Operação de cliente iniciada com êxito. A coluna ClientOperationId deve ter um valor inteiro.

  6. No espaço de trabalho Monitoramento, clique no nó Status do Script. Verifique se a nova linha foi exibida na lista e se a ClientOperationId é igual à ClientOperationId do nó Scripts agendados .

  7. Clique em Exibir status e verifique se a saída do script é exibida.

    Captura de tela do script - monitorar cronograma,

Saída do script

Saída do script de retorno do cliente usando a formatação JSON canalizando os resultados do script para o cmdlet ConvertTo-Json . O formato JSON retorna consistentemente a saída de script legível. Para scripts que não retornam objetos como saída, o cmdlet ConvertTo-Json converte a saída em uma cadeia de caracteres simples que o cliente retorna em vez de JSON.

  • Os scripts que obtiverem um resultado desconhecido ou em que o cliente estava offline não serão exibidos nos gráficos ou no conjunto de dados.

  • Evite retornar uma saída de script grande, pois ela é truncada para 4 KB.

  • Converta um objeto de enumeração em um valor de cadeia de caracteres em scripts para que eles sejam exibidos corretamente na formatação JSON.

    Converter objeto de enumeração em um valor sting

Você pode exibir a saída detalhada do script em formato JSON bruto ou estruturado. Essa formatação facilita a leitura e a análise da saída. Se o script retornar texto válido formatado em JSON ou a saída puder ser convertida em JSON usando o cmdlet ConvertTo-Json do PowerShell, exiba a saída detalhada como Saída JSON ou Saída Bruta. Caso contrário, a única opção será a Saída do Script.

Exemplo: a saída do script é conversível em JSON válido

Comando: $PSVersionTable.PSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      16299  551

Exemplo: a saída do script não é válida JSON

Comando: Write-Output (Get-WmiObject -Class Win32_OperatingSystem).Caption

Microsoft Windows 10 Enterprise

Arquivos de log

  • No cliente, por padrão em C:\Windows\CCM\logs:

    • Scripts.log
    • CcmMessaging.log

  • No MP, por padrão em C:\SMS_CCM\Logs:

    • MP_RelayMsgMgr.log

  • No servidor do site, por padrão em C:\Program Files\Configuration Manager\Logs:

    • SMS_Message_Processing_Engine.log

Automatizar com o Windows PowerShell

Você pode usar os seguintes cmdlets do PowerShell para automatizar algumas dessas tarefas:

Confira também

  • Last updated on