Runbook のカスタマイズ

RealmJoin の汎用 Runbook を環境のニーズに合わせて適応させます。

概要

RealmJoinランブック実装は、ランブックの作成者や環境の管理者が次のことを行えるようにカスタマイズ機能を提供します:

顧客/テナント固有のパラメーターやテンプレートをホストする
ユーザーピッカーやドロップダウン選択などのUI要素を提供する
パラメーターの人間可読な説明を提示する
不要なUI要素を非表示にする

カスタマイズはランブック自体に含めるか、顧客のRealmJoinポータルインスタンスに保存できます。デフォルトでは、当社は提供されるランブックに妥当なデフォルトを用意しようとします: GitHub.

一部のランブックには、ユーザーオンボーディングのオフィス所在地を指定するなど、顧客固有テンプレートの構成例が付属します。

整形

カスタマイズは（優先度の降順で）定義できます:

のJSONブロック RealmJoinポータル設定, デフォルトのランブック動作を上書きする
ランブックのヘッダー内のJSONブロック

さらに（最も優先度が低い）

ランブックヘッダー内の各パラメーターごとに
RJRbヘルパーモジュールを使用したランブックのparamブロック内の各パラメーターごとに

一部の機能（テンプレートなど）はJSON形式でのみ利用可能です。ある機能（ユーザーピッカーの作成など）はparamブロックでデータ型を指定することでのみ利用可能です。最良の結果を得るために、複数のタイプのカスタマイズを組み合わせることができます。

ランブックのParamブロック

RealmJoinポータルは、ランブックのPowerShell paramブロックを解析して描画すべき入力フィールドを判別します。可能な場合は、変数に与えられた.NET型に従って入力を検証します。

現在サポートされているデータ型は次のとおりです:

[bool], [boolean] - 二者択一のトグルを表示します
[string] - 任意の英数字入力を入力するテキストボックスを表示します
[int] - 数値入力のみ許可するテキストボックスを表示します
[DateTime], [DateTimeOffset] - 日付/時刻ピッカーを表示します

パラメーターには標準のPowerShell修飾子を適用できます。特にRealmJoinポータルは、次を指定した場合に理解します [Parameter(Mandatory = $true)] 必須パラメーターを示し、これらのパラメーターが入力されることを強制するために

可能な場合、RealmJoinポータルはUIで表示する既定値も読み取って提示します。

ランブックの既定値はカスタマイズによって上書きされる場合があることに注意してください。さらに、カスタマイズによってパラメーターを完全に非表示にすることもできます。

パラメーターのカスタマイズ

パラメーターをカスタマイズできるようにするには、ランブックにRealmJoinのRunbook Helper PSモジュールを含めてください:

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

次に以下を含めることができます [ValidateScript( { Use-RJInterface ... } )] パラメーター定義に文を含めます。例えば次の例はユーザーピッカーを作成し、Entra IDユーザーを選択させ、そのオブジェクトIDを文字列としてランブックに渡します。

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 PowerShellモジュールの一部です。これにより、期待する入力の種類を次のように指定できます。 -Type 同じ Log Analytics アカウントを -Entity（変数の型ですでに完全に定義されていない場合に）

-DisplayName はこのパラメーターの人間向けのプロンプト/説明をRealmJoinポータルに渡すことを可能にします。

Graphリソース

上の例では、情報のソースはMS Graphであり、次のように記述されています -Type GraphMS Graphの場合、期待するリソースの種類を指定するには次を使用します。 -Entity 利用可能なエンティティは Microsoft の資格情報で当社プラットフォームに認証すると、希望する総, グループ, デバイスです。これにより、指定されたEntra ID内のユーザー、グループ、またはデバイス用のピッカーが生成されます。

ピッカーにはクイック検索が含まれており、必要なリソースを簡単に絞り込めます。

現在、ピッカーでの複数選択はできません。

デフォルトでは、MS GraphピッカーはオブジェクトのIDを返します。たとえばユーザーのユーザープリンシパル名が必要な場合は、変数名に"name"をサフィックスとして含めてください。基本的には、ユーザーのIDを取得するにはパラメーターを $useridと名付けてください。 UPNが欲しい場合は、.

$username

と名付けてください。 Graphフィルタリング MS Graphベースのピッカーを使用している場合、次を指定することもできます -Filter とODATAフィルターを使用して、ピッカーで提示されるオブジェクトを制限します。

次の例は、Entra IDのグループのうち"LIC_"で始まるもののみをリストします。

param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "License group" } )]
    [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 は追加の構成なしでデフォルトで利用可能です。

ランブックヘッダー

ポータルはランブックのコメントベースのヘルプセクションを、存在する場合に解析できます。

例を示します:

<#
  .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 - ランブックの機能を非常に簡潔に説明してください。これは利用可能なランブックの一覧に表示されます。

.DESCRIPTION - ランブックの機能の説明を記載してください。これはランブックの実行/パラメーターダイアログ内に表示されるため、やや詳しい説明を含めることができます。

.PARAMETER - これはパラメーター名に続ける必要があります。該当するパラメーターに期待される入力の詳細な説明を提供できます。

.INPUTS - JSONベースのRunbookカスタマイズのブロックを含めることができます。

.NOTES - 解析/レンダリングされません。ここにはランブックに必要な権限や要件を記載してください。

.EXAMPLE - 解析/レンダリングされません。テナントのRealmJoinデータストアで使用するJSONベースのカスタマイズの例を含めることができます。これらはワークフローやユーザークラスごとのテンプレート作成例などになり得ます。

JSONベースのカスタマイズ

中央データストア

各Azureテナントは「Runbook Customizations」データストアをホストでき、場所は次のとおりです: https://portal.realmjoin.com/settings/runbooks-customizations .

形式はコメントを含むJSONで、末尾のカンマを許容します。現在、関連するセクションは3つあります、 設定, テンプレート, Runbooks.

{
    "Settings": {
    },
    "Templates": {
    },
    "Runbooks": {
    }
}

Runbooksセクション

Runbooks はランブック起動時にポータルによって解析されます。現在のAzure Automationランブックと同名のセクションが存在する場合、その内容がユーザーに表示されるフロントエンドのカスタマイズに使用されます。

次の単純なデモランブックを想定します。名前は rjgit-device_demo-runbook-customizing.

<#
  .SYNOPSIS
  ランブックカスタマイズのデモ

  .DESCRIPTION
  ドロップダウン/選択のようなランブックカスタマイズのデモ
#>

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

param(
    [string] $DeviceId,
    [bool] $ExtraWorkflow = $true,
    [int] $ExtraWorkflowTime = 15
)

"## Doing stuff to Device '$DeviceID'"

# 非常にオプションな複雑なワークフロー
if ($ExtraWorkflow) {
    "## Executing Meditation..."
    Start-Sleep -Seconds $ExtraWorkflowTime
}

カスタマイズされていない場合、フロントエンドでは次のように表示されます:

所感:

このランブックはポータル上でデバイスのコンテキストから起動されるため、 $DeviceId はユーザーにとって冗長な情報です。私はすでにどのデバイスを扱っているかを知っています。
「Extra Workflow」を有効/無効にした場合に何が起きますか？「Extra Workflow」を無効にした場合に「Extra Workflow Time」について考える必要がありますか？

これを改善しましょう。中央データストアの以下のJSON例はランブックのUIを変更します。

{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "ParameterList": [
                {
                    "Name": "DeviceId",
                    "Hide": true
                }, 
                {
                    "Name": "ExtraWorkflow",
                    "Hide": true
                },
                {
                    "Name": "ExtraWorkflowTime",
                    "DisplayName": "How long to meditate?",
                },
                {
                    "DisplayName": "Execute Extra Workflow",
                    "DisplayBefore": "ExtraWorkflowTime",
                    "Select": {
                        "Options": [
                            {
                                "Display": "Execute Meditation (optional)",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": true
                                    }
                                }
                            },
                            {
                                "Display": "Skip Device Mindfulness",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": false
                                    },
                                    "Hide": [
                                        "ExtraWorkflowTime"
                                    ]
                                }
                            }
                        ],
                        
                    },
                    "Default": "Skip Device Mindfulness"
                }
            ]
        }
    }
}

同じ表記/機能をランブックヘッダー内でも使用できます。ランブックヘッダー.

ParameterList

各パラメーターは ParameterList. 内に独自のセクションを持ちます。 Modifiers

はそのパラメーターの動作を変更することを可能にします。

デモ - 非表示後

デモ - 表示後

これはカスタマイズ適用前と比較して乱雑さを減らします。同時に「Extra Workflow」の選択肢に関する情報がユーザーにより提供されます。また、ユーザーは関連する場合にのみ「Extra Workflow Time」を気にするようになります。 そのフィールドの可視性変更は、 の内部にある のブロックを使用して行われました。 現在、同時に最大1つのそのような そのフィールドの可視性変更は、 ブロックのみをアクティブにできます。

ご覧の通り、パラメーター $DeviceId は完全に非表示になっています。これはこのパラメーターの "Hide": true を設定することで行われます。

パラメーターは DisplayNameを持つことができます。 DisplayName 私たちは人間に優しい をUIで$ExtraWorkflowTimeの代わりに提供しました。 他の修飾子も参照してください。

値を直接返さずにUI要素を提供したい場合は、"Execute Extra Workflow"セクションのように"名前のない"パラメーター（"ステートメント"が欠けているもの）を挿入できます。これは通常、 名前 と組み合わせてのみ使用されます。 選択します.

選択します

我々は 選択しますを使用してドロップダウンに のリストを表示しました。各オプションは テキストにしたり、 表示 のような処理をトリガーしたりできます。 カスタマイズ他のパラメーターに対して Hide や Default 値を設定することがあります。例では、これを使って をUIで$ExtraWorkflowTimeの代わりに提供しました。 を(非)表示し、 $ExtraWorkflowの値を上書きしました。

をUIで$ExtraWorkflowTimeの代わりに提供しました。 は関連する場合にのみ表示され、二値スイッチ $ExtraWorkflow はユーザー視点で意味のある代替表示に置き換えられます。

名前付きパラメーターのための 選択します の各オプションには、ランブックに渡すための "ParameterValue": "..." を持たせるべきです。 結果パラメーターの値フィールドを表示したくない場合は、 ブロック内に"ShowValue: false"を配置してドロップダウンのみを表示できます。 選択します ブロック内に配置できます。

名前付きパラメーターの例:

{
    "Name": "ExtraWorkflow",
    "DefaultValue": true,
    "DisplayName": "Execute Extra Workflow",
    "DisplayBefore": "ExtraWorkflowTime",
    "Select": {
        "Options": [
            {
                "Display": "Execute Meditation (optional)",
                "ParameterValue": true
            },
            {
                "Display": "Skip Device Mindfulness",
                "ParameterValue": false,
                "Customization": {
                    "Hide": [
                        "ExtraWorkflowTime"
                    ]
                }
            }
        ],
        "ShowValue": false
    }
}

その Default / DefaultValue パラメーター内のステートメントはドロップダウンの初期状態も指定します。名前のないパラメーターの場合は、目的のオプションの DisplayName を使用するか、そうでなければ"true"や"false"、あるいは文字列などのデフォルトの返り値を指定してください。

パラメーター

名前付きパラメーターのみがある場合は、 パラメーター の代わりに少し短い ParameterList.

形式を使用できます。

SelectSimpleの例を参照してください

SelectSimple 選択します フル機能の SelectSimpleの例を参照してください.

SelectSimpleの例を参照してください が不要で、単にドロップダウンで可能な値の一覧を提供したいだけ（追加のカスタマイズを適用しない）場合は、

例：

{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "Parameters": {
                を使用できます。
                    "Hide": true
                }, 
                は名前付きパラメーターでのみ使用可能です。
                    "Name": "ExtraWorkflow",
                    "DisplayName": "Execute Extra Workflow",
                    "DeviceId": {
                    "SelectSimple": {
                        "ExtraWorkflow": {
                        "Default": false,
                    }
                },
                "Execute Meditation (optional)": true,
                    "Skip Device Mindfulness": false
                }
            }
        }
    }
}

"ExtraWorkflowTime": { をUIで$ExtraWorkflowTimeの代わりに提供しました。 私たちの前の例との最大の違い（短いこと以外）は、

内に独自のセクションを持ちます。

が常に表示されることです。

各パラメーターは以下のいずれかまたは複数の修飾子を持つことができます: "DisplayName": "text"
- UIでパラメーターの名前として"text"を表示する "Hide": true / false
- このパラメーターを非表示にする "Mandatory": true / false
- このパラメーターの入力を必須にする "ReadOnly": true / false
- このパラメーターが既定値から変更されるのを防ぐ "DefaultValue": "..." Default - このパラメーターのデフォルト値を設定する。（代わりに
を使用することもできます。） "GraphFilter": "startswith(DisplayName, 'LIC_')" $username
- を参照してください "AllowEdit": true / false

設定

設定 - 手動編集からこのパラメーターを保護します。（テンプレートと組み合わせて使用してください）

はAzure Storageアカウント名のような構成データを中央の場所に保存しつつ、ランブックからは分離して保持することを可能にします。 Use-RJInterface.

ランブックのparamブロックから個々の値にアクセスするには次を使用します:

param(
    例として次のランブックの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

ポータルは中央データストアから各パラメーターを（存在すれば）事前入力しようとします。これはパラメーターがUIで非表示にされている場合でも機能します。

{
    "Settings": {
        このランブックのデータストア内の可能なJSONは次のようになります:
            "CaPoliciesExport": {
            "ResourceGroup": "rj-runbooks-01",
                "StorageAccount": {
                "Name": "rjrbexports01",
                "Location": "West Europe",
            }
        }
    }
}

"Sku": "Standard_LRS" 欠けている Container

テンプレート

テンプレート 要素は単にUIに事前入力されません。 選択します JSON参照を使用してデータ（例えば長いオフィス所在地のリスト）を取り込むことができます。これは

ステートメントを使用する場合に有用です。

これにより、カスタマイズを実際のデータから分離して中立/再利用可能に保つことができます。

新規ユーザーのオンボーディングの例を考えてみましょう。部署やオフィス所在地に複数の選択肢があり、オフィス所在地を割り当てると特定の住所、国、州などが要求される場合があります。 次のランブックカスタマイズの例は、 ブロック内に"ShowValue: false"を配置してドロップダウンのみを表示できます。 Runbooks $ref テンプレート セクションを使用して、 セクションからサブツリーを参照/インポートします。/$id $values セクションからサブツリーを参照/インポートします。/$id といったキーワードに注意してください。 次のランブックカスタマイズの例は、参照する前に テンプレート を定義する必要があることに注意してください。 Runbooks そのためこの例では

はの前に定義されています。 セクションからサブツリーを参照/インポートします。 この例では、ポータルに という を持つサブツリーを取得し、その $idを置き換えるよう指示します。したがって、ポータルは 次のランブックカスタマイズの例は、 セクションに記載されたとおりに 選択します をレンダリングしますが、実際のオプションはから取り込みます。 Runbooks テンプレートは参照先でサポートされる任意の文を含めることができます。この例では、他のパラメーター（例: テンプレート.

StreetAddress カスタマイズ ）を変更するために ステートメントを使用しています。.

したがって、ランブック固有のカスタマイズを Runbooks に保持しつつ、実際のデータを分離して複数の環境で再利用できます。

{
    "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": "Office Location",
                    "DisplayAfter": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "LocationOptions"
                        }
                    }
                },
                {
                    "Name": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "CompanyOptions"
                        },
                        "AllowEdit": false
                    }
                }
            ],
            "ReadOnly": [
                "StreetAddress",
                "PostalCode",
                "City",
                "Country"
            ]
        }
    }
}

これにより次のUIが作成されます:

Graphフィルター

を準備できます。 ODATA Graphフィルター複数のランブックで使用するために保存します。これらは というセクションに格納してください:.

GraphFilters DisplayName 次の例は、グループの表示名の特定のプレフィックスをフィルタリングし、グループピッカーにライセンス関連のグループのみを表示するものです。

"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // RJコードにもデフォルトとして含まれます
  }

参照： Graphフィルタリングランブックからこれを使用する方法について。

最終更新 1 年前

役に立ちましたか？

こんにちは

hashtag概要

hashtag整形

hashtagランブックのParamブロック

hashtagパラメーターのカスタマイズ

hashtagGraphリソース

hashtag$username

hashtagランブックヘッダー

hashtagJSONベースのカスタマイズ

hashtag中央データストア

hashtagRunbooksセクション

hashtagParameterList

hashtag選択します

hashtagパラメーター

hashtagSelectSimpleの例を参照してください

hashtag内に独自のセクションを持ちます。

hashtag設定

hashtagテンプレート

hashtagGraphフィルター

概要

整形