Get-RjRbBrandingMailParams

Résolvez les paramètres du Tenant RJReport.Branding en paramètres prêts à l’emploi pour Send-RjRbReportEmail.

Aperçu

Get-RjRbBrandingMailParams fait le lien entre la configuration centrale paramètres de branding des e-mails et Send-RjRbReportEmail: les paramètres contiennent URL, la fonction d'envoi attend des chemins de fichiers locaux. Cette fonction télécharge les images configurées, les valide et renvoie une table de hachage qui peut être splattée directement dans l'appel d'envoi.

Disponible à partir de RealmJoin.RunbookHelper 0.8.9. Les versions antérieures du runbook intégraient cette logique sous forme d'aide intégrée du même nom ; ces copies peuvent être supprimées une fois que le compte Automation exécute la version 0.8.9 ou ultérieure.

Règles de conception :

• Ne fait jamais échouer le rapport. Tout problème — paramètre vide, URL non HTTPS, téléchargement échoué, fichier trop volumineux, image invalide, couleur mal formée — entraîne un avertissement et l'omission de cette clé unique. L'e-mail est alors rendu avec la valeur par défaut RealmJoin correspondante.
• Ne renvoie que ce qui a été résolu. La table de hachage renvoyée ne contient que les clés qui ont réussi, donc son utilisation en splatting n'écrase jamais une valeur par défaut par une valeur vide.
• Un téléchargement par exécution. Appelez-le une seule fois et réutilisez le résultat pour chaque e-mail envoyé par le runbook — y compris dans les boucles qui notifient de nombreux utilisateurs.

Démarrage rapide

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

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

Sans branding configuré, $brandingMailParams est une table de hachage vide et l'appel se comporte exactement comme si le paramètre avait été omis.

Paramètres

Tous les paramètres sont facultatifs — la fonction est conçue pour être appelée avec tout ce que le Tenant a configuré.

Paramètre	Type	Valeur par défaut	Description
HeaderImageUrl	string	—	URL HTTPS publique de l'image d'en-tête (RJReport.Branding.HeaderImageUrl).
FooterImageUrl	string	—	URL HTTPS publique de l'image de pied de page (RJReport.Branding.FooterImageUrl).
FooterLink	string	—	URL cible de l'image de pied de page (RJReport.Branding.FooterLink). Transmis tel quel, non validé.
AccentColor	string	—	Couleur d'accent (RJReport.Branding.AccentColor). Transmis tel quel ; le format hexadécimal est validé par Send-RjRbReportEmail.
TextColor	string	—	Couleur du texte (RJReport.Branding.TextColor). Même traitement que AccentColor.
TimeoutSec	int	30	Délai d'attente de téléchargement par image.
MaxImageBytes	long	200 Ko	Taille maximale d'image acceptée. Les images de branding partagent la limite d'environ 4 Mo avec les pièces jointes du rapport. sendMail limite avec les pièces jointes du rapport.

Sorties

Un [hashtable] contenant uniquement les clés résolues avec succès :

Clé	Valeur
Image d'en-tête	Chemin local de l'image d'en-tête téléchargée
Image de pied de page	Chemin local de l'image de pied de page téléchargée
FooterLink	Lien de pied de page sans espaces superflus
AccentColor	Couleur d'accent sans espaces superflus
TextColor	Couleur du texte sans espaces superflus

Chaque clé correspond à un paramètre de Send-RjRbReportEmail, ce qui rend l'utilisation du splatting sûre.

Validation

Chaque image passe par les vérifications suivantes avant d'être acceptée :

Vérification	Raison du rejet
Schéma d'URL	Seul https est accepté — les octets de l'image se retrouvent dans les e-mails de l'entreprise, donc HTTP simple est refusé.
Téléchargement	Les réponses non-2xx, les délais d'attente et les erreurs réseau sont interceptés ; le corps de réponse d'une erreur de stockage n'est pas traité silencieusement comme une image.
Taille	Les fichiers vides et les fichiers plus volumineux que MaxImageBytes (200 Ko par défaut).
Signature de fichier	Les premiers octets doivent identifier un PNG, un JPEG ou un GIF. Une page d'erreur HTML enregistrée sous un .png nom est rejetée ici.

Le fichier temporaire reçoit l'extension correspondant à son détecté format, car Send-RjRbReportEmail en déduit le type de contenu de la pièce jointe — une URL sans extension de fichier, ou avec une extension trompeuse, fonctionne donc correctement.

Notes de comportement

Hébergement des images

L'URL doit seulement être accessible depuis le bac à sable Azure Automation. Deux schémas courants :

• Blob public ou CDN — le plus simple, mais les images sont lisibles par n'importe qui.
• Conteneur privé avec un SAS Token dans l'URL — le conteneur reste privé et seuls les détenteurs du lien peuvent le lire. N'oubliez pas que l'expiration du SAS met fin au branding sans avertissement : une fois expiré, les rapports continuent d'arriver avec les valeurs par défaut RealmJoin et la raison n'apparaît qu'en tant qu'avertissement dans le journal du travail.

Nettoyage du fichier temporaire

Les images téléchargées sont écrites dans le répertoire temporaire du bac à sable. Le bac à sable est supprimé après l'exécution, donc le nettoyage est facultatif — mais les runbooks comportant une section de nettoyage explicite doivent les supprimer après le dernier e-mail :

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

Diagnostic d'un branding qui n'apparaît pas

Lorsqu'un rapport arrive avec les graphiques par défaut alors que le branding est configuré, le journal du travail identifie l'étape qui a échoué :

Entrée du journal	Cause
Aucun Branding : entrée du tout	Les paramètres n'ont jamais atteint le runbook — vérifiez le JSON de personnalisation et si le portail connaît cette version du runbook.
Seules les URL HTTPS sont prises en charge	L'URL utilise http://.
Une erreur de stockage telle que PublicAccessNotPermitted	La requête est arrivée sans authentification — le SAS Token est absent de l'URL, souvent parce qu'il a été tronqué lors de la copie.
dépasse la limite … pour les images e-mail intégrées	Le fichier est plus volumineux que MaxImageBytes.
n'est pas une image PNG, JPEG ou GIF	Le téléchargement a renvoyé autre chose qu'une image, généralement une page d'erreur.

Voir aussi

• Send-RjRbReportEmail — le consommateur des paramètres renvoyés.
• Paramètres de rapport du runbook — la configuration des RJReport.Branding.* paramètres en tant qu'administrateur.