Send-RjRbReportEmail
Envoyer des e-mails de rapport HTML à l'image de marque depuis des runbooks Azure Automation via Microsoft Graph en utilisant du contenu Markdown.
Vue d’ensemble
Send-RjRbReportEmail est l'assistant standard pour l'envoi des e-mails de rapport depuis les runbooks de reporting RealmJoin. Il prend du contenu Markdown, le convertit en e-mail HTML réactif à l'image de RealmJoin, joint des fichiers facultatifs et des éléments graphiques de marque 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-RjReportEmailenSend-RjRbReportEmailpour assurer la 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 doivent 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 avec thème, compatible avec 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 e-mail à plusieurs destinataires. Il s'agit d'une conception axée sur la confidentialité / CCI par défaut.
En-tête et pied de page de marque intégrés en ligne — les ressources PNG intégrées 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 entièrement supprimées.
Connexion automatique — si aucune session Graph n'est active, la fonction appelle de manière transparente
Connect-RjRbGraph(ouConnect-MgGraph -Identitylorsque-UseNativeGraphRequestest défini).Résilient — les lectures de pièces jointes échouées, les remplacements d'image manquants ou les échecs sendMail par destinataire sont signalés mais n'interrompent pas tout le lot à moins que tous les destinataires n'échouent.
Les paramètres d'e-mail centralisés (adresse de l'expéditeur, informations du service desk) sont documentés dans Paramètres du 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 aux lettres partagée dédiée telle que realmjoin-report@contoso.com) est requise comme De adresse. 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 Mail.Send (avec un périmètre défini via RBAC pour les applications si vous souhaitez restreindre l'identité à une seule boîte aux lettres).
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 cible 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. Lorsque -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 nécessite uniquement 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 tenant/version dans le pied de page.
Paramètres
Obligatoire
EmailFrom
chaîne
Nom principal d'utilisateur ou identifiant d'objet de la boîte aux lettres de l'expéditeur. Utilisé comme /users/{id}/sendMail.
EmailTo
chaîne
Adresse du destinataire. Chaîne unique — plusieurs adresses sont transmises sous forme de liste séparée par des virgules, voir ci-dessous.
Subject
chaîne
Ligne d'objet. Injectée également dans le HTML <title> élément.
MarkdownContent
chaîne
Corps du rapport en Markdown. Voir Prise en charge du Markdown pour la syntaxe prise en charge.
Facultatif — Contenu
Pièces jointes
chaîne[]
@()
Chemins de fichiers locaux à joindre. Les fichiers manquants sont journalisé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 la Éléments envoyés. Définissez sur $false pour les rapports à fort volume afin d'éviter de saturer la boîte aux lettres.
TenantDisplayName
chaîne
—
Affiché dans la zone d'informations du tenant intégrée à la fin de la zone de contenu.
ReportVersion
chaîne
—
Affiché dans la zone d'informations du tenant (utilisez des chaînes de version sémantiques, des numéros de build ou un nom de runbook + date).
Facultatif — Branding
HeaderImage
chaîne
intégré 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 ex. via Get-AzStorageBlobContent). Les remplacements manquants/illisibles reviennent à la valeur intégrée par défaut et génèrent un avertissement.
FooterImage
chaîne
intégré Assets/Footer.png
Même traitement que HeaderImage. Le pied de page est rendu comme une seule image cliquable — tout texte de marque, logo ou URL doit être intégré au PNG.
FooterLink
chaîne
https://www.realmjoin.com
URL utilisée comme href et title du lien enveloppant l'image du pied de page.
NoHeader
commutateur
désactivé
Supprime entièrement le graphique d'en-tête. S'il est combiné avec HeaderImage, un avertissement est émis et la substitution est ignorée.
NoFooter
commutateur
désactivé
Supprime entièrement le graphique de pied de page et son lien. S'il est combiné avec FooterImage ou un FooterLinkpersonnalisé, un avertissement est émis et ces valeurs sont ignorées.
Dimensions d'image recommandées : PNG de 750 × 200 px. Cela correspond à la largeur du conteneur de l'e-mail et aux valeurs intégrées par défaut. Des rapports d'aspect sensiblement différents peuvent paraître déformés sur les affichages étroits. Chaque image doit rester bien en dessous de 3 Mo — Graph limite le total sendMail de la requête à 4 Mo et un avertissement est émis si l'une ou l'autre image dépasse 3 Mo.
Facultatif — Transport
UseNativeGraphRequest
commutateur
désactivé
Envoie via Invoke-MgGraphRequest (nécessite Microsoft.Graph module et une Connect-MgGraph session) au lieu de Invoke-RjRbRestMethodGraph. Utilisez ceci lorsque le runbook est conçu autour du SDK natif plutôt que du wrapper RealmJoin.
Exemples d'utilisation
Destinataires multiples
EmailTo accepte une seule chaîne contenant une ou plusieurs adresses séparées par des virgules. Chaque adresse est nettoyée des espaces superflus, les entrées vides sont supprimées, et un e-mail individuel est envoyé à chaque destinataire — les destinataires ne se voient pas entre eux.
Avec pièces jointes et métadonnées du tenant
Les fichiers joints sont répertoriés dans une zone « Attached Files » au bas du corps de l'e-mail, en plus d'être ajoutés comme véritables pièces jointes au message.
Personnalisation de la marque 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 transmettez les chemins obtenus. 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 — la valeur par défaut intégrée RealmJoin est utilisée et un avertissement est consigné.
Contenu simple (sans en-tête/pied de page)
Pour des notifications de type alerte qui ne doivent pas ressembler à un e-mail marketing :
Utilisation du SDK Microsoft.Graph natif
Si le runbook est déjà authentifié via Connect-MgGraph (identité managée) et que vous préférez ne pas mêler le wrapper RealmJoin :
Lecture du corps du rapport depuis un fichier
Pour les rapports plus volumineux, générez le Markdown dans un .md fichier et lisez-le :
Boutons d'action (call-to-action)
Rendre un ou plusieurs boutons de marque en ajoutant {button} à un lien Markdown. Les boutons placés sur la même ligne sont regroupés sur une seule ligne :
Chaque bouton est un lien hypertexte normal stylisé comme un 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 du Markdown
La fonction est livrée 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é~~
En ligne uniquement (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-…". Tolère également les délimiteurs mal formés à un seul backtick.
[text](url) liens
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 ligne (largeur répartie également). Les coins arrondis s'affichent dans les clients modernes (New Outlook, OWA, mobile) ; Outlook Classic (moteur Word) affiche des coins carrés.
 images
Insérées comme <img> (aucune 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 grâce à 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 multi-lignes
Une ligne indentée non vide directement sous un <li> est repliée dans le même élément avec un <br> retour à la ligne souple — inutile de garder chaque élément sur une seule ligne.
- [ ] / - [x] listes de tâches
Rendu comme ☐ / ☑ Glyphes Unicode (verts lorsque cochés). <input type="checkbox"> est volontairement évité car Outlook Classic supprime les contrôles de formulaire. La majuscule [X] compte aussi comme coché.
> citation
Rendu avec une bordure gauche colorée et un fond ombré.
> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]
Avertissements de style GitHub. La première ligne de la citation est le marqueur (seul), les lignes restantes >précédées de - constituent le corps. Chaque type reçoit sa propre couleur d'accent, son propre glyphe et sa propre barre de titre.
---, ***, ___
Règle horizontale.
|col|col| tableaux
Tableaux pipe standard avec :---, :---:, ---: des spécificateurs d'alignement. Une ligne d'en-tête + un séparateur sont requis.
\\ échappement
\*, | etc. sont respectés afin que les 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éfinition et le passage HTML — limitez le Markdown au tableau ci-dessus.
Comportement et gestion des erreurs
Analyse des destinataires
EmailTo est découpé par virgules, chaque entrée est nettoyée des espaces superflus et les entrées vides sont supprimées. Si la liste résultante est vide, la fonction lève Aucun destinataire d'e-mail valide trouvé dans le paramètre EmailTo. avant qu'un appel 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 l'envoi réussit mais d'autres échouent, un avertissement est émis listant les adresses en échec ; la fonction se termine normalement.
Si tous les envois échouent, la fonction lève une exception
É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) — consignés en détail, 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 « Attached Files » en bas de l'e-mail répertorie uniquement les pièces jointes qui ont été lues avec succès.
Échecs de remplacement d'image
Les deux HeaderImage et FooterImage reviennent aux valeurs par défaut intégrées en cas de toute erreur (fichier manquant, extension non prise en charge, erreur d'E/S). Un avertissement décrit l'échec et indique quelle valeur par défaut a été utilisée.
Limite de taille totale
Plafonds de Graph sendMail 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 ou l'autre image de marque dépasse 3 Mo. Si la charge utile totale dépasse encore 4 Mo, l'appel à Graph échouera ; envisagez :
de téléverser les données volumineuses vers le canal Storage Account à la place — voir Paramètres du rapport du runbook.
de lier des pièces jointes hébergées à l'extérieur plutôt que de les intégrer.
de 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 résolvent généralement l'adresse de l'expéditeur à partir du JSON central de personnalisation RealmJoin plutôt que de la coder en dur. Les paramètres pertinents sont documentés dans Paramètres du rapport du runbook. Un modèle de résolution typique dans un runbook ressemble à ceci :
Sorties
La fonction ne renvoie rien en cas de succès. 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, afin qu'ils apparaissent de façon fiable dans le flux de travaux Azure Automation.
Aides exportées associées
Les blocs de construction derrière Send-RjRbReportEmail sont désormais également exportés depuis le module, afin que les runbooks puissent composer ou prévisualiser le HTML sans l'envoyer :
ConvertFrom-RjRbMarkdownToHtml
Convertisseur Markdown → HTML autonome (le même moteur léger utilisé en interne, y compris la {button} syntaxe).
Get-RjRbReportEmailBody
Assemble le corps HTML complet avec l'image de marque (en-tête/pied de page, zone d'informations sur le locataire, liste des pièces jointes) à partir de HTML ou de Markdown — utile pour générer et inspecter l'e-mail avant l'envoi.
Resolve-RjRbImageSource
Résout un chemin d'image d'en-tête/pied de page vers sa source CID intégrée, avec repli sur la valeur par défaut intégrée en cas d'erreur.
Ils sont principalement destinés à des scénarios avancés/de test ; le chemin normal consiste à appeler Send-RjRbReportEmail directement.
Voir aussi
Paramètres du rapport du runbook — configuration centrale de la boîte aux lettres de l'expéditeur, des informations du service desk 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 ?