Personalização de Runbooks
Adapte os runbooks genéricos do RealmJoin às necessidades dos seus ambientes.
Visão Geral
A implementação do runbook RealmJoin oferece capacidades de personalização para o autor de um runbook ou para o administrador de ambientes, para que eles possam:
Hospedar parâmetros e templates específicos do cliente/locatário
Oferecer elementos de UI como seletores de usuário ou seleções suspensas
Apresentar explicações legíveis por humanos dos parâmetros
Ocultar elementos de UI desnecessários
As personalizações podem ser incluídas no próprio runbook e/ou armazenadas na instância do Portal RealmJoin do cliente. Por padrão, tentaremos oferecer padrões sensatos nos runbooks disponibilizados em GitHub.
Alguns runbooks virão com exemplos de como configurar templates específicos do cliente, como especificar locais de escritório para o onboarding de usuário.
Formatar
A personalização pode ser definida (em ordem decrescente de prioridade)
Bloco de JSON em configurações do Portal RealmJoin, substituindo o comportamento padrão do runbook
Bloco de JSON no cabeçalho de um runbook
Adicionalmente (com menor prioridade)
por parâmetro no cabeçalho do runbook
por parâmetro no bloco param dos runbooks (usando o Módulo Auxiliar RJRb)
Algumas funcionalidades (como templates) estão disponíveis apenas em formato JSON. Algumas funcionalidades (como criar um seletor de usuário) estão disponíveis apenas especificando um tipo de dado no bloco param. Você pode combinar múltiplos tipos de personalizações para melhores resultados.
Bloco Param do Runbook
O Portal RealmJoin analisa o bloco param PowerShell de um runbook para determinar quais campos de entrada renderizar. Quando possível, também validará as entradas de acordo com o tipo .NET informado para uma variável.
Os seguintes tipos de dados são atualmente compreendidos:
[bool],[boolean]- apresentará um alternador binário[string]- apresentará uma caixa de texto para digitar qualquer entrada alfanumérica[int]- apresentará uma caixa de texto, permitindo apenas entradas numéricas[DateTime],[DateTimeOffset]- Apresentará um seletor de data/hora
Você pode aplicar modificadores padrão do PowerShell aos parâmetros. O Portal RealmJoin, em particular, entenderá se você especificar [Parameter(Mandatory = $true)] para indicar um parâmetro obrigatório e impor que esses parâmetros sejam preenchidos.
Quando possível, o Portal RealmJoin também lerá e apresentará valores padrão fornecidos na UI.
Esteja ciente de que valores padrão do runbook podem ser substituídos por personalizações. Além disso, parâmetros podem ser completamente ocultados por personalizações.
Personalizando Parâmetros
Para poder personalizar parâmetros, por favor certifique-se de incluir o Módulo PS Runbook Helper da RealmJoin no seu runbook:
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
Você pode então incluir [ValidateScript( { Use-RJInterface ... } )] declarações nas definições de parâmetro. Por exemplo, o seguinte criará um seletor de usuário, permitindo escolher um usuário do Entra ID e passará seu object id como string para o runbook.
Vamos analisar isso parte por parte. [ValidateScript...] é um modificador para o próximo parâmetro definido no bloco param. Neste caso a variável $AssignedUserId.
Use-RJInterface faz parte do nosso Módulo Auxiliar de Runbook RealmJoin PowerShell. Ele permite que você especifique que tipo de entrada espera usando -Type quanto para -Entity, caso isso não esteja já totalmente definido pelo tipo da variável.
-DisplayName permite que você passe um prompt/descrição legível por humanos para este parâmetro ao Portal RealmJoin.
Recursos do Graph
No exemplo acima, a fonte da informação é o MS Graph, conforme descrito por -Type Graph. Para o MS Graph, use -Entity para especificar que tipo de recurso você está esperando. Entidades disponíveis são Usuários, Grupo, Dispositivo. Isso produzirá um seletor para usuários, grupos ou dispositivos no Entra ID dado.
O seletor inclui uma busca rápida, para localizar facilmente o recurso requerido.
Atualmente, não é possível seleção múltipla usando um seletor.
Por padrão, um seletor MS Graph retornará o ID do objeto. Se você precisar, por exemplo, do user principal name em vez disso, certifique-se de incluir "name" como sufixo no nome da sua variável. Então, basicamente, para obter o id de um usuário, nomeie o parâmetro $userid. Se você quiser um UPN, nomeie-o $username.
Filtragem do Graph
Se você estiver usando um seletor baseado em MS Graph, você também pode especificar -Filter e usar um Filtro ODATA para limitar os objetos oferecidos no seletor.
O exemplo a seguir listará apenas grupos do Entra ID que comecem com "LIC_".
Você pode preparar filtros e reutilizá-los em vários scripts usando o armazenamento central de dados. Neste caso, basta referenciar o filtro pelo nome usando -Filter "ref:LicenseGroup", onde ref: indica procurar um filtro armazenado.
Este exemplo específico ref:LicenseGroup está disponível por padrão sem configuração adicional.
Cabeçalho do Runbook
O Portal pode analisar a help baseada em comentários seção do runbook, se presente.
Aqui está um exemplo:
.SYNOPSIS - Dê uma descrição muito breve da função do seu runbook. Isso será exibido na lista de runbooks disponíveis.
.DESCRIPTION - Dê uma descrição da função do seu runbook. Pode conter um pouco mais de detalhe, pois isso será exibido dentro do diálogo de execução/parâmetros do runbook.
.PARAMETER - Deve ser seguido pelo nome de um parâmetro. Permite que você forneça uma explicação detalhada da entrada esperada para o parâmetro em questão.
.INPUTS - Pode conter um bloco de Personalização de Runbook baseado em JSON.
.NOTES - Não é analisado/renderizado. Por favor, use este espaço para escrever quais permissões e requisitos existem para o seu runbook.
.EXAMPLE - Não é analisado/renderizado. Pode conter um exemplo de uma Personalização baseada em JSON para usar no Datastore RealmJoin no seu locatário. Estes podem ser exemplos de como criar templates, por exemplo para diferentes fluxos de trabalho ou classes de usuário.
Personalização Baseada em JSON
Datastore Central
Cada locatário do Azure pode hospedar um datastore "Runbook Customizations", encontrado em https://portal.realmjoin.com/settings/runbooks-customizations .
O formato é JSON com comentários, permitindo vírgulas finais. Atualmente, existem três seções relevantes, Configurações, Templates, Runbooks.
Seção Runbooks
Runbooks é analisada pelo portal ao iniciar um runbook. Se existir uma seção com nome igual ao do Runbook do Azure Automation atual, seu conteúdo será usado para personalizar o frontend exibido ao usuário.
Considere o seguinte runbook de demonstração simples, chamado rjgit-device_demo-runbook-customizing.
Se não for personalizado, será apresentado assim no frontend:
Pensamentos:
Como este runbook é iniciado a partir do contexto de um dispositivo no portal, o
$DeviceIdé uma informação redundante para um usuário. Eu já sei em qual dispositivo estou trabalhando.O que acontece se eu habilitar ou desabilitar o "Extra Workflow"? Eu preciso pensar sobre o "Extra Workflow Time" se eu desabilitar o "Extra Workflow"?
Vamos melhorar isso. O seguinte JSON de exemplo no datastore central modificará a UI para o runbook.
Você pode usar a mesma notação/características no seu cabeçalho do runbook.
ParameterList
Cada parâmetro tem sua própria seção em ParameterList. Modifiers permitem alterar o comportamento desse parâmetro.
O resultado ficará assim:
Escolher o fluxo de trabalho adicional apresentará (reexibirá) mais parâmetros:
Isso mostra menos desordem em comparação com antes de aplicar a personalização. Ao mesmo tempo, mais informação sobre as alternativas de "Extra Workflow" está disponível ao usuário. Além disso, um usuário agora só se preocupará com "Extra Workflow Time" se for relevante.
Alterar a visibilidade desse campo foi feito usando um "Customization" bloco dentro de uma das "Select" opções. Atualmente você pode ter no máximo um desses "Customization" blocos ativo por vez.
Como você pode ver, o parâmetro $DeviceId está completamente oculto. Isso é feito definindo o "Hide": true para este parâmetro.
Parâmetros podem ter um DisplayName. Nós oferecemos um amigável para humanos DisplayName para substituir $ExtraWorkflowTime na UI. Veja outros modificadores para mais.
Você pode inserir parâmetros "sem nome" (faltando a Nome declaração) como a seção "Executar Fluxo de Trabalho Extra", se quiser oferecer elementos de UI sem retornar diretamente um valor. Isso normalmente é usado apenas em conjunto com Selecione.
Selecione
Usamos Selecione, para exibir uma lista de Opções em um dropdown. Cada opção pode Exibição texto, ou acionar um Personalização, como definir Hide ou um Default valor em outros parâmetros. No nosso exemplo, usamos isto para (re)ocultar $ExtraWorkflowTime e sobrescrever $ExtraWorkflow's valor.
$ExtraWorkflowTime é assim exibido apenas quando relevante e o interruptor binário $ExtraWorkflow agora é substituído por alternativas significativas na perspectiva do usuário.
No caso de um Selecione para um parâmetro nomeado, cada opção deve ter um "ParameterValue": "..." para passar ao runbook. Você pode colocar um "ShowValue: false" dentro do Selecione bloco para mostrar apenas o dropdown e não um campo para o valor resultante do parâmetro.
Exemplo de parâmetro nomeado:
O Default / DefaultValue a declaração no parâmetro também especifica o estado inicial do dropdown. No caso de um parâmetro sem nome, use o DisplayName do opção desejada, caso contrário dê um valor padrão de retorno, como "true" ou "false" ou alguma string.
Parâmetros
Se você tiver apenas parâmetros nomeados, pode usar o formato um pouco mais curto Parâmetros em vez de ParameterList.
Para um exemplo veja SelectSimple
SelectSimple
Se o poder total de um Selecione não for necessário e você apenas quiser oferecer uma lista de valores possíveis em um dropdown (sem aplicar personalizações adicionais), você pode usar SelectSimple.
SelectSimple é utilizável apenas para parâmetros nomeados.
city!=Stuttgart
A maior diferença (além de ser muito mais curto) em relação ao nosso exemplo anterior é que $ExtraWorkflowTime está sempre visível.
Modifiers
Cada parâmetro pode ter um ou mais dos seguintes modificadores:
"DisplayName": "texto"- Exibir "texto" como nome do parâmetro na UI"Hide": true / false- Ocultar este parâmetro"Mandatory": true / false- Exigir que este parâmetro seja preenchido"ReadOnly": true / false- Proteger este parâmetro de ser alterado a partir de seu valor padrão"DefaultValue": "..."- Definir um valor padrão para este parâmetro. (Você também pode usarDefaultem vez.)"GraphFilter": "startswith(DisplayName, 'LIC_')"- veja Filtragem do Graph"AllowEdit": true / false- Proteger este parâmetro de edição manual. (combine isto com templates)
Configurações
Configurações permite que você armazene dados de configuração como nomes de Conta de Armazenamento do Azure em um lugar central, mantendo-os separados dos seus runbooks.
Você pode acessar valores individuais do bloco param de um runbook usando Use-RJInterface.
Vamos pegar este exemplo de bloco param de um runbook:
O Portal tentará preencher cada parâmetro com valores do datastore central - se presente. Isso também funciona se o parâmetro tiver sido ocultado na UI.
Um possível JSON no datastore para este runbook seria:
O elemento ausente Container simplesmente não será preenchido automaticamente na UI.
Templates
Templates use referências JSON para trazer dados - por exemplo uma extensa lista de locais de escritório - ao usar uma Selecione declaração.
Isto permite manter uma personalização neutra/reutilizável/separada dos dados reais.
Vamos pegar o exemplo de onboarding de novos usuários. Você pode ter múltiplas opções dadas para departamentos ou locais de escritório, onde atribuir um local de escritório também determina um determinado endereço de rua, país, estado etc.
O exemplo seguinte de uma personalização de runbook utiliza a $ref dentro do Runbooks seção para referenciar/importar uma subárvore da Templates seção. Fique atento às $id/$values palavras-chave. Esteja ciente de que $id/$values devem ser definidas antes de serem referenciadas usando $ref. Por isso Templates é definido antes de Runbooks neste exemplo.
Neste exemplo dizemos ao portal para pegar a subárvore com o $id chamado LocationOptions e incluir seus $values, substituindo a declaração $ref Assim, o portal renderizará um Selecione conforme descrito na seção Runbooks mas incluirá as opções reais de Templates.
Um template pode conter qualquer declaração que seja suportada no local de referência. Neste exemplo, usamos uma declaração Personalização para modificar outros parâmetros como StreetAddress.
Então, podemos ter uma personalização específica do runbook em Runbooks reutilizável através de múltiplos ambientes, mantendo os dados reais separados.
Isto criará a seguinte UI:
Filtros do Graph
Você pode preparar Filtros ODATA do Graph para serem usados em múltiplos runbooks. Armazene-os em uma seção chamada GraphFilters.
O exemplo a seguir filtra por um certo prefixo no DisplayName de um grupo, para mostrar apenas grupos relacionados a licenciamento em um seletor de grupo.
Veja Filtragem do Graph sobre como usar isto a partir de um runbook.
Last updated
Was this helpful?