# ランブックのカスタマイズ
## 概要
Realmjoin Runbook の実装は、runbook の作成者または環境の管理者に対して、runbook をカスタマイズする機能を提供し、次のことができるようにします。
* 顧客/Tenant 固有のパラメーターとテンプレートをホストする
* ユーザーピッカーやドロップダウン選択のような UI 要素を提供する
* パラメーターの人間にとって読みやすい説明を表示する
* 不要な UI 要素を非表示にする
カスタマイズは、runbook 自体に含めることも、顧客の RealmJoin Portal インスタンスに保存することもできます。既定では、提供される runbook に対して妥当な既定値を提供するようにします。 [GitHub](https://github.com/realmjoin/realmjoin-runbooks).
一部の runbook には、ユーザー オンボーディング時のオフィス所在地の指定など、顧客固有のテンプレートを構成する方法の例が含まれています。
### 書式設定
カスタマイズは次のように定義できます（優先順位の高い順）
* 内の JSON ブロック [RealmJoin Portal の設定](https://portal.realmjoin.com/settings/runbooks-customizations)、既定の runbook の動作を上書きします
* runbook のヘッダー内の JSON ブロック
さらに（優先順位は最低）
* runbook ヘッダー内の各パラメーターごと
* runbook の param ブロック内の各パラメーターごと（RJRb Helper Module を使用）
一部の機能（テンプレートなど）は JSON 形式でのみ利用可能です。一部の機能（ユーザーピッカーの作成など）は、param ブロックでデータ型を指定することでのみ利用可能です。最良の結果を得るために、複数の種類のカスタマイズを組み合わせることができます。
## Runbook Param ブロック
RealmJoin Portal は、どの入力フィールドをレンダリングするかを判断するために、runbook の PowerShell の param ブロックを解析します。可能な場合は、変数に指定された .NET 型に従って入力も検証します。
現在理解されているデータ型は次のとおりです。
* `[bool]`, `[boolean]` - 2 値のトグルを表示します
* `[string]` - 任意の英数字入力を行うためのテキストボックスを表示します
* `[int]` - 数値入力のみを許可するテキストボックスを表示します
* `[DateTime]`, `[DateTimeOffset]` - 日付/時刻ピッカーを表示します
パラメーターには標準の PowerShell 修飾子を適用できます。特に RealmJoin Portal は、次の指定を理解します `[Parameter(Mandatory = $true)]` これは必須パラメーターを示し、これらのパラメーターが入力されることを強制します。
可能な場合、RealmJoin Portal は指定された既定値も読み取り、UI に表示します。
runbook の既定値はカスタマイズによって上書きされる可能性があることに注意してください。さらに、パラメーターはカスタマイズによって完全に非表示にすることもできます。
### パラメーターのカスタマイズ
パラメーターをカスタマイズできるようにするには、runbook に RealmJoin の Runbook Helper PS Module を含めてください。
`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`
その後、次を含めることができます `[ValidateScript( { Use-RJInterface ... } )]` この文をパラメーター定義に含められます。たとえば、次の例ではユーザーピッカーが作成され、Entra ID ユーザーを選択でき、その object id が文字列として runbook に渡されます。
```powershell
param(
[ValidateScript( { Use-RJInterface -DisplayName "Assign device to this user (optional)" -Type Graph -Entity User } )]
[string] $AssignedUserId = ""
)
```
これを少しずつ見ていきましょう。 `[ValidateScript...]` は、param ブロック内で次に定義されるパラメーターへの修飾子です。この場合、変数 `$AssignedUserId`.
`Use-RJInterface` は、当社の [RealmJoin Runbook Helper](https://github.com/realmjoin/RealmJoin.RunbookHelper) PowerShell Module の一部です。これにより、使用する入力の種類を指定できます `-Type` および `-Entity`。ただし、それが変数の型によってまだ完全に定義されていない場合に限ります。
`-DisplayName` を使うと、このパラメーターの人間にとって読みやすいプロンプト / 説明を RealmJoin Portal に渡すことができます。
#### Graph リソース
上記の例では、情報ソースは MS Graph であり、次で説明されています `-Type Graph`。MS Graph では、次を使用します `-Entity` 期待するリソースの種類を指定するには。利用可能なエンティティは `ユーザー`, `グループ`, `デバイス`。これにより、指定された Entra ID 内のユーザー、グループ、またはデバイスのいずれかに対するピッカーが生成されます。
このピッカーにはクイック検索が含まれており、必要なリソースを簡単に絞り込めます。
現在、ピッカーを使用した複数選択はできません。
既定では、MS Graph ピッカーはオブジェクトの ID を返します。たとえば user principal name が必要な場合は、変数名の末尾に "name" を含めてください。つまり、ユーザーの id を取得するには、パラメーター名を `$userid`にします。UPN が必要な場合は、次のように名前を付けます `$username`.
#### Graph フィルタリング
MS Graph ベースのピッカーを使用している場合は、次も指定できます `-Filter` および [ODATA-Filter](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) を使用して、ピッカーで提供されるオブジェクトを制限します。
次の例では、Entra ID から "LIC\_" で始まるグループのみを一覧表示します。
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "License group" } )]
[String] $GroupID_License
)
```
次を使用してフィルターを準備し、複数のスクリプト間で再利用できます [中央データストア](#graph-filters)。この場合は、次を使用して名前でフィルターを参照するだけです `-Filter "ref:LicenseGroup"`、ここで `ref:` は、保存されたフィルターを探すことを示します。
```powershell
param(
[Parameter(Mandatory = $true)]
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
[String] $GroupID_License
)
```
この特定の例 `ref:LicenseGroup` は、追加の構成なしで既定で利用可能です。
## Runbook ヘッダー
Portal は、runbook の [コメントベースのヘルプ](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) セクションが存在する場合、それを解析できます。
以下は例です。
```powershell
<#
.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": "Assign or Remove License",
"SelectSimple": {
"Assign License to User": false,
"Remove License from User": true
}
}
}
}
#>
```
`.SYNOPSIS` - runbook の機能について非常に簡潔な説明を記述します。これは利用可能な runbook の一覧に表示されます。
`.DESCRIPTION` - runbook の機能について説明を記述します。runbook の実行 / パラメーター ダイアログ内に表示されるため、やや詳しい内容を含めることができます。
`.PARAMETER` - この後にはパラメーター名が必要です。対象のパラメーターに期待される入力について、詳細な説明を記述できます。
`.INPUTS` - JSON ベースの Runbook Customization のブロックを含めることができます。
`.NOTES` - これは解析 / レンダリングされません。この領域は、runbook に存在するアクセス許可や要件を書き留めるために使用してください。
`.EXAMPLE` - これは解析 / レンダリングされません。Tenant 内の RealmJoin データストアで使用する JSON ベースのカスタマイズ例を含めることができます。これらは、たとえば異なるワークフローやユーザー クラス向けのテンプレート作成例にできます。
## JSON ベースのカスタマイズ
### 中央データストア
各 Azure Tenant は、次の場所にある "Runbook Customizations" データストアをホストできます .
形式はコメント付き JSON で、末尾のカンマを許可します。現在、関連するセクションは 3 つあります。 `Settings`, `テンプレート`, `Runbooks`.
```json
{
"Settings": {
},
"Templates": {
},
"Runbooks": {
}
}
```
### Runbooks セクション
`Runbooks` は、runbook 開始時に portal によって解析されます。現在の Azure Automation Runbook と同じ名前のセクションが存在する場合、その内容はユーザーに表示されるフロントエンドのカスタマイズに使用されます。
次の単純なデモ用 runbook を想定してください。名前は `rjgit-device_demo-runbook-customizing`.
```powershell
<#
.SYNOPSIS
Runbook Customizing をデモする
.DESCRIPTION
ドロップダウン/選択などの Runbook Customizing をデモする
#>
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
param(
[string] $DeviceId,
[bool] $ExtraWorkflow = $true,
[int] $ExtraWorkflowTime = 15
)
"## Device '$DeviceID' に対して処理を実行中"
# 非常に任意の複雑なワークフロー
if ($ExtraWorkflow) {
"## 瞑想を実行中..."
Start-Sleep -Seconds $ExtraWorkflowTime
}
```
カスタマイズされていない場合、フロントエンドでは次のように表示されます。
考察:
* この runbook は portal のデバイス コンテキストから開始されるため、 `$DeviceId` はユーザーにとって冗長な情報です。自分がどのデバイスを操作しているかはすでに分かっています。
* "Extra Workflow" を有効または無効にすると何が起きるのでしょうか。"Extra Workflow" を無効にした場合でも、"Extra Workflow Time" を考慮する必要があるのでしょうか。
これを改善してみましょう。中央データストア内の次の JSON 例は、この runbook の UI を変更します。
```json
{
"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-header).
#### ParameterList
各パラメーターには、それぞれ独自のセクションがあります `ParameterList`. [修飾子](#modifiers) により、そのパラメーターの動作を変更できます。
結果は次のようになります。
追加ワークフローを選択すると、さらに多くのパラメーターが表示されます（非表示解除）。
これにより、カスタマイズ適用前と比べて煩雑さが少なくなります。同時に、"Extra Workflow" の選択肢に関する情報がより多くユーザーに提供されます。また、ユーザーは "Extra Workflow Time" が関連する場合にのみ気にすればよくなります。
そのフィールドの表示/非表示の変更は、 `"Customization"` ブロックを `"Select"` オプションの 1 つの中で使用することで行われました。現在、一度に有効にできるこのような `"Customization"` ブロックは最大 1 つです。
ご覧のとおり、このパラメーター `$DeviceId` は完全に非表示です。これは、 `"Hide": true` をこのパラメーターに設定することで行われます。
パラメーターには `DisplayName`を設定できます。私たちは、人に分かりやすい `DisplayName` を提供して、 `$ExtraWorkflowTime` を UI 内で置き換えました。他の [修飾子](#modifiers) については、さらに参照してください。
"名前なし" パラメーター（ `名前` ステートメントが欠けているもの）を、"Execute Extra Workflow" セクションのように挿入できます。これは、値を直接返さずに UI 要素を提供したい場合に使います。通常、これは `選択します`.
#### 選択します
私たちは `選択します`を使用して、 `Options` のリストをドロップダウンに表示しました。各オプションは、 `表示` テキストを表示したり、 `カスタマイズ`をトリガーしたりできます。たとえば、 `Hide` や、他のパラメーターに対する `Default` 値の設定です。この例では、それを使って `$ExtraWorkflowTime` を表示/非表示にし、 `$ExtraWorkflow`の値を上書きしました。
`$ExtraWorkflowTime` したがって、これは関連がある場合にのみ表示され、2 値スイッチ `$ExtraWorkflow` は、ユーザー視点で意味のある選択肢に置き換えられました。
次の場合には `選択します` 名前付きパラメーターごとに、各オプションは `"ParameterValue": "..."` を持つ必要があり、runbook に渡されます。 `"ShowValue: false"` を `選択します` ブロック内に配置することで、ドロップダウンのみを表示し、結果となるパラメーター値のフィールドは表示しないようにできます。
名前付きパラメーターの例:
```json
{
"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"、または何らかの文字列のような既定の戻り値を指定してください。
#### パラメーター
名前付きパラメーターしかない場合は、やや短い `パラメーター` 形式を、 `ParameterList`.
の代わりに使用できます。例については SelectSimple を参照してください
#### SelectSimple
の完全な機能が不要で、追加のカスタマイズを適用せずにドロップダウンで可能な値の一覧だけを提供したい場合は、 `選択します` を使用できます `SelectSimple`.
`SelectSimple` は名前付きパラメーターでのみ使用可能です。
例:
```json
{
"Runbooks": {
"rjgit-device_demo-runbook-customizing": {
"Parameters": {
"DeviceId": {
"Hide": true
},
"ExtraWorkflow": {
"Name": "ExtraWorkflow",
"DisplayName": "追加ワークフローを実行",
"Default": false,
"SelectSimple": {
"Execute Meditation (optional)": true,
"Skip Device Mindfulness": false
}
},
"ExtraWorkflowTime": {
"DisplayName": "どのくらい瞑想しますか?"
}
}
}
}
}
```
以前の例との最大の違いは（はるかに短いこと以外では）、 `$ExtraWorkflowTime` が常に表示されることです。
#### 修飾子
各パラメーターは、次の修飾子の 1 つ以上を持つことができます。
* `"DisplayName": "text"` - UI でこのパラメーターの名前として "text" を表示する
* `"Hide": true / false` - このパラメーターを非表示にする
* `"Mandatory": true / false` - このパラメーターの入力を必須にする
* `"ReadOnly": true / false` - このパラメーターが既定値から変更されないよう保護する
* `"DefaultValue": "..."` - このパラメーターの既定値を設定する。（ `Default` を代わりに使用することもできます。）
* `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - 次を参照 [Graph フィルタリング](#graph-filtering)
* `"AllowEdit": true / false` - このパラメーターを手動編集から保護する。（テンプレートと組み合わせて使用）
### Settings
`Settings` により、Azure Storage Account 名のような構成データを中央の場所に保存しつつ、それらを runbook とは分離して保持できます。
runbook の param ブロックから個々の値にアクセスするには、次を使用できます `Use-RJInterface`.
次の runbook の param ブロック例を見てみましょう。
```powershell
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 の一例は、次のようになります。
```json
{
"Settings": {
"CaPoliciesExport": {
"ResourceGroup": "rj-runbooks-01",
"StorageAccount": {
"Name": "rjrbexports01",
"Location": "West Europe",
"Sku": "Standard_LRS"
}
}
}
}
```
不足している `Container` 要素は、UI で単に事前入力されません。
### テンプレート
`テンプレート` JSON 参照を使用してデータを取り込めます。たとえば、 `選択します` ステートメントを使用するときに、オフィス所在地の長いリストを取り込むことができます。
これにより、カスタマイズを中立的 / 再利用可能 / 実データから分離した状態に保つことができます。
新規ユーザーのオンボーディングの例を考えてみましょう。部門やオフィス所在地について複数の選択肢があり、オフィス所在地を割り当てると、特定の番地、国、州なども必須になる場合があります。
次の runbook カスタマイズ例では、 `$ref` を `Runbooks` セクションを使用して、 `テンプレート` セクションからサブツリーを参照 / インポートします。 `$id`/`$values` キーワードに注目してください。なお、 `$id`/`$values` は、 `$ref`を使用して参照する前に定義されている必要があります。 `テンプレート` が `Runbooks` より前に定義されているのは、このためです。
この例では、portal に対して、 `$id` という名前の `LocationOptions` を持つサブツリーを取得し、その `$values`を含めて、 `$ref` ステートメントを置き換えるよう指示しています。したがって、portal は `選択します` を、 `Runbooks` セクションで記述されているとおりにレンダリングしますが、実際のオプションは `テンプレート`.
から含めます。テンプレートには、参照先の場所でサポートされる任意のステートメントを含めることができます。この例では、 `カスタマイズ` ステートメントを使用して、 `StreetAddress`.
のような他のパラメーターを変更します。 `Runbooks` したがって、複数の環境で再利用可能な runbook 固有のカスタマイズを
```json
{
"Templates": {
"Options": [
{
"$id": "LocationOptions",
"$values": [
{
"Display": "DE-OF",
"Customization": {
"Default": {
"StreetAddress": "Kaiserstraße 39",
"PostalCode": "63065",
"City": "Offenbach",
"Country": "Germany"
}
}
},
{
"Display": "DE-DEG",
"Customization": {
"Default": {
"StreetAddress": "Lateinschulgassse 24-26",
"PostalCode": "94469",
"City": "Deggendorf",
"Country": "Germany"
}
}
},
{
"Display": "DE-HH",
"Customization": {
"Default": {
"StreetAddress": "Hans-Henny-Jahnn-Weg 53",
"PostalCode": "22085",
"City": "Hamburg",
"Country": "Germany"
}
}
},
{
"Display": "FI-HS",
"Customization": {
"Default": {
"StreetAddress": "Somewhere 42",
"PostalCode": "12345",
"City": "Helsinki",
"Country": "Finland"
}
}
}
]
},
{
"$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": "オフィス所在地",
"DisplayAfter": "CompanyName",
"Select": {
"Options": {
"$ref": "LocationOptions"
}
}
},
{
"Name": "CompanyName",
"Select": {
"Options": {
"$ref": "CompanyOptions"
},
"AllowEdit": false
}
}
],
"ReadOnly": [
"StreetAddress",
"PostalCode",
"City",
"Country"
]
}
}
}
```
これにより、次の UI が作成されます。
### Graph フィルター
次を準備できます [ODATA Graph-Filters](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) を複数の runbook で使用するために。これらは次のセクションに保存します `GraphFilters`.
次の例では、グループの `DisplayName` に対して特定のプレフィックスでフィルターし、グループ ピッカーでライセンス関連のグループのみを表示します。
```json
"GraphFilters": {
"LicenseGroup": "startswith(DisplayName, 'LIC_')" // RJ コードにも既定値として含まれています
}
```
参照 [Graph フィルタリング](#graph-filtering) これを runbook から使用する方法について。