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] - 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 ユーザーを選択でき、そのオブジェクト ID が文字列として runbook に渡されます。

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

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

Use-RJInterface は、次の一部です RealmJoin Runbook Helper PowerShell Module です。期待する入力の種類を次で指定できます -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 ヘッダー

Portal は、runbook の comment based help セクションを、存在する場合に解析できます。

例を示します:

<#
  .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": {
                "ライセンスを割り当てる/削除する",
                "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 つあります。 設定, テンプレート, Runbooks.

{
    "設定": {
    },
    "テンプレート": {
    },
    "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
)

"## Device '$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 ヘッダー.

ParameterList

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

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

追加ワークフローを選ぶと、より多くのパラメーターが表示（再表示）されます:

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

そのフィールドの表示可否の変更は、次のものを使って行いました "Customization" ブロックを "Select" オプションのいずれかに含めることで行います。現在、同時にアクティブにできるのはそのような "Customization" ブロックは 1 つまでです。

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

パラメーターには DisplayNameを指定できます。UI 上でのパラメーター名として、分かりやすい DisplayName を提供しました $ExtraWorkflowTime の代わりに UI 上で表示します。詳細は他の修飾子を参照してください。

"名前のない" パラメーター（ Name の記述がないもの）を "追加ワークフローを実行" セクションのように挿入できます。これは、値を直接返さずに UI 要素を提供したい場合に使います。通常は Select.

Select

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

$ExtraWorkflowTime これは関連する場合にのみ表示され、2 値スイッチ $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 は常に表示されることです。

Modifiers

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

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

設定

設定 これにより、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 の例は次のとおりです:

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

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

テンプレート

テンプレート JSON 参照を使用してデータを取り込む - たとえば Office の所在地の長い一覧 - を使用する場合に Select ステートメント。

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

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

次の runbook カスタマイズの例では、 $ref を Runbooks セクションを使って、 テンプレート セクションからサブツリーを参照/インポートします。次の $id/$values キーワードに注意してください。なお、 $id/$values 参照する前に定義しておく必要があります。 $ref。そのため、 テンプレート は、 Runbooks この例では前に定義されています。

この例では、ポータルに次の値を持つサブツリーを取得するよう指示します。 $id という名前の LocationOptions を含め、その $valuesを置き換えます。 $ref ステートメント。したがって、ポータルは Select に記載されているとおりに Runbooks セクションのようにしつつ、実際のオプションを テンプレート.

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

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

{
    "テンプレート": {
        "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 が作成されます:

Graph フィルター

準備できます ODATA Graph フィルター複数の runbook で使用できるように、次のセクションに保存します: GraphFilters.

次の例では、グループ内の特定のプレフィックスを対象にフィルターし、 DisplayName グループピッカーでライセンス関連のグループだけを表示するためです。

"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // こちらも RJ コードに既定値として含まれています
  }

詳細は Graph フィルタリング runbook からこれを使用する方法について。

最終更新 2 か月前

役に立ちましたか？