> 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). # Runbook のカスタマイズ ## 概要 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]` - 二値のトグルを表示します * `[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 に渡します。 ```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 モジュールです。これを使用すると、次を使って期待する入力の種類を指定できます `-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 Header 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": "ライセンスの割り当てまたは削除", "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 つあります `Settings`, `Templates`, `Runbooks`. ```json { "Settings": { }, "Templates": { }, "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 ) "## デバイス '$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 ヘッダー](#runbook-header). #### ParameterList 各パラメーターには、次の中に独自のセクションがあります `ParameterList`. [修飾子](#modifiers) はそのパラメーターの動作を変更できます。 結果は次のようになります: ![デモ - 非表示後](/files/ab6a238996984ced1f9ca2bf3418ed62773c8e92) 追加ワークフローを選択すると、さらに多くのパラメーターが表示（非表示解除）されます: ![デモ - 非表示解除後](/files/2537ec2ad7d7d404fc5f8d3ea03feb95e3426213) これにより、カスタマイズ適用前と比べて表示がすっきりします。同時に、「Extra Workflow」の代替 विकल्पについてより多くの情報がユーザーに提供されます。また、ユーザーは「Extra Workflow Time」が関連する場合にのみ気にすればよくなります。 そのフィールドの表示/非表示は次を使用して変更しました `"Customization"` のいずれかの中のブロックを `"Select"` のオプションです。現在、このようなブロックは同時に 1 つまでしか有効にできません。 `"Customization"` ブロックを同時に有効化できます。 ご覧のとおり、パラメーター `$DeviceId` は完全に非表示です。これは次を設定することで行われます `"Hide": true` このパラメーターに対して。 パラメーターには次を指定できます `DisplayName`。より人間に分かりやすい `DisplayName` を置き換えるために提供しました `$ExtraWorkflowTime` UI 上で。ほかの [修飾子を参照してください](#modifiers) 詳細はそちらをご覧ください。 "名前なし" パラメーター（次がない） `Name` の記述）が、値を直接返さずに UI 要素を提供したい場合に、「Execute Extra Workflow」セクションのように挿入できます。これは通常、次と組み合わせて使用されます `Select`. #### Select 次を使用しました `Select`、次の一覧を表示するために `Options` ドロップダウンに表示します。各オプションは `Display` テキストを表示したり、次をトリガーしたりできます `Customization`、たとえば次の設定です `Hide` または `Default` 値を他のパラメーターに設定します。この例では、これを使用して次を（非）表示にしました `$ExtraWorkflowTime` と上書きしました `$ExtraWorkflow`の値を。 `$ExtraWorkflowTime` したがって、これは関連がある場合にのみ表示され、二値スイッチ `$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` は常に表示されることです。 #### 修飾子 各パラメーターには、次の修飾子を 1 つ以上指定できます: * `"DisplayName": "テキスト"` - UI 上でパラメーターの名前として「テキスト」を表示する * `"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-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 { "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` 複数の環境で再利用可能で、実データは分離したままにできます。 ```json { "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 が作成されます。 ![デモ - ref-location](/files/8b22afda3009aabf7abf17f20e4e7431c8e441d3) ![デモ - ref-address](/files/217a892822135024213e34d2487caef22e38a751) ### グラフ フィルター 準備できます [ODATA グラフ フィルター](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-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: ``` GET https://docs.realmjoin.com/ja/zi-dong-hua/runbooks/runbook-customization.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.