Send-RjRbReportEmail
Envoyer des e-mails de rapport HTML à l'effigie de la marque depuis les runbooks Azure Automation via Microsoft Graph à l'aide de contenu Markdown.
Aperçu
Send-RjRbReportEmail est l'assistant standard pour l'envoi d'e-mails de rapport depuis les runbooks de reporting RealmJoin. Il prend du contenu Markdown, le convertit en e-mail HTML responsive à l'image de RealmJoin, joint des fichiers optionnels et des graphiques de branding en ligne (en-tête/pied de page), et envoie le résultat via Microsoft Graph sendMail point de terminaison.
Renommé dans cette version. La fonction a été renommée de
Send-RjReportEmailàSend-RjRbReportEmailpour une cohérence de nommage avec le reste du module (*-RjRb*). L'ancien nomSend-RjReportEmailest exporté comme alias rétrocompatible, de sorte que les runbooks existants continuent de fonctionner sans changement — mais les nouveaux runbooks devraient appelerSend-RjRbReportEmail.
Caractéristiques principales:
Markdown en entrée, HTML en sortie — les runbooks composent le corps du rapport en Markdown ; la fonction le rend en HTML thématique qui fonctionne dans Outlook Classic, New Outlook, Outlook Web, les clients mobiles et le mode sombre.
Un e-mail par destinataire — lorsque plusieurs destinataires sont fournis, la fonction envoie un message individuel à chaque adresse plutôt qu'un seul courrier à plusieurs destinataires. Il s'agit d'une conception axée sur la confidentialité et le BCC par défaut.
En-tête et pied de page brandés en ligne — les ressources PNG fournies sont envoyées comme pièces jointes CID et référencées par le HTML intégré. Les deux peuvent être remplacées ou complètement désactivées.
Couleurs de modèle personnalisables — la couleur d'accentuation et la couleur du texte du modèle peuvent être remplacées à chaque appel, afin que les e-mails de rapport puissent suivre la charte graphique de l'entreprise du client.
Protection intégrée contre la taille des pièces jointes — un ensemble de pièces jointes de secours plus petit et optionnel est envoyé automatiquement lorsque l'ensemble habituel dépasse le budget de taille ou si sa tentative d'envoi échoue.
Connexion automatique — si aucune session Graph n'est active, la fonction appelle de manière transparente
Connect-RjRbGraph(ouConnect-MgGraph -Identityquand-UseNativeGraphRequestest défini).Résiliente — les erreurs de lecture de pièces jointes, les remplacements d'images invalides, les couleurs invalides ou les échecs sendMail par destinataire sont signalés mais n'interrompent pas tout le lot sauf si tous les destinataires échouent.
Les paramètres centralisés des e-mails (adresse de l'expéditeur, informations du service desk) sont documentés dans Paramètres de rapport du runbook — ce document se concentre sur l'appel de la fonction depuis un runbook.
Prérequis
Boîte aux lettres de l'expéditeur
Une boîte aux lettres Microsoft 365 sous licence (généralement une boîte partagée dédiée telle que realmjoin-report@contoso.com) est requise comme adresse De expéditeur Mail.Send L'identité managée du compte Automation doit être autorisée à envoyer au nom de cette boîte aux lettres via l'autorisation d'application Graph (à portée via RBAC pour les applications si vous souhaitez limiter l'identité à une seule boîte aux lettres).
L'expéditeur ne doit pas être un groupe Microsoft 365. La fonction envoie via le point de terminaison Graph
/users/{EmailFrom}/sendMail— un groupe Microsoft 365 n'est pas un objet utilisateur, donc l'appel échoue. Utilisez un utilisateur ou une boîte aux lettres partagée.Les adresses de groupe Microsoft 365 comme destinataires sont techniquement acceptées, mais déconseillées: le message peut n'atteindre que la boîte aux lettres du groupe (les membres ne reçoivent une copie personnelle que s'ils suivent le groupe), la gestion de remise du groupe peut rejeter l'expéditeur, et les échecs de remise n'apparaissent que comme un NDR dans la boîte aux lettres de l'expéditeur — le runbook lui-même indique toujours une réussite. Préférez des adresses de boîte aux lettres individuelles.
Autorisations Graph
Par défaut (Invoke-RjRbRestMethodGraph)
Mail.Send (Application) sur la boîte aux lettres de l'expéditeur
Avec -UseNativeGraphRequest
Identique — l'appel atteint toujours /users/{id}/sendMail
Connectivité du module
Par défaut, la fonction utilise Invoke-RjRbRestMethodGraph de ce module. Si aucune connexion n'est active, elle se connecte automatiquement via Connect-RjRbGraph. Quand -UseNativeGraphRequest est défini, la fonction vérifie à la place Get-MgContext et appelle Connect-MgGraph -Identity -NoWelcome à la demande.
Démarrage rapide
L'appel minimal viable ne nécessite que l'expéditeur, le destinataire, un objet et le corps Markdown :
Cela produit un e-mail RealmJoin entièrement brandé avec l'en-tête et le pied de page par défaut, la prise en charge des modes clair/sombre, et le bloc locataire/version dans le pied de page.
Paramètres
Requis
EmailFrom
string
Nom principal d'utilisateur ou ID d'objet de la boîte aux lettres de l'expéditeur. Utilisé comme /users/{id}/sendMail. Doit être une boîte aux lettres d'utilisateur ou partagée — un groupe Microsoft 365 n'est pas un objet utilisateur et l'envoi échoue.
EmailTo
string
Adresse du destinataire. Chaîne unique — plusieurs adresses sont transmises sous forme de liste séparée par des virgules, voir ci-dessous. Les adresses de groupe Microsoft 365 sont acceptées mais déconseillées — la remise aux membres n'est pas garantie et les échecs ne sont pas visibles pour le runbook.
Objet
string
Ligne d'objet. Injectée également dans le HTML <title> élément.
MarkdownContent
string
Corps du rapport en Markdown. Voir Prise en charge de Markdown pour la syntaxe prise en charge.
Optionnel — contenu
Pièces jointes
string[]
@()
Chemins de fichiers locaux à joindre. Les fichiers manquants sont consignés et ignorés, les fichiers illisibles génèrent un avertissement mais n'interrompent pas l'envoi. Le type MIME est déduit de l'extension du fichier.
saveToSentItems
bool
$true
Si $true le message envoyé est conservé dans le Éléments envoyés. Définissez-le sur $false pour le reporting à fort volume afin d'éviter de remplir la boîte aux lettres.
TenantDisplayName
string
—
Affiché dans la boîte d'informations du locataire intégrée à la fin de la zone de contenu.
ReportVersion
string
—
Affiché dans la boîte d'informations du locataire (utilisez des chaînes de version sémantique, des numéros de build ou un nom de runbook + date).
Optionnel — Branding
Image d'en-tête
string
fournis Assets/Header.png
Chemin de fichier local vers un PNG/JPG/GIF qui remplace le graphique d'en-tête par défaut. Le runbook doit d'abord résoudre toute URL/blob en fichier local (par exemple via Get-AzStorageBlobContent). Les remplacements manquants/illisibles retombent sur le défaut fourni et déclenchent un avertissement.
Image de pied de page
string
fournis Assets/Footer.png
Même traitement que Image d'en-tête. Le pied de page est rendu comme une seule image cliquable — tout texte de branding, logo ou URL doit être intégré dans le PNG.
FooterLink
string
https://www.realmjoin.com
URL utilisée comme href et title de l'ancre qui enveloppe l'image du pied de page.
NoHeader
interrupteur
désactivé
Supprime entièrement le graphique d'en-tête. S'il est combiné avec Image d'en-tête , un avertissement est émis et le remplacement est ignoré.
NoFooter
interrupteur
désactivé
Supprime entièrement le graphique de pied de page et son lien. S'il est combiné avec Image de pied de page ou un FooterLink , un avertissement est émis et ces valeurs sont ignorées.
AccentColor
string
#f8842c
Nouveauté en 0.8.9. Couleur hexadécimale à 6 chiffres pour les lignes d'en-tête des tableaux, les boutons d'action et les bordures d'accentuation des boîtes d'information. Une valeur vide ou mal formée déclenche un avertissement et retombe sur la valeur par défaut.
TextColor
string
#011e33
Nouveauté en 0.8.9. Couleur hexadécimale à 6 chiffres pour le texte du corps, les titres, les éléments de liste et le code. Même comportement de repli que AccentColor.
Dimensions d'image recommandées : PNG 750 × 200 px. Cela correspond à la largeur du conteneur d'e-mail et aux valeurs par défaut fournies. Des rapports d'aspect très différents peuvent paraître déformés sur des affichages étroits. Chaque graphique doit rester bien en dessous de 3 Mo — Graph limite la taille totale de la sendMail requête à 4 Mo et un avertissement est émis si l'une ou l'autre image dépasse 3 Mo.
Couleurs : sans AccentColor/TextColor le HTML généré est identique au bit près aux versions précédentes du module — les valeurs par défaut sont l'orange et le bleu marine RealmJoin. Les couleurs d'état (vert/rouge/ambre) et les gris neutres ne sont volontairement pas paramétrables car ils véhiculent un sens. Vérifiez les couleurs personnalisées en modes clair et sombre : la carte de contenu reste blanche en mode sombre, donc une couleur de texte trop claire devient illisible.
Optionnel — garde-fou de taille des pièces jointes
Nouveauté en 0.8.9. Graph rejette toute la sendMail requête une fois que le message dépasse ~4 Mo. Plutôt que d'échouer le rapport, la fonction peut retomber sur un ensemble de pièces jointes plus petit. Cette logique était auparavant dupliquée sous forme d'assistant de runbook en ligne Send-RjRbGuardedReportEmail et fait désormais partie de la fonction elle-même.
FallbackAttachments
string[]
—
Ensemble de pièces jointes plus petit utilisé lorsque l'ensemble habituel dépasse MaxAttachmentBytes , ou lorsque l'envoi avec l'ensemble habituel échoue pour tous les destinataires. Sans ce paramètre, il n'existe pas de solution de repli et un envoi échoué déclenche immédiatement une exception.
FallbackMarkdownContent
string
valeur de MarkdownContent
Corps utilisé lorsque l'ensemble de secours est envoyé — utilisez-le pour expliquer quels fichiers ont été omis et comment les obtenir.
MaxAttachmentBytes
long
2,5 Mo
Budget de taille brute pour l'ensemble habituel de pièces jointes. Reste nettement en dessous de la limite Graph d'environ 4 Mo après encodage base64 (+33 %), corps HTML et images de branding en ligne. Évalué uniquement lorsque FallbackAttachments est fourni.
Le garde-fou s'exécute en deux étapes :
Avant l'envoi — si l'ensemble habituel dépasse le budget, l'ensemble de secours est envoyé directement et un message indique les deux tailles.
Après un envoi échoué — si l'envoi avec l'ensemble habituel échoue pour tous destinataires, une nouvelle tentative avec l'ensemble de secours est effectuée avant que la fonction ne lève une exception.
Optionnel — transport
UseNativeGraphRequest
interrupteur
désactivé
Envoie via Invoke-MgGraphRequest (nécessite Microsoft.Graph le module et une session Connect-MgGraph à la place de Invoke-RjRbRestMethodGraph. Utilisez ceci lorsque le runbook est construit autour du SDK natif plutôt que du wrapper RealmJoin.
Exemples d'utilisation
Plusieurs destinataires
EmailTo accepte une seule chaîne contenant une ou plusieurs adresses séparées par des virgules. Chaque adresse est nettoyée, les entrées vides sont supprimées, et un e-mail individuel est envoyé par destinataire — les destinataires ne se voient pas les uns les autres.
Avec pièces jointes et métadonnées du locataire
Les fichiers joints sont répertoriés dans une boîte « Fichiers joints » au bas du corps de l'e-mail, en plus d'être ajoutés comme pièces jointes réelles au message.
Branding personnalisé de l'en-tête/pied de page
Apportez votre propre branding en téléchargeant d'abord les ressources vers un chemin local, puis passez les chemins résultants. La fonction ne récupère pas elle-même les URL.
Si $headerPath est manquant ou illisible, l'appel réussit quand même — le défaut RealmJoin fourni est utilisé et un avertissement est consigné.
Couleurs de modèle personnalisées
Adaptez l'e-mail à la charte graphique du client. Les deux paramètres sont indépendants — ne remplacer que la couleur d'accentuation conserve la couleur de texte par défaut :
Une valeur invalide (par exemple blue ou #05c) ne fait pas échouer l'envoi : un avertissement nomme le paramètre et la couleur par défaut est utilisée.
Grands rapports avec un ensemble de pièces jointes de secours
Générez un CSV et un classeur Excel, mais retombez sur le classeur seul lorsque le duo dépasse le budget de taille :
Les runbooks en cours de migration depuis l'assistant en ligne Send-RjRbGuardedReportEmail peuvent supprimer cette fonction et renommer l'appel en Send-RjRbReportEmail — les noms de paramètres (Pièces jointes, FallbackAttachments, FallbackMarkdownContent, MaxAttachmentBytes) n'ont pas changé.
Contenu brut (pas d'en-tête/pied de page)
Pour des notifications de type alerte qui ne doivent pas ressembler à un e-mail marketing :
Utilisation du SDK natif Microsoft.Graph
Si le runbook est déjà authentifié via Connect-MgGraph (identité managée) et que vous préférez ne pas mélanger avec le wrapper RealmJoin :
Lecture du corps du rapport depuis un fichier
Pour les rapports plus volumineux, générez le Markdown dans un fichier .md et lisez-le :
Boutons d'action (appel à l'action)
Rendez un ou plusieurs boutons brandés en ajoutant {button} à un lien Markdown. Les boutons placés sur la même ligne sont regroupés en une seule rangée :
Chaque bouton est un lien hypertexte normal stylisé comme CTA — sûr dans tous les clients, avec des coins arrondis dans les clients modernes et des coins carrés dans Outlook Classic.
Prise en charge de Markdown
La fonction est fournie avec un convertisseur Markdown → HTML léger intégré. Aucun module Markdown externe n'est requis. Syntaxe prise en charge :
# … ###### titres
Les six niveaux. L'espace après # est facultatif. h1 reçoit un soulignement ; l'espacement est ajusté pour Outlook.
**gras**, *italique*, ~~barré~~
Uniquement en ligne (ne doit pas s'étendre sur plusieurs lignes).
`code en ligne`
Rendu comme <code> avec un fond gris clair.
blocs de code délimités lang ...
Le tag de langue est conservé comme class="language-…". Accepte également les délimitations mal formées à un seul backtick.
[text](url) liens
S'ouvre dans un nouvel onglet avec noopener noreferrer.
[label](url){button} boutons de lien
Rendu comme un bouton d'appel à l'action orange brandé plutôt qu'un simple lien. Plusieurs {button} liens sur la même ligne s'affichent côte à côte sur une seule rangée (largeur répartie également). Les coins arrondis apparaissent dans les clients modernes (New Outlook, OWA, mobile) ; Outlook Classic (moteur Word) affiche des coins carrés.
 images
Insérées comme <img> (pas de magie de pièce jointe en ligne — l'URL doit être accessible par le client de messagerie).
- élément / 1. élément listes
Les listes imbriquées sont prises en charge via une indentation de 2 espaces par niveau. Le mélange d’éléments ordonnés et non ordonnés clôt la liste précédente.
Éléments de liste sur plusieurs lignes
Une ligne indentée et non vide directement sous un <li> est repliée dans le même élément avec un <br> saut de ligne souple — inutile de conserver chaque élément sur une seule ligne.
- [ ] / - [x] listes de tâches
Rendu comme ☐ / ☑ Glyphes Unicode (verts lorsqu’ils sont cochés). <input type="checkbox"> est volontairement évité car Outlook Classic supprime les contrôles de formulaire. La majuscule [X] compte également comme cochée.
> bloc de citation
Rendu avec une bordure gauche colorée et un fond ombré.
> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]
Avertissements de type GitHub. La première ligne du bloc de citation est le marqueur (seul), les lignes restantes >préfixées par - constituent le corps. Chaque type reçoit sa propre couleur d’accent, son glyphe et sa barre de titre.
---, ***, ___
Règle horizontale.
|col|col| tableaux
Tableaux standard à barres verticales avec :---, :---:, ---: des spécificateurs d’alignement. Ligne d’en-tête + séparateur requis.
\\ échappement
\*, | etc. sont pris en compte afin que des caractères Markdown littéraux puissent être émis.
Les éléments non pris en charge incluent les notes de bas de page, les listes de définitions et le passage direct de HTML — limitez-vous au Markdown du tableau ci-dessus.
Comportement et gestion des erreurs
Analyse des destinataires
EmailTo est séparé par des virgules, chaque entrée est tronquée et les entrées vides sont supprimées. Si la liste résultante est vide, la fonction lève Aucun destinataire e-mail valide trouvé dans le paramètre EmailTo. avant qu’un appel à Microsoft Graph ne soit effectué.
Échecs par destinataire
Chaque destinataire est envoyé indépendamment. La fonction suit les succès et les échecs :
Si au moins un envoi réussit mais que d’autres échouent, un avertissement est émis listant les adresses en échec ; la fonction se termine normalement.
Si tous envois échouent, la fonction lève
Échec de l’envoi de l’e-mail à tous les destinataires : …afin que le runbook échoue de manière explicite.
Échecs des pièces jointes
Fichiers manquants (le chemin n’existe pas) — journalisés de manière détaillée, ignorés silencieusement.
Fichiers existants mais illisibles (verrouillés, permission refusée) — avertissement émis, ignorés, le reste de l’appel se poursuit.
La zone « Fichiers joints » en bas de l’e-mail répertorie uniquement les pièces jointes qui ont été lues avec succès.
Échecs de remplacement des images
Les deux Image d'en-tête et Image de pied de page reviennent aux valeurs par défaut intégrées en cas d’erreur (fichier manquant, erreur d’E/S ou fichier qui n’est pas une image valide). Un avertissement décrit l’échec et indique quelle valeur par défaut a été utilisée.
Depuis la version 0.8.9, le format de l’image est déterminé à partir de la signature de fichier (octets magiques) plutôt qu’à partir de l’extension de fichier. Un fichier nommé .png mais contenant en réalité une page d’erreur HTML — issue fréquente lorsqu’un téléchargement renvoie silencieusement un document d’erreur — est désormais rejeté avec un avertissement au lieu de produire une pièce jointe inline cassée. À l’inverse, un PNG valide enregistré sous une extension trompeuse est accepté et typé correctement.
Couleurs invalides
AccentColor et TextColor sont validées selon ^#[0-9A-Fa-f]{6}$. Une valeur qui ne correspond pas déclenche un avertissement nommant le paramètre et l’envoi se poursuit avec la couleur par défaut. Les couleurs ne sont jamais une raison pour qu’un rapport échoue.
Limite de taille totale
Graph limite sendMail les requêtes à environ 4 Mo au total (corps HTML + toutes les pièces jointes, encodées en base64). La fonction émet un avertissement lorsque l’une des images de marque dépasse 3 Mo.
Lorsque FallbackAttachments est fourni, le contrôle de taille des pièces jointes décrit dans la section des paramètres ci-dessus gère automatiquement les charges utiles trop volumineuses. Sans jeu de secours, une requête trop volumineuse échoue lors de l’appel à Microsoft Graph ; envisagez :
Fournir un
FallbackAttachmentsjeu (par exemple le classeur Excel sans les fichiers CSV bruts).Téléverser plutôt les données volumineuses vers le canal Storage Account — voir Paramètres de rapport du runbook.
Lier des pièces jointes hébergées à l’extérieur plutôt que de les intégrer.
Compresser les données tabulaires (
Compress-Archive) avant de les joindre.
Intégration avec les paramètres de rapport du runbook
Les runbooks de reporting n’encodent pas en dur l’adresse de l’expéditeur ni l’image de marque : ils déclarent des paramètres masqués que le portail RealmJoin préremplit à partir du JSON central de personnalisation. Les paramètres disponibles sont documentés dans Paramètres de rapport du runbook.
Le rattachement se fait dans le param() bloc via Use-RJInterface -Type Setting, et les paramètres sont marqués "Hide": true dans le .INPUTS RunbookCustomization bloc afin de ne pas encombrer le formulaire du portail :
Voir Get-RjRbBrandingMailParams pour les règles de téléchargement, de validation et de nettoyage.
Sorties
La fonction ne renvoie rien en cas de réussite. Toute la progression est écrite via Write-RjRbLog -Verbose (visible lorsque le runbook est exécuté avec -Verbose ou $VerbosePreference = 'Continue'). Les avertissements sont forcés via $WarningPreference = 'Continue' quelle que soit la surcharge côté appelant, de sorte qu’ils apparaissent de manière fiable dans le flux de tâches Azure Automation.
Aides exportées associées
Les blocs de construction derrière Send-RjRbReportEmail sont désormais eux aussi exportés depuis le module, de sorte que les runbooks puissent composer ou prévisualiser le HTML sans l’envoyer :
Transforme les RJReport.Branding.* paramètres du tenant en paramètres prêts à être splattés : télécharge et valide les images, transmet les couleurs et le lien de pied de page.
ConvertFrom-RjRbMarkdownToHtml
Convertisseur Markdown → HTML autonome (le même moteur léger utilisé en interne, y compris la {button} syntaxe). Accepte -AccentColor/-TextColor.
Get-RjRbReportEmailBody
Assemble le corps HTML complet avec habillage de marque (en-tête/pied de page, boîte d’informations sur le tenant, liste des pièces jointes) à partir d’HTML ou de Markdown — utile pour rendre et inspecter l’e-mail avant l’envoi. Accepte -AccentColor/-TextColor.
Resolve-RjRbImageSource
Résout le chemin d’une image d’en-tête/pied de page vers sa source CID inline. Valide à partir de la signature de fichier et lève une erreur pour tout ce qui n’est pas un PNG, un JPEG ou un GIF.
À l’exception de Get-RjRbBrandingMailParams, ceux-ci sont principalement destinés à des scénarios avancés/de test ; le chemin normal consiste à appeler Send-RjRbReportEmail directement.
Voir aussi
Get-RjRbBrandingMailParams — résolution des paramètres de marque du tenant au sein d’un runbook.
Paramètres de rapport du runbook — configuration centrale de la boîte aux lettres de l’expéditeur, des informations du service desk, de l’image de marque et du canal de livraison Storage Account.
Microsoft Graph: Envoyer un e-mail — API sous-jacente.
Mis à jour
Ce contenu vous a-t-il été utile ?