Send-RjRbReportEmail

Azure Automation の Runbook から Microsoft Graph を介してブランド付き HTML レポートメールを Markdown コンテンツで送信します。

概要

Send-RjRbReportEmail RealmJoin のレポート runbook からレポートメールを送信するための標準ヘルパーです。Markdown コンテンツを受け取り、RealmJoin ブランドのレスポンシブ HTML メールに変換し、任意のファイルとインラインのブランド画像（ヘッダー/フッター）を添付し、結果を Microsoft Graph の sendMail エンドポイント。

このリリースで名前が変更されました。 この関数は次の名前から改名されました: Send-RjReportEmail に Send-RjRbReportEmail モジュールの他の部分との命名の一貫性を保つため（*-RjRb*）。旧名 Send-RjReportEmail は後方互換の別名としてエクスポートされるため、既存の runbook は変更なしでそのまま動作します — ただし、新しい runbook では次を呼び出す必要があります: Send-RjRbReportEmail.

主な特徴:

• Markdown 入力、HTML 出力 — runbook はレポート本文を Markdown で作成し、この関数がそれをテーマ付き HTML にレンダリングします。これは Outlook Classic、New Outlook、Outlook Web、モバイル クライアント、ダーク モード全体で機能します。
• 受信者ごとに 1 通のメール — 複数の受信者が指定された場合、この関数は 1 通の複数受信者宛てメールではなく、各アドレスに個別のメッセージを送信します。これはプライバシー保護のため、既定で BCC を前提とした設計です。
• インラインのブランド付きヘッダーとフッター — 同梱の PNG アセットは CID 添付として送信され、埋め込み HTML から参照されます。どちらも上書きまたは完全に非表示にできます。
• 自動接続 — Graph セッションがアクティブでない場合、この関数は透過的に次を呼び出します: Connect-RjRbGraph （または Connect-MgGraph -Identity 場合 -UseNativeGraphRequest が設定されている）。
• 堅牢 — 添付ファイルの読み取り失敗、画像オーバーライドの欠落、または受信者ごとの sendMail 失敗は報告されますが、 すべての 受信者が失敗しない限り、バッチ全体は中断されません。

集中管理されたメール設定（送信者アドレス、サービス デスク情報）は次で文書化されています: Runbook レポート設定 — このドキュメントでは、runbook から関数を呼び出す方法に焦点を当てています。

前提条件

送信者メールボックス

ライセンス付きの Microsoft 365 メールボックス（通常は次のような専用の共有メールボックス） [e-mail]) が次のために必要です: From アドレス。Automation Account のマネージド ID には、Graph のアプリケーション権限を介してそのメールボックスの代理送信を許可する必要があります（アイデンティティを 1 つのメールボックスに制限したい場合は、RBAC for Applications でスコープを制限できます）。 Mail.Send application permission (scoped via RBAC for Applications if you want to restrict the identity to a single mailbox).

Graph 権限

シナリオ	必要な権限
既定（Invoke-RjRbRestMethodGraph)	Mail.Send （Application）を送信者メールボックス上で
あり -UseNativeGraphRequest	同じです — 呼び出しは引き続き次に到達します: /users/{id}/sendMail

モジュール接続

既定では、この関数は次を使用します: Invoke-RjRbRestMethodGraph このモジュールのものを使用します。接続がアクティブでない場合は、次を介して自動接続します: Connect-RjRbGraph。その場合 -UseNativeGraphRequest が設定されている場合、この関数は代わりに次を確認します: Get-MgContext そして次を呼び出します: Connect-MgGraph -Identity -NoWelcome 必要に応じて。

クイック スタート

最小限の呼び出しには、送信者、受信者、件名、および Markdown 本文だけが必要です:

Send-RjRbReportEmail `
    -EmailFrom "[e-mail]" `
    -EmailTo   "[e-mail]" `
    -Subject   "Weekly Report" `
    -MarkdownContent @"
# 週間レポート

こんにちは、Alice さん、

今週の数値は次のとおりです:

- 登録された新しいデバイス: **42**
- ライセンス準拠率: **98%**
"@

これにより、既定のヘッダーとフッター、ライト/ダーク モード対応、フッター内の Tenant/バージョン ブロックを備えた、完全にブランド化された RealmJoin メールが生成されます。

パラメーター

必須

パラメーター	種類	説明
EmailFrom	string	送信者メールボックスのユーザー プリンシパル名またはオブジェクト ID。次の用途で使用されます: /users/{id}/sendMail.
EmailTo	string	受信者アドレス。 単一の文字列 — 複数のアドレスは、以下のとおりカンマ区切りのリストとして渡されます。
件名	string	件名。HTML の <title> 要素にも挿入されます。
MarkdownContent	string	Markdown 形式のレポート本文。サポートされる構文は Markdown Support を参照してください。

オプション — コンテンツ

パラメーター	種類	既定値	説明
添付ファイル	string[]	@()	添付するローカル ファイル パス。存在しないファイルはログに記録されてスキップされ、読み取れないファイルは警告を出しますが、送信は中断されません。MIME タイプはファイル拡張子から推定されます。
saveToSentItems	bool	$true	If $true 送信されたメッセージを送信者メールボックスの Sent Itemsに保持する場合は $false 大量のレポート送信では、メールボックスがいっぱいにならないようにするために設定します。
TenantDisplayName	string	—	コンテンツ領域の末尾に埋め込まれた tenant-info ボックスに表示されます。
ReportVersion	string	—	tenant-info ボックスに表示されます（セマンティック バージョン文字列、ビルド番号、または runbook 名 + 日付を使用してください）。

オプション — ブランディング

パラメーター	種類	既定値	説明
HeaderImage	string	同梱 Assets/Header.png	既定のヘッダー画像を上書きする PNG/JPG/GIF へのローカル ファイル パス。 runbook は、URL/blob を事前にローカル ファイルに解決しておく必要があります （たとえば次を使って: Get-AzStorageBlobContent）。欠落または読み取れない上書きは、同梱の既定値にフォールバックし、警告を出します。
FooterImage	string	同梱 Assets/Footer.png	同じ扱いです HeaderImage。フッターは 1 つのクリック可能な画像としてレンダリングされます — ブランド文言、ロゴ、URL はすべて PNG に埋め込んでおく必要があります。
FooterLink	string	https://www.realmjoin.com	フッター画像を囲むアンカーの href および title として使用される URL。
NoHeader	スイッチ	無効	ヘッダー画像を完全に抑制します。次と組み合わせると HeaderImage、警告が出力され、上書きは無視されます。
NoFooter	スイッチ	無効	フッター画像とそのリンクを完全に抑制します。次と組み合わせると FooterImage またはカスタムの FooterLink、警告が出力され、それらの値は無視されます。

推奨画像サイズ: 750 × 200 px の PNG です。これはメール コンテナーの幅と同梱の既定値に一致します。アスペクト比が大きく異なると、狭いビューポートでは歪んで見える場合があります。各画像は 3 MB を十分下回るようにしてください — Graph ではリクエスト全体が 4 MB に制限されており、いずれかの画像が 3 MB を超えると警告が出力されます。 sendMail リクエスト全体が 4 MB に制限されており、いずれかの画像が 3 MB を超えると警告が出力されます。

オプション — 送信

パラメーター	種類	既定値	説明
UseNativeGraphRequest	スイッチ	無効	次を介して送信します: Invoke-MgGraphRequest （ Microsoft.Graph モジュールと Connect-MgGraph セッションが必要）で、次の代わりに使用します: Invoke-RjRbRestMethodGraph。runbook が RealmJoin ラッパーではなくネイティブ SDK を中心に構築されている場合に使用します。

使用例

複数の受信者

EmailTo 1 つ以上のカンマ区切りアドレスを含む単一の文字列を受け付けます。各アドレスは前後の空白が除去され、空の項目は削除され、 受信者ごとに個別のメールが 1 通ずつ送信されます — 受信者同士は互いに見えません。

Send-RjRbReportEmail `
    -EmailFrom "[e-mail]" `
    -EmailTo   "[e-mail], [e-mail], [e-mail]" `
    -Subject   "Monthly Inventory" `
    -MarkdownContent $reportMd

添付ファイルと Tenant メタデータ付き

$csvPath = Join-Path $env:TEMP 'devices.csv'
$exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

Send-RjRbReportEmail `
    -EmailFrom         "[e-mail]" `
    -EmailTo           "[e-mail]" `
    -Subject           "Device Inventory — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent   $reportMd `
    -Attachments       @($csvPath, "$env:TEMP\summary.xlsx") `
    -TenantDisplayName "Contoso Ltd" `
    -ReportVersion     "DeviceInventory v1.4.2"

添付されたファイルは、メッセージの実際の添付ファイルとして追加されるだけでなく、メール本文下部の「Attached Files」ボックスにも一覧表示されます。

カスタムのヘッダー/フッター ブランディング

アセットをまずローカル パスにダウンロードしてから、そのパスを渡して独自のブランディングを適用します。この関数自体は URL を取得しません。

# ブランディング アセットを Azure Blob Storage から runbook の一時フォルダーへ解決
$headerPath = Join-Path $env:TEMP 'contoso-header.png'
$footerPath = Join-Path $env:TEMP 'contoso-footer.png'

Get-AzStorageBlobContent -Container 'branding' -Blob 'header.png' -Destination $headerPath -Force | Out-Null
Get-AzStorageBlobContent -Container 'branding' -Blob 'footer.png' -Destination $footerPath -Force | Out-Null

Send-RjRbReportEmail `
    -EmailFrom        "[e-mail]" `
    -EmailTo          "[e-mail]" `
    -Subject          "Branded Report" `
    -MarkdownContent  $reportMd `
    -HeaderImage      $headerPath `
    -FooterImage      $footerPath `
    -FooterLink       "https://intranet.contoso.com/it-reports"

If $headerPath が見つからない、または読み取れない場合でも、呼び出しは成功します — 同梱の RealmJoin 既定値が使用され、警告がログに記録されます。

プレーン コンテンツ（ヘッダー/フッターなし）

マーケティングメールのように見せたくないアラート形式の通知向け:

Send-RjRbReportEmail `
    -EmailFrom       "[e-mail]" `
    -EmailTo         "[e-mail]" `
    -Subject         "[ALERT] License threshold exceeded" `
    -MarkdownContent "## License threshold exceeded`n`nSee dashboard for details." `
    -NoHeader `
    -NoFooter

ネイティブ Microsoft.Graph SDK の使用

runbook がすでに次を通じて認証されている場合: Connect-MgGraph （マネージド ID）で、RealmJoin ラッパーを混在させたくない場合:

Connect-MgGraph -Identity -NoWelcome

Send-RjRbReportEmail `
    -EmailFrom             "[e-mail]" `
    -EmailTo               "[e-mail]" `
    -Subject               "Native Graph send" `
    -MarkdownContent       $reportMd `
    -UseNativeGraphRequest

レポート本文をファイルから読み込む

大きなレポートでは、Markdown を .md ファイルに生成して読み込みます:

$reportMd = Get-Content -Path .\generated-report.md -Raw

Send-RjRbReportEmail `
    -EmailFrom       "[e-mail]" `
    -EmailTo         "[e-mail]" `
    -Subject         "Weekly Report" `
    -MarkdownContent $reportMd

アクション ボタン（CTA）

Markdown リンクに {button} を付加することで、1 つ以上のブランド付きボタンをレンダリングします。同じ行に置かれたボタンは 1 行にまとめられます:

$reportMd = @"
# アクセス要求

新しいデバイスのアクセス要求があなたの判断を待っています。

[Approve](https://portal.contoso.com/approve/123){button} [Reject](https://portal.contoso.com/reject/123){button}
"@

Send-RjRbReportEmail `
    -EmailFrom       "[e-mail]" `
    -EmailTo         "[e-mail]" `
    -Subject         "Action required: device access request" `
    -MarkdownContent $reportMd

各ボタンは CTA としてスタイル付けされた通常のハイパーリンクです — すべてのクライアントで安全に機能し、モダン クライアントでは角丸、Outlook Classic では角が四角になります。

Markdown Support

この関数には、組み込みの軽量 Markdown → HTML 変換器が付属しています。 外部の Markdown モジュールは不要です。 サポートされる構文:

Markdown	注記
# … ###### 見出し	6 レベルすべてに対応。次の後の空白は # は省略可能です。 h1 には下線が付きます。間隔は Outlook 向けに調整されています。
**太字**, *斜体*, ~~取り消し線~~	インライン専用（複数行にまたがってはいけません）。
`inline code`	次のようにレンダリングされます: <code> 薄いグレーの背景付きで。
lang ... のフェンス付きコード ブロック	言語タグは次のように保持されます: class="language-…"。不正な単一バックティックのフェンスも許容します。
[text](url) リンク	次を使用して新しいタブで開きます: noopener noreferrer.
[label](url){button} リンク ボタン	通常のリンクではなく、ブランド付きのオレンジ色の CTA ボタンとしてレンダリングされます。複数の {button} 同じ行上の 同じ行 は 1 行に並んでレンダリングされます（幅は均等に分割）。角丸はモダン クライアント（New Outlook、OWA、モバイル）で表示され、Outlook Classic（Word エンジン）では角が四角になります。
 画像	次のように挿入されます: <img> （インライン添付の特別処理はありません — URL はメール クライアントから到達可能である必要があります）。
- 項目 / 1. 項目 リスト	各レベル 2 スペースのインデントでネストされたリストをサポートします。順序付きリストと順序なしリストを混在させると、前のリストが閉じられます。
複数行のリスト項目	インデントされた空でない行が直下にある <li> は、同じ項目に折りたたまれ、 <br> のソフト ブレークになります — 各項目を 1 行に保つ必要はありません。
- [ ] / - [x] タスクリスト	次のようにレンダリングされます: ☐ / ☑ Unicode グリフ（チェック時は緑）。 <input type="checkbox"> Outlook Classic がフォーム コントロールを削除するため、意図的に避けています。大文字の [X] もチェック済みとして扱われます。
> 引用ブロック	色付きの左境界線と陰影付き背景でレンダリングされます。
> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]	GitHub 風の注意書きです。引用ブロックの 1 行目はマーカーのみで、残りの >- で始まる行が本文です。種類ごとに専用のアクセント色、グリフ、タイトル バーが付きます。
---, ***, ___	水平線。
|col|col| テーブル	配置指定子付きの標準的なパイプ テーブルです。 :---, :---:, ---: ヘッダー行と区切り行が必要です。
\\ エスケープ	\*, | などは尊重されるため、Markdown 文字をそのまま出力できます。

サポートされない項目には脚注、定義リスト、HTML パススルーが含まれます — Markdown は上の表の範囲にとどめてください。

動作とエラー処理

受信者の解析

EmailTo カンマで分割され、各項目はトリムされ、空の項目は削除されます。結果のリストが空の場合、この関数は次をスローします: EmailTo パラメーターに有効なメール受信者が見つかりませんでした。 Graph の呼び出しが行われる前に。

受信者ごとの失敗

各受信者には個別に送信されます。この関数は成功と失敗を追跡します:

• If 少なくとも 1 つの 送信が成功し、他が失敗した場合、失敗したアドレスを列挙する警告が出力されます。関数は通常どおり戻ります。
• If すべての 送信がすべて失敗した場合、この関数は次をスローします: すべての受信者へのメール送信に失敗しました: … そのため、runbook は明確に失敗します。

添付ファイルの失敗

• 存在しないファイル（パスが存在しない）— 詳細にログへ記録され、黙ってスキップされます。
• 存在するが読み取れないファイル（ロック中、権限不足）— 警告が出力され、スキップされ、呼び出しの残りは続行されます。
• メール下部の「Attached Files」ボックスには、正常に読み取れた添付ファイルだけが一覧表示されます。

画像オーバーライドの失敗

両方 HeaderImage および FooterImage エラー（ファイル不足、未サポートの拡張子、IO エラー）の場合は、同梱の既定値にフォールバックします。警告では失敗内容と、どの既定値が使用されたかが示されます。

合計サイズの上限

Graph の上限 sendMail 合計で約 4 MB（HTML 本文 + すべての添付ファイル、base64 エンコード）に収めます。いずれかのブランド画像が 3 MB を超えると、関数は警告を出します。それでも総ペイロードが 4 MB を超える場合、Graph 呼び出し自体が失敗します。次を検討してください:

• 大きなデータは代わりに Storage Account チャネルへアップロードする — 参照: Runbook レポート設定.
• 埋め込むのではなく、外部ホストの添付ファイルへリンクする。
• 表形式データを圧縮する（Compress-Archive）を添付する前に。

Runbook Report Settings との統合

レポート用 runbook は通常、送信者アドレスをハードコードせず、中央の RealmJoin カスタマイズ JSON から解決します。関連する設定は Runbook レポート設定に記載されています。runbook での典型的な解決パターンは次のとおりです:

# 集中管理された設定を読み込む（runbook フレームワークによって解決）
$emailFrom = (Get-RjRbDefaultValue -Name 'EmailSender' -Section 'RJReport')

if (-not $emailFrom) {
    throw "EmailSender が構成されていません。セットアップ手順は https://docs.realmjoin.com/ を参照してください。"
}

Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $RecipientParameter `
    -Subject         $Subject `
    -MarkdownContent $reportMd `
    -TenantDisplayName $TenantDisplayName `
    -ReportVersion     "MyReport v1.0"

出力

成功時、この関数は何も返しません。進捗はすべて Write-RjRbLog -Verbose を通じて書き込まれます（runbook を -Verbose または $VerbosePreference = 'Continue'付きで実行すると表示されます）。警告は $WarningPreference = 'Continue' を通じて、呼び出し側の上書きにかかわらず強制的に出力されるため、Azure Automation のジョブ ストリームに確実に表示されます。

関連するエクスポート済みヘルパー

の基盤となる構成要素も Send-RjRbReportEmail もモジュールからエクスポートされるようになったため、runbook は送信せずに HTML を組み立てたりプレビューしたりできます:

関数	目的
ConvertFrom-RjRbMarkdownToHtml	単体で動作する Markdown → HTML 変換器（内部で使用している同じ軽量エンジン。これには {button} の構文も含まれます）。
Get-RjRbReportEmailBody	HTML または Markdown から、ブランド付きの完全な HTML 本文（ヘッダー/フッター、Tenant 情報ボックス、添付ファイル一覧）を組み立てます。送信前にメールをレンダリングして確認するのに便利です。
Resolve-RjRbImageSource	ヘッダー/フッター画像のパスをインライン CID ソースに解決し、エラー時には同梱の既定値にフォールバックします。

これらは主に高度な用途／テスト用シナリオ向けです。通常の方法は次を呼び出すことです: Send-RjRbReportEmail 直接。

関連項目

• Runbook レポート設定 — 送信元メールボックス、サービスデスク情報、および Storage Account 配信チャネルの中央設定。
• Microsoft Graph: メール送信 — 基盤となる API。