Runbook のカスタマイズ

RealmJoin の汎用 Runbook を、環境のニーズに合わせて適応させます。

概要

RealmJoin の runbook 実装は、runbook の作成者や環境の管理者にカスタマイズ機能を提供し、次のことができます:

顧客/Tenant 固有のパラメーターとテンプレートをホストする
ユーザーピッカーやドロップダウン選択などの UI 要素を提供する
パラメーターの人間が読める説明を表示する
不要な UI 要素を非表示にする

カスタマイズは runbook 自体に含めることも、顧客の RealmJoin Portal インスタンスに保存することもできます。既定では、次の場所で提供される runbook に対して、適切な既定値を提供しようとします GitHub.

一部の runbook には、ユーザーのオンボーディング時に勤務場所を指定するなど、顧客固有のテンプレートを構成する方法の例が含まれます。

形式

カスタマイズは（優先度の高い順に）定義できます

の JSON ブロック RealmJoin Portal の設定、既定の runbook の動作を上書きします
runbook のヘッダー内の JSON ブロック

さらに（最も優先度が低い）

runbook ヘッダー内の各パラメーターごとに
runbook の param ブロック内の各パラメーターごとに（RJRb Helper Module を使用）

一部の機能（テンプレートなど）は JSON 形式でのみ利用できます。一部の機能（ユーザーピッカーの作成など）は、param ブロックでデータ型を指定した場合にのみ利用できます。最良の結果を得るには、複数の種類のカスタマイズを組み合わせることができます。

Runbook Param Block

RealmJoin Portal は、runbook の PowerShell param ブロックを解析して、どの入力フィールドを表示するかを判断します。可能な場合は、変数に指定された .NET 型に従って入力の検証も行います。

現在、次のデータ型が認識されます:

[bool], [boolean] - 二値のトグルを表示します
[string] - 任意の英数字入力を入力するテキストボックスを表示します
[int] - 数値入力のみを許可するテキストボックスを表示します
[DateTime], [DateTimeOffset] - 日付/時刻ピッカーを表示します

標準の PowerShell 修飾子をパラメーターに適用できます。RealmJoin Portal は、特に次を指定するとそれを理解します [Parameter(Mandatory = $true)] 必須パラメーターを示し、これらのパラメーターの入力を必須にします。

可能な場合、RealmJoin Portal は UI で指定された既定値も読み取り、表示します。

既定値はカスタマイズによって上書きできることに注意してください。また、パラメーターはカスタマイズによって完全に非表示にすることもできます。

パラメーターのカスタマイズ

パラメーターをカスタマイズできるようにするには、runbook に RealmJoin の Runbook Helper PS Module を含めてください:

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

その後、次を含めることができます [ValidateScript( { Use-RJInterface ... } )] パラメーター定義に記述します。たとえば、次のものはユーザーピッカーを作成し、Entra ID ユーザーを選択できるようにし、そのオブジェクト ID を文字列として runbook に渡します。

param(
    [ValidateScript( { Use-RJInterface -DisplayName "このユーザーにデバイスを割り当てる（任意）" -Type Graph -Entity User } )]
    [string] $AssignedUserId = ""
)

この部分を順に見ていきましょう。 [ValidateScript...] は param-block で定義される次のパラメーターに対する修飾子です。この場合、変数 $AssignedUserId.

Use-RJInterface は私たちの RealmJoin Runbook Helper PowerShell モジュールです。これを使用すると、次を使って期待する入力の種類を指定できます -Type と -Entity、変数の型によってすでに完全に定義されていない場合に使用します。

-DisplayName RealmJoin Portal にこのパラメーターの人間が読めるプロンプト / 説明を渡すことができます。

Graph リソース

上の例では、情報源は MS Graph であり、次で説明されています -Type Graph。MS Graph では、次を使用します -Entity どの種類のリソースを期待しているかを指定します。利用可能なエンティティは User, Group, Device。これにより、指定した Entra ID 内のユーザー、グループ、またはデバイスのピッカーが生成されます。

ピッカーにはクイック検索が含まれており、必要なリソースを簡単に絞り込めます。

現時点では、ピッカーで複数選択はできません。

既定では、MS Graph のピッカーはオブジェクトの ID を返します。たとえば user principal name を代わりに必要とする場合は、変数名の接尾辞として必ず "name" を含めてください。つまり、ユーザーの id を取得するには、パラメーターに次の名前を付けます $userid。UPN が必要な場合は、次のようにします $username.

Graph フィルタリング

MS Graph ベースのピッカーを使用している場合は、次も指定できます -Filter と次を使用して ODATA-Filter ピッカーで提示されるオブジェクトを制限します。

次の例では、Entra ID のうち "LIC_" で始まるグループのみを一覧表示します。

param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "ライセンス グループ" } )]
    [String] $GroupID_License
)

フィルターを準備し、次を使って複数のスクリプト間で再利用できます中央データストア。この場合は、次を使ってフィルター名を参照するだけです -Filter "ref:LicenseGroup"、ここで ref: 保存されたフィルターを検索することを示します。

param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
    [String] $GroupID_License
)

この特定の例 ref:LicenseGroup は、追加の構成なしで既定で利用できます。

Runbook Header

Portal は runbook のコメントベースのヘルプセクションを解析できます。存在する場合。

例を示します:

<#
  .SYNOPSIS
  グループ メンバーシップを通じてユーザーにライセンスを（解除）割り当てます。

  .DESCRIPTION
  グループ メンバーシップを通じてユーザーにライセンスを（解除）割り当てます。より詳細な説明...

  .PARAMETER DefaultGroups
  割り当てるグループのコンマ区切りリスト。例: "DL Sales,LIC Internal Product"

  .NOTES
  権限:
  MS Graph (API):
  - User.Read.All
  - GroupMember.ReadWrite.All 
  - Group.ReadWrite.All

  .INPUTS
  RunbookCustomization: {
        "Parameters": {
            "UserName": {
                "Hide": true
            },
            "Remove": {
                "DisplayName": "ライセンスの割り当てまたは削除",
                "SelectSimple": {
                    "ユーザーにライセンスを割り当てる": false,
                    "ユーザーからライセンスを削除する": true
                }
            }
        }
    }
#>

.SYNOPSIS - runbook の機能についてごく簡潔に説明してください。これは利用可能な runbook の一覧に表示されます。

.DESCRIPTION - runbook の機能について説明してください。実行／パラメータダイアログ内に表示されるため、やや詳しくても構いません。

.PARAMETER - パラメーター名の後に続ける必要があります。該当パラメーターに期待される入力の詳細な説明を記載できます。

.INPUTS - JSON ベースの Runbook Customization のブロックを含めることができます。

.NOTES - 解析／レンダリングされません。このスペースには、runbook に存在する権限や要件を記載してください。

.EXAMPLE - 解析／レンダリングされません。Tenant の RealmJoin Datastore で使用する JSON ベースのカスタマイズ例を記載できます。これらは、たとえば異なるワークフローやユーザークラス向けのテンプレート作成例にできます。

JSON ベースのカスタマイズ

中央データストア

各 Azure Tenant は "Runbook Customizations" データストアをホストでき、場所は次のとおりです https://portal.realmjoin.com/settings/runbooks-customizations .

形式はコメント付き JSON で、末尾のカンマが許可されます。現在、関連するセクションは 3 つあります Settings, Templates, Runbooks.

{
    "Settings": {
    },
    "Templates": {
    },
    "Runbooks": {
    }
}

Runbooks セクション

Runbooks は runbook の開始時に portal によって解析されます。現在の Azure Automation Runbook と同名のセクションが存在する場合、その内容がユーザーに表示されるフロントエンドのカスタマイズに使用されます。

次の単純なデモ用 runbook を、次の名前で用意したとします rjgit-device_demo-runbook-customizing.

<#
  .SYNOPSIS
  Runbook カスタマイズのデモ

  .DESCRIPTION
  Runbook カスタマイズのデモ。たとえばドロップダウン／選択
#>

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

param(
    [string] $DeviceId,
    [bool] $ExtraWorkflow = $true,
    [int] $ExtraWorkflowTime = 15
)

"## デバイス '$DeviceID' に対して処理を実行中"

# 非常に任意度の高い複雑なワークフロー
if ($ExtraWorkflow) {
    "## 瞑想を実行中..."
    Start-Sleep -Seconds $ExtraWorkflowTime
}

カスタマイズされていない場合、フロントエンドでは次のように表示されます:

考察:

この runbook は portal でデバイスのコンテキストから開始されるため、 $DeviceId はユーザーにとって冗長な情報です。どのデバイスを操作しているかはすでに分かっています。
「Extra Workflow」を有効または無効にすると何が起こるのでしょうか？「Extra Workflow」を無効にした場合、「Extra Workflow Time」について考える必要はありますか？

それを改善しましょう。中央データストア内の次の JSON 例により、runbook の UI が変更されます。

{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "ParameterList": [
                {
                    "Name": "DeviceId",
                    "Hide": true
                }, 
                {
                    "Name": "ExtraWorkflow",
                    "Hide": true
                },
                {
                    "Name": "ExtraWorkflowTime",
                    "DisplayName": "どのくらい瞑想しますか？",
                },
                {
                    "DisplayName": "追加ワークフローを実行",
                    "DisplayBefore": "ExtraWorkflowTime",
                    "Select": {
                        "Options": [
                            {
                                "Display": "瞑想を実行（任意）",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": true
                                    }
                                }
                            },
                            {
                                "Display": "デバイスのマインドフルネスをスキップ",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": false
                                    },
                                    "Hide": [
                                        "ExtraWorkflowTime"
                                    ]
                                }
                            }
                        ],
                        
                    },
                    "Default": "デバイスのマインドフルネスをスキップ"
                }
            ]
        }
    }
}

runbook ヘッダーで同じ表記 / 機能を使用できます runbook ヘッダー.

ParameterList

各パラメーターには、次の中に独自のセクションがあります ParameterList. 修飾子はそのパラメーターの動作を変更できます。

結果は次のようになります:

追加ワークフローを選択すると、さらに多くのパラメーターが表示（非表示解除）されます:

これにより、カスタマイズ適用前と比べて表示がすっきりします。同時に、「Extra Workflow」の代替 विकल्पについてより多くの情報がユーザーに提供されます。また、ユーザーは「Extra Workflow Time」が関連する場合にのみ気にすればよくなります。

そのフィールドの表示/非表示は次を使用して変更しました "Customization" のいずれかの中のブロックを "Select" のオプションです。現在、このようなブロックは同時に 1 つまでしか有効にできません。 "Customization" ブロックを同時に有効化できます。

ご覧のとおり、パラメーター $DeviceId は完全に非表示です。これは次を設定することで行われます "Hide": true このパラメーターに対して。

パラメーターには次を指定できます DisplayName。より人間に分かりやすい DisplayName を置き換えるために提供しました $ExtraWorkflowTime UI 上で。ほかの修飾子を参照してください詳細はそちらをご覧ください。

"名前なし" パラメーター（次がない） Name の記述）が、値を直接返さずに UI 要素を提供したい場合に、「Execute Extra Workflow」セクションのように挿入できます。これは通常、次と組み合わせて使用されます Select.

Select

次を使用しました Select、次の一覧を表示するために Options ドロップダウンに表示します。各オプションは Display テキストを表示したり、次をトリガーしたりできます Customization、たとえば次の設定です Hide または Default 値を他のパラメーターに設定します。この例では、これを使用して次を（非）表示にしました $ExtraWorkflowTime と上書きしました $ExtraWorkflowの値を。

$ExtraWorkflowTime したがって、これは関連がある場合にのみ表示され、二値スイッチ $ExtraWorkflow は、ユーザーの視点では意味のある代替 विकल्पに置き換えられます。

〜の場合、 Select 名前付きパラメーターでは、各オプションに次を含める必要があります "ParameterValue": "..." を runbook に渡します。次を配置できます "ShowValue: false" の中に Select ブロックを入れると、ドロップダウンのみを表示し、結果のパラメーター値のフィールドは表示しません。

名前付きパラメーターの例:

{
    "Name": "ExtraWorkflow",
    "DefaultValue": true,
    "DisplayName": "追加ワークフローを実行",
    "DisplayBefore": "ExtraWorkflowTime",
    "Select": {
        "Options": [
            {
                "Display": "瞑想を実行（任意）",
                "ParameterValue": true
            },
            {
                "Display": "デバイスのマインドフルネスをスキップ",
                "ParameterValue": false,
                "Customization": {
                    "Hide": [
                        "ExtraWorkflowTime"
                    ]
                }
            }
        ],
        "ShowValue": false
    }
}

その Default / DefaultValue の記述は、そのパラメーターにおけるドロップダウンの初期状態も指定します。名前なしパラメーターの場合は、目的のオプションの DisplayName を使用してください。それ以外の場合は、「true」や「false」、あるいは任意の文字列のような既定の戻り値を指定してください。

Parameters

名前付きパラメーターのみの場合は、少し短い Parameters 形式を次の代わりに使用できます ParameterList.

例については SelectSimple を参照してください

SelectSimple

の完全な機能が不要で、 Select 追加のカスタマイズを適用せずに、ドロップダウンで候補値の一覧だけを提示したい場合は、 SelectSimple.

SelectSimple は名前付きパラメーターにのみ使用できます。

例:

{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "Parameters": {
                "DeviceId": {
                    "Hide": true
                }, 
                "ExtraWorkflow": {
                    "Name": "ExtraWorkflow",
                    "DisplayName": "追加ワークフローを実行",
                    "Default": false,
                    "SelectSimple": {
                        "瞑想を実行（任意）": true,
                        "デバイスのマインドフルネスをスキップ": false
                    }
                },
                "ExtraWorkflowTime": {
                    "DisplayName": "どのくらい瞑想しますか？"
                }
            }
        }
    }
}

この例との最大の違い（はるかに短いこと以外）は、 $ExtraWorkflowTime は常に表示されることです。

修飾子

各パラメーターには、次の修飾子を 1 つ以上指定できます:

"DisplayName": "テキスト" - UI 上でパラメーターの名前として「テキスト」を表示する
"Hide": true / false - このパラメーターを非表示にする
"Mandatory": true / false - このパラメーターの入力を必須にする
"ReadOnly": true / false - このパラメーターが既定値から変更されないように保護する
"DefaultValue": "..." - このパラメーターの既定値を設定する。（次を使うこともできます Default 代わりに。）
"GraphFilter": "startswith(DisplayName, 'LIC_')" - 参照 Graph フィルタリング
"AllowEdit": true / false - このパラメーターを手動編集から保護する。（テンプレートと組み合わせて使用します）

Settings

Settings Azure Storage Account 名などの構成データを中央の場所に保存しつつ、runbook とは分離したままにできます。

runbook の param-Block から個々の値に次を使ってアクセスできます Use-RJInterface.

runbook の次の param-block の例を見てみましょう:

param(
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.Container" } )]
    [string] $ContainerName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.ResourceGroup" } )]
    [string] $ResourceGroupName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Name" } )]
    [string] $StorageAccountName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Location" } )]
    [string] $StorageAccountLocation,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Sku" } )]
    [string] $StorageAccountSku
)

Portal は、存在する場合、中央データストアの値で各パラメーターを事前入力しようとします。これは、パラメーターが UI で非表示になっている場合でも機能します。

この runbook に対するデータストア内の JSON 例は次のようになります:

{
    "Settings": {
        "CaPoliciesExport": {
            "ResourceGroup": "rj-runbooks-01",
            "StorageAccount": {
                "Name": "rjrbexports01",
                "Location": "西ヨーロッパ",
                "Sku": "Standard_LRS"
            }
        }
    }
}

欠落している コンテナー 要素は UI に事前入力されません。

Templates

Templates JSON リファレンスを使用してデータを取り込みます。たとえば、オフィスの場所の長い一覧などを、ある Select ステートメント。

これにより、カスタマイズを実データから分離し、中立的で再利用可能な状態に保てます。

新しいユーザーをオンボーディングする例を見てみましょう。部門やオフィスの場所について複数の選択肢があり、オフィスの場所を割り当てると、特定の番地、国、州なども必須になる場合があります。

次の runbook カスタマイズの例では、 $ref の中に Runbooks セクションを使って、 Templates セクション。次の点に注意してください。 $id/$values キーワード。〜に注意してください。 $id/$values それらは、使用して参照する前に定義しておく必要があります。 $ref。そのため、 Templates は、 Runbooks この例では。

この例では、ポータルに、 $id という LocationOptions そして、その $values、 $ref ステートメント。したがって、ポータルは Select 〜で説明されているように Runbooks セクションですが、 Templates.

テンプレートには、参照先の場所でサポートされている任意のステートメントを含めることができます。この例では、 Customization 〜などの他のパラメーターを変更するためのステートメントを使用します。 StreetAddress.

そのため、runbook 固有のカスタマイズを Runbooks 複数の環境で再利用可能で、実データは分離したままにできます。

{
    "Templates": {
        "Options": [
            {
                "$id": "LocationOptions",
                "$values": [
                    {
                        "Display": "DE-OF",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Kaiserstraße 39",
                                "PostalCode": "63065",
                                "City": "Offenbach",
                                "Country": "ドイツ"
                            }
                        }
                    },
                    {
                        "Display": "DE-DEG",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Lateinschulgassse 24-26",
                                "PostalCode": "94469",
                                "City": "Deggendorf",
                                "Country": "ドイツ"
                            }
                        }
                    },
                    {
                        "Display": "DE-HH",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Hans-Henny-Jahnn-Weg 53",
                                "PostalCode": "22085",
                                "City": "Hamburg",
                                "Country": "ドイツ"
                            }
                        }
                    },
                    {
                        "Display": "FI-HS",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Somewhere 42",
                                "PostalCode": "12345",
                                "City": "Helsinki",
                                "Country": "フィンランド"
                            }
                        }
                    }
                ]
            },
            {
                "$id": "CompanyOptions",
                "$values": [
                    {
                        "Id": "gkg",
                        "Display": "glueckkanja",
                        "Value": "glueckkanja AG"
                    },
                    {
                        "Id": "pp",
                        "Display": "PRIMEPULSE",
                        "Value": "PRIMEPULSE SE"
                    }
                ]
            }
        ]
    },
    "Runbooks": {
        "rjgit-org_general_add-user": {
            "ParameterList": [
                {
                    "DisplayName": "Office の場所",
                    "DisplayAfter": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "LocationOptions"
                        }
                    }
                },
                {
                    "Name": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "CompanyOptions"
                        },
                        "AllowEdit": false
                    }
                }
            ],
            "ReadOnly": [
                "StreetAddress",
                "PostalCode",
                "City",
                "Country"
            ]
        }
    }
}

これにより、次の UI が作成されます。

グラフフィルター

準備できます ODATA グラフフィルターを複数の runbook で使用できるようにします。これらは、次のセクション GraphFilters.

次の例では、グループの DisplayName 特定のプレフィックスでフィルターし、グループピッカーでライセンス関連のグループのみを表示します。

"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')\" // RJ コードにも既定で含まれています
  }

参照グラフフィルタリング runbook からこれを使用する方法について。

最終更新 1 年前

役に立ちましたか？