> 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 インスタンスに保存することもできます。既定では、RealmJoin Portal 上で提供される runbook に対して妥当な既定値を提供するようにします [GitHub](https://github.com/realmjoin/realmjoin-runbooks). 一部の runbook には、ユーザーのオンボーディング時に Office の所在地を指定するなど、顧客固有のテンプレートの設定方法の例が含まれます。 ### フォーマット カスタマイズは（優先度の高い順に）定義できます * 〜内の 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]` - は二値トグルとして表示されます * `[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 "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 内のユーザー、グループ、またはデバイス用のピッカーが生成されます。 ピッカーにはクイック検索があり、必要なリソースを簡単に絞り込めます。 ![ピッカーの例](/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 "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` は、追加の設定なしで既定で利用できます。 ![ODATA フィルター](/files/b644d59d447d6154b03ad38703e9c1a6429301a5) ## 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": "ライセンスを割り当てる/削除する", "SelectSimple": { "ライセンスをユーザーに割り当てる": false, "ユーザーからライセンスを削除する": true } } } } #> ``` `.SYNOPSIS` - runbook の機能を非常に簡潔に説明してください。これは利用可能な runbook の一覧に表示されます。 `.DESCRIPTION` - runbook の機能を説明してください。実行 / パラメーター ダイアログ内に表示されるため、やや詳しく記述できます。 `.PARAMETER` - には続けてパラメーター名を指定する必要があります。対象パラメーターに期待される入力について詳細な説明を記述できます。 `.INPUTS` - JSON ベースの Runbook カスタマイズ ブロックを含めることができます。 `.NOTES` - は解析/レンダリングされません。この領域には、runbook に必要な権限や要件を記載してください。 `.EXAMPLE` - は解析/レンダリングされません。Tenant 内の RealmJoin Datastore で使用する JSON ベースのカスタマイズ例を含めることができます。これは、たとえば異なるワークフローやユーザー クラス向けのテンプレートの作成例にできます。 ## JSON ベースのカスタマイズ ### 中央データストア 各 Azure Tenant は、次の場所にある "Runbook Customizations" データストアをホストできます： . 形式はコメント付き JSON で、末尾のカンマを許可します。現在、関連するセクションは 3 つあります、 `設定`, `Templates`, `Runbook`. ```json { "Settings": { }, "Templates": { }, "Runbooks": { } } ``` ### Runbooks セクション `Runbook` は、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-header). #### ParameterList 各パラメーターには、次の中に独自のセクションがあります： `ParameterList`. [Modifiers](#modifiers) これらを使って、そのパラメーターの動作を変更できます。 結果は次のようになります： ![デモ - 非表示後](/files/ab6a238996984ced1f9ca2bf3418ed62773c8e92) 追加ワークフローを選択すると、より多くのパラメーターが表示（再表示）されます： ![デモ - 再表示後](/files/2537ec2ad7d7d404fc5f8d3ea03feb95e3426213) これは、カスタマイズ適用前と比べて表示の煩雑さが少ないことを示します。同時に、"Extra Workflow" の選択肢に関するより多くの情報がユーザーに提供されます。また、ユーザーは "Extra Workflow Time" が関係する場合にのみそれを気にすればよくなります。 そのフィールドの表示/非表示の変更は、次を使用して行いました： `"Customization"` 次のいずれかの内部にあるブロックを使用して `"Select"` のオプションです。現在、そのようなブロックは同時に 1 つまでしか有効にできません。 `"Customization"` そのようなブロックは同時に 1 つまでしか有効にできません。 ご覧のとおり、パラメーター `$DeviceId` は完全に非表示です。これは、このパラメーターに対して次を設定することで実現しています。 `"Hide": true` このパラメーターに対して パラメーターには `DisplayName`。人間に分かりやすい `DisplayName` を置き換えるための `$ExtraWorkflowTime` を UI 上に表示しました。その他の [修飾子を参照してください。](#modifiers) 詳細はそちらをご覧ください。 "名前なし" パラメーター（次が欠けているもの）を挿入できます： `名前` ステートメント）を、"Execute Extra Workflow" セクションのように挿入できます。値を直接返さずに UI 要素を提供したい場合に使います。これは通常、次と組み合わせて使用します： `選択します`. #### 選択します 次を使用しました： `選択します`、次の一覧を表示するために `Options` をドロップダウンに表示します。各オプションは `表示` テキストを表示したり、次をトリガーしたりできます： `カスタマイズ`、たとえば次を設定するなどです： `Hide` または `既定値` 他のパラメーターの値を設定します。例では、これを使って次を（非）表示しました： `$ExtraWorkflowTime` および上書き `$ExtraWorkflow`の値。 `$ExtraWorkflowTime` したがって、関連がある場合にのみ表示され、二値スイッチ `$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 } } ``` その `既定値` / `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": { "瞑想を実行（オプション）": true, "デバイスのマインドフルネスをスキップ": false } }, "ExtraWorkflowTime": { "DisplayName": "瞑想時間はどのくらいにしますか？" } } } } } ``` 前の例との最大の違いは（かなり短いこと以外に）、 `$ExtraWorkflowTime` は常に表示されることです。 #### Modifiers 各パラメーターには、次の修飾子を 1 つ以上指定できます： * `"DisplayName": "テキスト"` - UI でパラメーター名として "テキスト" を表示する * `"Hide": true / false` - このパラメーターを非表示にする * `"Mandatory": true / false` - このパラメーターの入力を必須にする * `"ReadOnly": true / false` - このパラメーターが既定値から変更されないようにする * `"DefaultValue": "..."` - このパラメーターの既定値を設定します。（代わりに次も使用できます `既定値` 。） * `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - 参照： [Graph のフィルタリング](#graph-filtering) * `"AllowEdit": true / false` - このパラメーターを手動編集から保護します。（テンプレートと組み合わせて使用してください） ### 設定 `設定` 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 用の datastore に入る可能性のある JSON は次のとおりです： ```json { "Settings": { "CaPoliciesExport": { "ResourceGroup": "rj-runbooks-01", "StorageAccount": { "Name": "rjrbexports01", "Location": "West Europe", "Sku": "Standard_LRS" } } } } ``` 不足している `コンテナー` 要素は、単純に UI では事前入力されません。 ### Templates `Templates` JSON 参照を使用してデータを取り込みます。たとえば、Office の所在地の長い一覧などです。これは、次を使用する場合に役立ちます： `選択します` ステートメント。 これにより、カスタマイズを実際のデータから切り離し、中立的で再利用可能な状態に保てます。 新しいユーザーのオンボーディング例を考えてみましょう。部署や Office の所在地について複数の候補があり、Office の所在地を割り当てると特定の番地、国、州なども必須になることがあります。 次の runbook カスタマイズ例では、 `$ref` 次の中に `Runbook` セクションを使用して、次のセクションからサブツリーを参照/インポートします： `Templates` セクション。次のキーワードに注意してください： `$id`/`$values` キーワードです。注意してください： `$id`/`$values` は、次を使用して参照する前に定義しておく必要があります： `$ref`。そのため、 `Templates` は次より前に定義されています： `Runbook` この例では。 この例では、ポータルに、次の内容を持つサブツリーを取得するよう指示します `$id` という名前の `LocationOptions` そしてその `$values`、置き換える `$ref` ステートメント。したがって、ポータルは `選択します` 次に記載するように `Runbook` セクションですが、実際のオプションは `Templates`. テンプレートには、参照先の場所でサポートされている任意のステートメントを含めることができます。この例では、 `カスタマイズ` ステートメントを使用して、次のような他のパラメーターを変更します: `StreetAddress`. そのため、runbook固有のカスタマイズを `Runbook` 実際のデータを分離したまま、複数の環境で再利用できます。 ```json { "Templates": { "Options": [ { "$id": "LocationOptions", "$values": [ { "Display": "DE-OF", "Customization": { "Default": { "StreetAddress": "Kaiserstraße 39", "PostalCode": "63065", "City": "オッフェンバッハ", "Country": "ドイツ" } } }, { "Display": "DE-DEG", "Customization": { "Default": { "StreetAddress": "Lateinschulgassse 24-26", "PostalCode": "94469", "City": "デッゲンドルフ", "Country": "ドイツ" } } }, { "Display": "DE-HH", "Customization": { "Default": { "StreetAddress": "Hans-Henny-Jahnn-Weg 53", "PostalCode": "22085", "City": "ハンブルク", "Country": "ドイツ" } } }, { "Display": "FI-HS", "Customization": { "Default": { "StreetAddress": "Somewhere 42", "PostalCode": "12345", "City": "ヘルシンキ", "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.