Dieser Artikel wurde automatisch übersetzt. Die Übersetzung kann Ungenauigkeiten enthalten.
Zur englischen Originalversion wechseln.
Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Send-RjRbReportEmail

Senden Sie gebrandete HTML-Report-E-Mails aus Azure Automation-Runbooks über Microsoft Graph mithilfe von Markdown-Inhalten.

Übersicht

Send-RjRbReportEmail ist der Standard-Helfer zum Ausliefern von Bericht-E-Mails aus RealmJoin-Reporting-Runbooks. Er nimmt Markdown-Inhalt entgegen, wandelt ihn in eine responsiv gestaltete HTML-E-Mail im RealmJoin-Branding um, fügt optionale Dateien und eingebettete Branding-Grafiken (Header/Footer) hinzu und sendet das Ergebnis über Microsoft Graph sendMail -Endpunkt.

In diesem Release umbenannt. Die Funktion wurde umbenannt von Send-RjReportEmail zu Send-RjRbReportEmail zur einheitlichen Benennung mit dem Rest des Moduls (*-RjRb*). Der alte Name Send-RjReportEmail wird als rückwärtskompatibler Alias exportiert, sodass vorhandene Runbooks unverändert weiter funktionieren — neue Runbooks sollten jedoch Send-RjRbReportEmail.

Wesentliche Merkmale:

  • Markdown rein, HTML raus — Runbooks verfassen den Berichtstext in Markdown; die Funktion rendert ihn zu thematischem HTML, das in Outlook Classic, dem neuen Outlook, Outlook im Web, mobilen Clients und im Dunkelmodus funktioniert.

  • Eine E-Mail pro Empfänger — wenn mehrere Empfänger angegeben werden, sendet die Funktion an jede Adresse eine einzelne Nachricht statt einer einzigen Mail mit mehreren Empfängern. Dies ist ein datenschutzorientiertes BCC-by-default-Design.

  • Inline-Branding für Header & Footer — mitgelieferte PNG-Assets werden als CID-Anhänge gesendet und vom eingebetteten HTML referenziert. Beide können überschrieben oder vollständig unterdrückt werden.

  • Selbstverbindend — wenn keine Graph-Sitzung aktiv ist, ruft die Funktion transparent Connect-RjRbGraph (oder Connect-MgGraph -Identity auf, wenn -UseNativeGraphRequest gesetzt ist).

  • Robust — fehlgeschlagene Lesevorgänge von Anhängen, fehlende Bild-Überschreibungen oder sendMail-Fehler pro Empfänger werden gemeldet, brechen aber nicht den gesamten Batch ab, es sei denn alle Empfänger schlagen fehl.

Zentralisierte E-Mail-Einstellungen (Absenderadresse, Service-Desk-Informationen) sind dokumentiert in Runbook-Report-Einstellungen — dieses Dokument konzentriert sich darauf, die Funktion aus einem Runbook aufzurufen.

Voraussetzungen

Absenderpostfach

Ein lizenziertes Microsoft 365-Postfach (typischerweise ein dediziertes freigegebenes Postfach wie realmjoin-report@contoso.com) ist als From -Adresse erforderlich. Der verwalteten Identität des Automation Accounts muss erlaubt sein, im Namen dieses Postfachs über die Graph Mail.Send Anwendungsberechtigung zu senden (über RBAC für Anwendungen eingeschränkt, wenn Sie die Identität auf ein einzelnes Postfach beschränken möchten).

Graph-Berechtigungen

Szenario
Erforderliche Berechtigung

Standard (Invoke-RjRbRestMethodGraph)

Mail.Send (Anwendung) auf dem Absenderpostfach

Mit -UseNativeGraphRequest

Gleich — der Aufruf trifft weiterhin /users/{id}/sendMail

Modulverbindung

Standardmäßig verwendet die Funktion Invoke-RjRbRestMethodGraph aus diesem Modul. Wenn keine Verbindung aktiv ist, stellt sie automatisch über Connect-RjRbGraph. Wenn -UseNativeGraphRequest gesetzt ist, prüft die Funktion stattdessen Get-MgContext und ruft Connect-MgGraph -Identity -NoWelcome bei Bedarf auf.

Schnellstart

Der minimal funktionsfähige Aufruf benötigt nur den Absender, den Empfänger, einen Betreff und den Markdown-Textkörper:

Dadurch entsteht eine vollständig gebrandete RealmJoin-E-Mail mit Standard-Header und -Footer, Unterstützung für Hell-/Dunkelmodus und dem Mandanten-/Versionsblock im Footer.

Parameter

Erforderlich

Parameter
Typ
Beschreibung

EmailFrom

string

Benutzerprinzipalname oder Objekt-ID des Absenderpostfachs. Verwendet als /users/{id}/sendMail.

EmailTo

string

Empfängeradresse. Einzelner String — mehrere Adressen werden als kommagetrennte Liste übergeben, siehe unten.

Subject

string

Betreffzeile. Wird auch in das HTML <title> -Element eingefügt.

MarkdownContent

string

Berichtstext in Markdown. Siehe Markdown-Unterstützung für die unterstützte Syntax.

Optional — Inhalt

Parameter
Typ
Standard
Beschreibung

Attachments

string[]

@()

Lokale Dateipfade, die angehängt werden sollen. Fehlende Dateien werden protokolliert und übersprungen, nicht lesbare Dateien erzeugen eine Warnung, brechen den Versand jedoch nicht ab. Der MIME-Typ wird aus der Dateierweiterung abgeleitet.

saveToSentItems

bool

$true

Wenn $true die gesendete Nachricht im Gesendete Elementedes Absenderpostfachs behalten wird. Setzen Sie es auf $false für Berichte mit hohem Volumen, um das Postfach nicht zu füllen.

TenantDisplayName

string

—

Wird im am Ende des Inhaltsbereichs eingebetteten Mandanten-Info-Kasten angezeigt.

ReportVersion

string

—

Wird im Mandanten-Info-Kasten angezeigt (verwenden Sie semantische Versionszeichenfolgen, Buildnummern oder einen Runbook-Namen + Datum).

Optional — Branding

Parameter
Typ
Standard
Beschreibung

HeaderImage

string

mitgeliefert Assets/Header.png

Lokaler Dateipfad zu einer PNG/JPG/GIF-Datei, die die standardmäßige Headergrafik überschreibt. Das Runbook muss jede URL/jeden Blob vorher in eine lokale Datei auflösen (z. B. über Get-AzStorageBlobContent). Fehlende/nicht lesbare Überschreibungen fallen auf die mitgelieferte Standardvariante zurück und erzeugen eine Warnung.

FooterImage

string

mitgeliefert Assets/Footer.png

Gleiche Handhabung wie HeaderImage. Der Footer wird als einzelnes anklickbares Bild gerendert — jeder Branding-Text, jedes Logo oder jede URL muss in die PNG eingebettet sein.

FooterLink

string

https://www.realmjoin.com

URL, die als href und title des Ankers verwendet wird, der das Footer-Bild umschließt.

NoHeader

Schalter

aus

Unterdrückt die Headergrafik vollständig. Wenn mit HeaderImagekombiniert, wird eine Warnung ausgegeben und die Überschreibung ignoriert.

NoFooter

Schalter

aus

Unterdrückt die Footergrafik und ihren Link vollständig. Wenn mit FooterImage oder einem benutzerdefinierten FooterLinkkombiniert, wird eine Warnung ausgegeben und diese Werte werden ignoriert.

Empfohlene Bildabmessungen: 750 × 200 px PNG. Das entspricht der Breite des E-Mail-Containers und den mitgelieferten Standardwerten. Deutlich andere Seitenverhältnisse können in schmalen Ansichten verzerrt wirken. Jede Grafik sollte deutlich unter 3 MB bleiben — Graph begrenzt die gesamte Anforderung auf 4 MB, und es wird eine Warnung ausgegeben, wenn eines der Bilder 3 MB überschreitet. sendMail Anforderung auf 4 MB, und es wird eine Warnung ausgegeben, wenn eines der Bilder 3 MB überschreitet.

Optional — Transport

Parameter
Typ
Standard
Beschreibung

UseNativeGraphRequest

Schalter

aus

Sendet über Invoke-MgGraphRequest (erfordert Microsoft.Graph Modul und eine Connect-MgGraph Sitzung) statt über Invoke-RjRbRestMethodGraph. Verwenden Sie dies, wenn das Runbook auf dem nativen SDK statt auf dem RealmJoin-Wrapper basiert.

Anwendungsbeispiele

Mehrere Empfänger

EmailTo akzeptiert einen einzelnen String mit einer oder mehreren durch Kommas getrennten Adressen. Jede Adresse wird getrimmt, leere Einträge werden entfernt, und an jeden Empfänger wird eine einzelne E-Mail gesendet — die Empfänger sehen sich nicht gegenseitig.

Mit Anhängen und Mandantenmetadaten

Die angehängten Dateien werden zusätzlich dazu, dass sie als echte Anhänge zur Nachricht hinzugefügt werden, in einem "Attached Files"-Kasten am unteren Rand des E-Mail-Textes aufgelistet.

Benutzerdefiniertes Header-/Footer-Branding

Bringen Sie Ihr eigenes Branding mit, indem Sie die Assets zuerst an einen lokalen Pfad herunterladen und dann die resultierenden Pfade übergeben. Die Funktion ruft URLs nicht selbst ab.

Wenn $headerPath fehlt oder ist nicht lesbar, ist der Aufruf trotzdem erfolgreich — die mitgelieferte RealmJoin-Standardvariante wird verwendet und eine Warnung wird protokolliert.

Reiner Inhalt (ohne Header/Footer)

Für Benachrichtigungen im Alarmstil, die nicht wie eine Marketing-E-Mail aussehen sollen:

Verwendung des nativen Microsoft.Graph SDK

Wenn das Runbook bereits über Connect-MgGraph (verwaltete Identität) authentifiziert ist und Sie den RealmJoin-Wrapper nicht einbinden möchten:

Den Berichtstext aus einer Datei lesen

Für größere Berichte erzeugen Sie das Markdown in einer .md -Datei und lesen Sie sie ein:

Aktionsschaltflächen (Call-to-Action)

Rendern Sie eine oder mehrere gebrandete Schaltflächen, indem Sie {button} an einen Markdown-Link anhängen. Schaltflächen, die in derselben Zeile stehen, werden zu einer einzigen Zeile zusammengefasst:

Jede Schaltfläche ist ein normaler Hyperlink, der als CTA gestaltet ist — sicher in allen Clients, mit abgerundeten Ecken in modernen Clients und eckigen Ecken in Outlook Classic.

Markdown-Unterstützung

Die Funktion wird mit einem integrierten, leichtgewichtigen Markdown-→-HTML-Konverter ausgeliefert. Es ist kein externes Markdown-Modul erforderlich. Unterstützte Syntax:

Markdown
Hinweise

# … ###### Überschriften

Alle sechs Ebenen. Leerzeichen nach # ist optional. h1 erhält eine Unterstreichung; der Abstand ist für Outlook optimiert.

**fett**, *kursiv*, ~~durchgestrichen~~

Nur inline (darf sich nicht über mehrere Zeilen erstrecken).

`inline code`

Gerendert als <code> mit hellgrauem Hintergrund.

lang ... eingerahmte Codeblöcke

Das Sprach-Tag bleibt erhalten als class="language-…". Toleriert auch fehlerhafte Ein-Apostroph-Einrahmungen.

[text](url) Links

In neuem Tab öffnen mit noopener noreferrer.

[label](url){button} Link-Schaltflächen

Wird statt als normaler Link als gebrandete orangefarbene Call-to-Action-Schaltfläche gerendert. Mehrere {button} Links in derselben Zeile werden nebeneinander in einer Zeile dargestellt (Breite gleichmäßig aufgeteilt). Abgerundete Ecken sind in modernen Clients (New Outlook, OWA, mobil) sichtbar; Outlook Classic (Word-Engine) rendert eckige Ecken.

![alt](url) Bilder

Eingefügt als <img> (kein Inline-Anhang-Zauber — die URL muss für den Mail-Client erreichbar sein).

- Element / 1. Element Listen

Verschachtelte Listen werden durch 2 Leerzeichen Einrückung pro Ebene unterstützt. Das Mischen von geordneten und ungeordneten Listen schließt die vorherige Liste.

Mehrzeilige Listenelemente

Eine eingerückte, nicht leere Zeile direkt unter einem <li> wird in dasselbe Element mit einem <br> weichen Zeilenumbruch übernommen — jedes Element muss also nicht in einer Zeile bleiben.

- [ ] / - [x] Aufgabenlisten

Gerendert als ☐ / ☑ Unicode-Symbole (grün, wenn angehakt). <input type="checkbox"> wird absichtlich vermieden, da Outlook Classic Formularsteuerelemente entfernt. Großes [X] gilt ebenfalls als angehakt.

> Blockzitat

Mit farbigem linken Rand und schattiertem Hintergrund gerendert.

> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]

GitHub-artige Hinweise. Die erste Zeile des Blockquotes ist der Marker (allein), die übrigen >-vorangestellten Zeilen sind der Inhalt. Jeder Typ erhält seine eigene Akzentfarbe, sein eigenes Symbol und seine eigene Titelleiste.

---, ***, ___

Horizontale Regel.

|col|col| Tabellen

Standard-Pipe-Tabellen mit :---, :---:, ---: Ausrichtungsangaben. Kopfzeile + Trennzeichen erforderlich.

\\ Maskierung

\*, | usw. werden berücksichtigt, sodass literale Markdown-Zeichen ausgegeben werden können.

Nicht unterstützt werden unter anderem Fußnoten, Definitionslisten und HTML-Passthrough — beschränken Sie das Markdown auf die obige Tabelle.

Verhalten & Fehlerbehandlung

Empfänger-Parsing

EmailTo wird an Kommas aufgeteilt, jeder Eintrag wird getrimmt und leere Einträge werden entfernt. Wenn die resultierende Liste leer ist, wirft die Funktion No valid email recipients found in EmailTo parameter. bevor ein Graph-Aufruf erfolgt.

Fehler pro Empfänger

Jeder Empfänger wird unabhängig gesendet. Die Funktion verfolgt Erfolge und Fehler:

  • Wenn mindestens einer ein Versand erfolgreich ist, andere aber fehlschlagen, wird eine Warnung ausgegeben, die die fehlgeschlagenen Adressen auflistet; die Funktion kehrt normal zurück.

  • Wenn alle Sendungen fehlschlagen, löst die Funktion einen Fehler aus E-Mail konnte nicht an alle Empfänger gesendet werden: … sodass das Runbook mit einer klaren Fehlermeldung fehlschlägt.

Fehler bei Anlagen

  • Fehlende Dateien (Pfad existiert nicht) — ausführlich protokolliert, still übersprungen.

  • Vorhandene, aber nicht lesbare Dateien (gesperrt, Zugriff verweigert) — Warnung ausgegeben, übersprungen, der Rest des Aufrufs läuft weiter.

  • Das Feld "Attached Files" unten in der E-Mail listet nur Anhänge auf, die erfolgreich gelesen werden konnten.

Fehler bei Bildüberschreibungen

Beide HeaderImage und FooterImage weichen bei jedem Fehler (fehlende Datei, nicht unterstützte Erweiterung, IO-Fehler) auf die mitgelieferten Standardwerte aus. Eine Warnung beschreibt den Fehler und nennt, welcher Standardwert verwendet wurde.

Gesamte Größenbeschränkung

Graph begrenzt sendMail Anfragen auf insgesamt etwa 4 MB (HTML-Textkörper + alle Anhänge, base64-kodiert). Die Funktion gibt eine Warnung aus, wenn eines der Branding-Bilder größer als 3 MB ist. Wenn die gesamte Nutzlast weiterhin 4 MB überschreitet, schlägt der Graph-Aufruf selbst fehl; erwägen Sie:

  • große Daten stattdessen über den Storage Account-Kanal hochzuladen — siehe Runbook-Report-Einstellungen.

  • statt sie einzubetten auf extern gehostete Anhänge zu verweisen.

  • Tabellarische Daten komprimieren (Compress-Archive) vor dem Anhängen.

Integration mit Runbook-Report-Einstellungen

Berichts-Runbooks ermitteln die Absenderadresse typischerweise aus dem zentralen RealmJoin-Anpassungs-JSON, statt sie fest zu codieren. Die relevanten Einstellungen sind dokumentiert in Runbook-Report-Einstellungen. Ein typisches Auflösungsmuster in einem Runbook sieht so aus:

Ausgaben

Die Funktion gibt bei Erfolg nichts zurück. Der gesamte Fortschritt wird ausgegeben über Write-RjRbLog -Verbose (sichtbar, wenn das Runbook mit -Verbose oder $VerbosePreference = 'Continue'). Warnungen werden erzwungen über $WarningPreference = 'Continue' unabhängig von Überschreibungen auf Aufruferseite, sodass sie zuverlässig im Azure Automation-Auftragsstream erscheinen.

Verwandte exportierte Helfer

Die Bausteine hinter Send-RjRbReportEmail werden jetzt ebenfalls aus dem Modul exportiert, sodass Runbooks das HTML zusammensetzen oder in der Vorschau ansehen können, ohne es zu senden:

Funktion
Zweck

ConvertFrom-RjRbMarkdownToHtml

Eigenständiger Markdown-→-HTML-Konverter (derselbe leichtgewichtige Engine, die intern verwendet wird, einschließlich der {button} Syntax).

Get-RjRbReportEmailBody

Erstellt den vollständigen gebrandeten HTML-Textkörper (Kopf-/Fußzeile, Tenant-Info-Box, Anhangsliste) aus HTML oder Markdown — nützlich, um die E-Mail vor dem Senden zu rendern und zu prüfen.

Resolve-RjRbImageSource

Löst einen Kopf-/Fußzeilen-Bildpfad zu seiner Inline-CID-Quelle auf und greift bei einem Fehler auf den mitgelieferten Standard zurück.

Diese sind in erster Linie für fortgeschrittene/Test-Szenarien gedacht; der normale Weg ist, Send-RjRbReportEmail sie direkt aufzurufen.

Siehe auch

  • Runbook-Report-Einstellungen — zentrale Konfiguration der Absender-Mailbox, Service-Desk-Informationen und des Storage Account-Zustellkanals.

  • Microsoft Graph: E-Mail senden — zugrunde liegende API.

Zuletzt aktualisiert

War das hilfreich?