Get-RjRbBrandingMailParams

RJReport.Branding の Tenant 設定を、Send-RjRbReportEmail ですぐに使えるパラメーターに解決します。

概要

Get-RjRbBrandingMailParams 中央のギャップを埋める メール ブランディング設定 と Send-RjRbReportEmail: 設定は URL、送信関数は ローカル ファイル パスを期待します。この関数は、構成済みの画像をダウンロードし、検証して、送信呼び出しにそのまま splat できる hashtable を返します。

RealmJoin.RunbookHelper 0.8.9 で利用できます。 それ以前の runbook バージョンでは、このロジックは同名のインライン ヘルパーとして含まれていました。Automation Account が 0.8.9 以降で実行されるようになったら、それらのコピーは削除できます。

設計ルール:

• レポートを失敗させません。 問題があっても — 空の設定、HTTPS でない URL、ダウンロード失敗、サイズ超過ファイル、無効な画像、不正な形式の色 — 警告を出し、その単一のキーは省略されます。その後、メールは対応する RealmJoin の既定値でレンダリングされます。
• 解決できたものだけを返します。 返される hashtable には成功したキーだけが含まれるため、splat しても空の値で既定値を上書きすることはありません。
• 実行ごとに 1 回のダウンロード。 1 回呼び出して結果を再利用し、runbook が送信するすべてのメールで使います — 多数のユーザーに通知するループの内側も含みます。

クイック スタート

$brandingMailParams = Get-RjRbBrandingMailParams `
    -HeaderImageUrl $BrandingHeaderImageUrl `
    -FooterImageUrl $BrandingFooterImageUrl `
    -FooterLink     $BrandingFooterLink `
    -AccentColor    $BrandingAccentColor `
    -TextColor      $BrandingTextColor

Send-RjRbReportEmail `
    -EmailFrom       $EmailFrom `
    -EmailTo         $EmailTo `
    -Subject         $Subject `
    -MarkdownContent $reportMd `
    @brandingMailParams

ブランディングが設定されていない場合、 $brandingMailParams は空の hashtable で、呼び出しはパラメーターを省略した場合とまったく同じように動作します。

パラメーター

すべてのパラメーターは省略可能です — この関数は、Tenant に設定されている内容に応じて呼び出せるよう設計されています。

パラメーター	型	既定	説明
HeaderImageUrl	string	—	ヘッダー画像の公開 HTTPS URL (RJReport.Branding.HeaderImageUrl).
FooterImageUrl	string	—	フッター画像の公開 HTTPS URL (RJReport.Branding.FooterImageUrl).
FooterLink	string	—	フッター画像のリンク先 URL (RJReport.Branding.FooterLink). そのまま渡され、検証はされません。
AccentColor	string	—	アクセント色 (RJReport.Branding.AccentColor). そのまま渡されます。16進形式は Send-RjRbReportEmail.
TextColor	string	—	テキスト色 (RJReport.Branding.TextColor). 同じ扱いです。 AccentColor.
TimeoutSec	int	30	画像ごとのダウンロード タイムアウト。
MaxImageBytes	long	200KB	許容される画像サイズの上限。ブランディング画像はレポート添付ファイルと約 4 MB の sendMail 制限を共有します。

出力

A [hashtable] 成功して解決されたキーのみを含む:

キー	値
HeaderImage	ダウンロードされたヘッダー画像のローカル パス
FooterImage	ダウンロードされたフッター画像のローカル パス
FooterLink	トリミングされたフッター リンク
AccentColor	トリミングされたアクセント色
TextColor	トリミングされたテキスト色

各キーは Send-RjRbReportEmail のパラメーターに対応しているため、splatting を安全に使えます。

検証

各画像は受け入れられる前に次のチェックを通過します:

チェック	拒否理由
URL スキーム	許可されるのは https のみです — 画像のバイトは会社のメール内に入るため、プレーン HTTP は拒否されます。
ダウンロード	2xx 以外の応答、タイムアウト、ネットワーク エラーは捕捉されます。ストレージ エラーの応答本文が、黙って画像として扱われることはありません。
サイズ	空のファイルと MaxImageBytes より大きいファイルは除外されます (既定 200 KB)。
ファイル署名	先頭のバイトで PNG、JPEG、GIF のいずれかであることを識別できる必要があります。HTML エラー ページが .png という名前で保存されていた場合はここで拒否されます。

一時ファイルには、検出された 形式に 一致する拡張子が付けられます。これは Send-RjRbReportEmail が添付ファイルのコンテンツ タイプをそこから導き出すためです — そのため、ファイル拡張子のない URL や誤解を招く拡張子の URL でも正しく動作します。

動作上の注意

画像のホスティング

URL は Azure Automation サンドボックスから到達できれば十分です。よくあるパターンは 2 つあります:

• 公開 blob または CDN — 最も簡単ですが、画像は誰でも閲覧できます。
• URL に SAS Token を含むプライベート コンテナー — コンテナーは非公開のままで、リンクを持つ人だけが読み取れます。SAS の有効期限が切れると、ブランディングは静かに終了することに注意してください。有効期限後は、レポートは引き続き RealmJoin の既定値で届き、理由はジョブ ログの警告としてのみ表示されます。

一時ファイルのクリーンアップ

ダウンロードされた画像はサンドボックスの temp ディレクトリに書き込まれます。サンドボックスは実行後に破棄されるため、クリーンアップは任意です — ただし、明示的なクリーンアップ領域を持つ runbook では、最後のメールの後に削除する必要があります:

foreach ($brandingKey in @('HeaderImage', 'FooterImage')) {
    if ($brandingMailParams -and $brandingMailParams.ContainsKey($brandingKey) -and (Test-Path -LiteralPath $brandingMailParams[$brandingKey])) {
        Remove-Item -LiteralPath $brandingMailParams[$brandingKey] -Force -ErrorAction SilentlyContinue
    }
}

ブランディングが表示されない場合の診断

ブランディングが設定されているのにレポートが既定のグラフィックで届く場合、ジョブ ログが失敗した段階を特定します:

ログ エントリ	原因
なし ブランディング: のエントリがまったくない	設定が runbook に届いていません — カスタマイズ JSON と、ポータルがこの runbook バージョンを認識しているかを確認してください。
HTTPS URL のみがサポートされています	URL が http://.
次のようなストレージ エラー PublicAccessNotPermitted	認証されていないまま要求が届きました — SAS Token が URL から欠落しています。コピー時に切り捨てられたことがよくあります。
はインライン メール画像の… 制限を超えています	ファイルは MaxImageBytes.
PNG、JPEG、GIF 画像ではありません	ダウンロード結果は画像以外のもので、通常はエラー ページです。

関連項目

• Send-RjRbReportEmail — 返されたパラメーターの利用側。
• Runbook レポート設定 — の設定 RJReport.Branding.* を管理者として構成すること。