> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/ja/zi-dong-hua/runbooks/runbook-customization.md). # ランブックのカスタマイズ ## 概要 RealmJoin 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 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 に渡されます。 ```powershell param( [ValidateScript( { Use-RJInterface -DisplayName "このユーザーにデバイスを割り当てる（任意）" -Type Graph -Entity User } )] [string] $AssignedUserId = "" ) ``` これを少しずつ見ていきましょう。 `[ValidateScript...]` は、param-block で定義された次のパラメーターに対する修飾子です。この場合、変数 `$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` を使って、どの種類のリソースを想定しているかを指定します。利用可能なエンティティは `User`, `Group`, `Device`です。これにより、指定された Entra ID 内のユーザー、グループ、またはデバイス用のピッカーが生成されます。 ピッカーにはクイック検索が含まれており、必要なリソースを簡単に絞り込めます。 ![ピッカーの例](/files/c7a0b1960df07c234e128f77ade256e76c925717) 現在、ピッカーを使用した複数選択はできません。 既定では、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 "ライセンス グループ" } )] [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` は、追加の設定なしで既定で利用できます。 ![ODATA フィルター](/files/b644d59d447d6154b03ad38703e9c1a6429301a5) ## Runbook ヘッダー Portal は、runbook の [comment based help](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": { "ライセンスを割り当てる/削除する", "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" データストアをホストでき、場所は . 形式はコメント付き JSON で、末尾のカンマを許可します。現在、関連するセクションは 3 つあります。 `設定`, `テンプレート`, `Runbooks`. ```json { "設定": { }, "テンプレート": { }, "Runbooks": { } } ``` ### Runbooks セクション `Runbooks` は、runbook の開始時に Portal によって解析されます。現在の Azure Automation Runbook と同じ名前のセクションが存在する場合、その内容がユーザーに表示されるフロントエンドのカスタマイズに使われます。 次の単純なデモ用 runbook を想定してください。名前は `rjgit-device_demo-runbook-customizing`. ```powershell <# .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 } ``` カスタマイズされていない場合、フロントエンドでは次のように表示されます: ![デモ - 変更前](/files/f20309d04dea3b091cbf1b31b43724ed522f151c) 考察: * この 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](#modifiers) 内に独自のセクションがあり、そのパラメーターの動作を変更できます。 結果は次のようになります: ![デモ - 非表示後](/files/ab6a238996984ced1f9ca2bf3418ed62773c8e92) 追加ワークフローを選ぶと、より多くのパラメーターが表示（再表示）されます: ![デモ - 再表示後](/files/2537ec2ad7d7d404fc5f8d3ea03feb95e3426213) これにより、カスタマイズを適用する前と比べて表示がすっきりします。同時に、"Extra Workflow" の代替選択肢についてより多くの情報がユーザーに提供されます。また、ユーザーは "Extra Workflow Time" が関連する場合にのみ気にすればよくなります。 そのフィールドの表示可否の変更は、次のものを使って行いました `"Customization"` ブロックを `"Select"` オプションのいずれかに含めることで行います。現在、同時にアクティブにできるのはそのような `"Customization"` ブロックは 1 つまでです。 ご覧のとおり、パラメーター `$DeviceId` は完全に非表示です。これは、 `"Hide": true` をこのパラメーターに設定することで実現します。 パラメーターには `DisplayName`を指定できます。UI 上でのパラメーター名として、分かりやすい `DisplayName` を提供しました `$ExtraWorkflowTime` の代わりに UI 上で表示します。詳細は他の [修飾子](#modifiers) を参照してください。 "名前のない" パラメーター（ `Name` の記述がないもの）を "追加ワークフローを実行" セクションのように挿入できます。これは、値を直接返さずに UI 要素を提供したい場合に使います。通常は `Select`. #### Select を `Select`使い、 `Options` の一覧をドロップダウンに表示しました。各オプションは `Display` テキストを表示したり、 `Customization`をトリガーしたりできます。たとえば `Hide` や `Default` などを他のパラメーターに設定することです。この例では、それを使って `$ExtraWorkflowTime` を (再) 非表示にし、 `$ExtraWorkflow`の値を上書きしました。 `$ExtraWorkflowTime` これは関連する場合にのみ表示され、2 値スイッチ `$ExtraWorkflow` は、ユーザーの視点では意味のある選択肢に置き換えられます。 の場合、 `Select` という名前付きパラメーターに対しては、各オプションに `"ParameterValue": "..."` を runbook に渡す必要があります。 `"ShowValue: false"` を `Select` ブロック内に置くと、ドロップダウンのみを表示し、結果のパラメーター値用のフィールドは表示しません。 名前付きパラメーターの例: ```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"、または文字列などの既定の戻り値を指定します。 #### Parameters 名前付きパラメーターのみの場合は、 `Parameters` より少し短い `ParameterList`. 形式を使用できます。 #### SelectSimple SelectSimple の完全な機能が不要で、単にドロップダウンで可能な値の一覧を提供したいだけなら（追加のカスタマイズは行わずに）、 `Select` を使用できます `SelectSimple`. `SelectSimple` は名前付きパラメーターにのみ使用できます。 例: ```json { "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 フィルタリング](#graph-filtering) * `"AllowEdit": true / false` - このパラメーターを手動編集から保護する。（これをテンプレートと組み合わせます） ### 設定 `設定` これにより、Azure Storage Account 名などの構成データを中央に保存しつつ、runbook とは分離したままにできます。 runbook の param-Block から個々の値にアクセスするには `Use-RJInterface`. runbook のこの param-block の例を見てみましょう: ```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 { "設定": { "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` 複数の環境で再利用可能で、実データを分離した状態に保てます。 ```json { "テンプレート": { "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 が作成されます: ![デモ - ref-location](/files/8b22afda3009aabf7abf17f20e4e7431c8e441d3) ![デモ - ref-address](/files/217a892822135024213e34d2487caef22e38a751) ### Graph フィルター 準備できます [ODATA Graph フィルター](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 からこれを使用する方法について。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/ja/zi-dong-hua/runbooks/runbook-customization.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.