Get-RjRbBrandingMailParams

Überführen Sie die RJReport.Branding-Tenant-Einstellungen in sofort verwendbare Parameter für Send-RjRbReportEmail.

Übersicht

Get-RjRbBrandingMailParams überbrückt die Lücke zwischen den zentralen E-Mail-Branding-Einstellungen und Send-RjRbReportEmail: die Einstellungen enthalten URLs, die Sendefunktion erwartet lokale Dateipfade. Diese Funktion lädt die konfigurierten Bilder herunter, validiert sie und gibt eine Hashtabelle zurück, die direkt in den Sendeaufruf gesplattet werden kann.

Verfügbar ab RealmJoin.RunbookHelper 0.8.9. Frühere Runbook-Versionen enthielten diese Logik als Inline-Helper mit demselben Namen; diese Kopien können gelöscht werden, sobald das Automation Account 0.8.9 oder höher ausführt.

Designregeln:

• Schlägt den Bericht niemals fehl. Jedes Problem — leere Einstellung, nicht-HTTPS-URL, fehlgeschlagener Download, zu große Datei, ungültiges Bild, fehlerhafte Farbe — führt zu einer Warnung und dazu, dass genau dieser Schlüssel weggelassen wird. Die E-Mail wird dann mit dem entsprechenden RealmJoin-Standard gerendert.
• Gibt nur das zurück, was aufgelöst wurde. Die zurückgegebene Hashtabelle enthält nur die Schlüssel, die erfolgreich waren, sodass das Splatten niemals einen Standardwert durch einen leeren Wert überschreibt.
• Ein Download pro Lauf. Einmal aufrufen und das Ergebnis für jede vom Runbook versendete E-Mail wiederverwenden — auch innerhalb von Schleifen, die viele Benutzer benachrichtigen.

Schnellstart

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

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

Ohne konfiguriertes Branding, $brandingMailParams ist eine leere Hashtabelle und der Aufruf verhält sich genau so, als wäre der Parameter weggelassen worden.

Parameter

Alle Parameter sind optional — die Funktion ist dafür ausgelegt, mit dem aufzurufen, was der Tenant zufällig konfiguriert hat.

Parameter	Typ	Standard	Beschreibung
HeaderImageUrl	string	—	Öffentliche HTTPS-URL des Headerbilds (RJReport.Branding.HeaderImageUrl).
FooterImageUrl	string	—	Öffentliche HTTPS-URL des Footerbilds (RJReport.Branding.FooterImageUrl).
FooterLink	string	—	Ziel-URL des Footerbilds (RJReport.Branding.FooterLink). Durchgereicht, nicht validiert.
AccentColor	string	—	Akzentfarbe (RJReport.Branding.AccentColor). Durchgereicht; das Hex-Format wird validiert durch Send-RjRbReportEmail.
TextColor	string	—	Textfarbe (RJReport.Branding.TextColor). Gleiche Behandlung wie AccentColor.
TimeoutSec	int	30	Download-Timeout pro Bild.
MaxImageBytes	long	200 KB	Maximale akzeptierte Bildgröße. Branding-Bilder teilen sich die ~4 MB sendMail Grenze zusammen mit den Berichtsanhängen.

Ausgaben

Ein [Hashtabelle] die nur die erfolgreich aufgelösten Schlüssel enthält:

Schlüssel	Wert
HeaderImage	Lokaler Pfad des heruntergeladenen Headerbilds
FooterImage	Lokaler Pfad des heruntergeladenen Footerbilds
FooterLink	Getrimmter Footer-Link
AccentColor	Getrimmte Akzentfarbe
TextColor	Getrimmte Textfarbe

Jeder Schlüssel entspricht einem Parameter von Send-RjRbReportEmail, was das Splatten sicher macht.

Validierung

Jedes Bild durchläuft vor der Annahme die folgenden Prüfungen:

Prüfung	Ablehnungsgrund
URL-Schema	Nur https wird akzeptiert — die Bilddaten landen in der Firmen-E-Mail, daher wird gewöhnliches HTTP abgelehnt.
Download	Nicht-2xx-Antworten, Timeouts und Netzwerkfehler werden abgefangen; der Response-Body eines Speicherfehlers wird nicht stillschweigend als Bild behandelt.
Größe	Leere Dateien und Dateien größer als MaxImageBytes (Standard 200 KB).
Dateisignatur	Die ersten Bytes müssen ein PNG, JPEG oder GIF identifizieren. Eine HTML-Fehlerseite, die unter einem .png Namen gespeichert wurde, wird hier abgelehnt.

Die temporäre Datei erhält die Erweiterung, die zu ihrem erkannten Format passt, weil Send-RjRbReportEmail daraus den Inhaltstyp des Anhangs ableitet — eine URL ohne Dateiendung oder mit einer irreführenden Endung funktioniert daher korrekt.

Verhaltenshinweise

Das Hosten der Bilder

Die URL muss nur von der Azure Automation-Sandbox aus erreichbar sein. Zwei gängige Muster:

• Öffentliches Blob oder CDN — am einfachsten, aber die Bilder sind für jeden lesbar.
• Privater Container mit einem SAS Token in der URL — der Container bleibt privat und nur Inhaber des Links können ihn lesen. Beachten Sie, dass das Ablaufdatum des SAS das Branding stillschweigend beendet: Nach Ablauf kommen Berichte weiterhin mit den RealmJoin-Standardwerten an, und der Grund ist nur als Warnung im Auftragsprotokoll sichtbar.

Bereinigung temporärer Dateien

Heruntergeladene Bilder werden in das Temp-Verzeichnis der Sandbox geschrieben. Die Sandbox wird nach dem Lauf verworfen, daher ist die Bereinigung optional — Runbooks mit einem expliziten Bereinigungsabschnitt sollten sie jedoch nach der letzten E-Mail entfernen:

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
    }
}

Diagnose von nicht erscheinendem Branding

Wenn ein Bericht trotz konfiguriertem Branding mit den Standardgrafiken ankommt, identifiziert das Auftragsprotokoll die fehlgeschlagene Phase:

Protokolleintrag	Ursache
Kein Branding: Eintrag überhaupt	Die Einstellungen haben das Runbook nie erreicht — prüfen Sie das Anpassungs-JSON und ob das Portal diese Runbook-Version kennt.
Es werden nur HTTPS-URLs unterstützt	Die URL verwendet http://.
Ein Speicherfehler wie PublicAccessNotPermitted	Die Anfrage kam nicht authentifiziert an — das SAS Token fehlt in der URL, oft weil es beim Kopieren abgeschnitten wurde.
überschreitet das Limit … für inline E-Mail-Bilder	Die Datei ist größer als MaxImageBytes.
kein PNG-, JPEG- oder GIF-Bild	Der Download lieferte etwas anderes als ein Bild, typischerweise eine Fehlerseite.

Siehe auch

• Send-RjRbReportEmail — der Verbraucher der zurückgegebenen Parameter.
• Runbook-Berichtseinstellungen — das Konfigurieren der RJReport.Branding.* Einstellungen als Administrator.