Send-RjRbReportEmail
Envíe correos electrónicos de informes HTML con marca desde runbooks de Azure Automation a través de Microsoft Graph usando contenido Markdown.
Información general
Send-RjRbReportEmail es el asistente estándar para enviar correos electrónicos de informes desde los runbooks de reportes de RealmJoin. Toma contenido Markdown, lo convierte en un correo HTML responsivo con la marca de RealmJoin, adjunta archivos opcionales y gráficos de marca en línea (encabezado/pie de página), y envía el resultado a través de Microsoft Graph sendMail punto de conexión.
Se ha renombrado en esta versión. La función se renombró de
Send-RjReportEmailaSend-RjRbReportEmailpara mantener la coherencia de nomenclatura con el resto del módulo (*-RjRb*). El nombre anteriorSend-RjReportEmailse exporta como un alias compatible con versiones anteriores, de modo que los runbooks existentes sigan funcionando sin cambios — pero los runbooks nuevos deben llamar aSend-RjRbReportEmail.
Características clave:
Markdown de entrada, HTML de salida — los runbooks componen el cuerpo del informe en Markdown; la función lo renderiza como HTML temático que funciona en Outlook Classic, New Outlook, Outlook Web, clientes móviles y en modo oscuro.
Un correo por destinatario — cuando se proporcionan varios destinatarios, la función envía un mensaje individual a cada dirección en lugar de un solo correo para múltiples destinatarios. Este es un diseño de privacidad/BCC por defecto.
Encabezado y pie de página con marca en línea — los recursos PNG incluidos se envían como adjuntos CID y se referencian desde el HTML incrustado. Ambos pueden anularse o deshabilitarse por completo.
Autoconectable — si no hay una sesión de Graph activa, la función llama transparentemente a
Connect-RjRbGraph(oConnect-MgGraph -Identitycuando-UseNativeGraphRequestestá establecido).Resistente — las lecturas de adjuntos fallidas, los reemplazos de imagen faltantes o los fallos de sendMail por destinatario se notifican, pero no abortan todo el lote a menos que todos los destinatarios fallen.
Los ajustes centralizados de correo electrónico (dirección del remitente, información del service desk) están documentados en Configuración de informes del runbook — este documento se centra en llamar a la función desde un runbook.
Requisitos previos
Buzón remitente
Se requiere un buzón con licencia de Microsoft 365 (normalmente un buzón compartido dedicado como realmjoin-report@contoso.com) como dirección From . La identidad administrada de la cuenta de Automation debe tener अनुमति para enviar en nombre de ese buzón mediante el permiso de aplicación Mail.Send (acotado mediante RBAC para aplicaciones si desea restringir la identidad a un solo buzón).
Permisos de Graph
Predeterminado (Invoke-RjRbRestMethodGraph)
Mail.Send (Application) en el buzón remitente
Con -UseNativeGraphRequest
igual — la llamada sigue llegando a /users/{id}/sendMail
Conectividad del módulo
De forma predeterminada, la función usa Invoke-RjRbRestMethodGraph de este módulo. Si no hay una conexión activa, se conecta automáticamente mediante Connect-RjRbGraph. Cuando -UseNativeGraphRequest está establecido, la función en su lugar comprueba Get-MgContext y llama a Connect-MgGraph -Identity -NoWelcome bajo demanda.
Inicio rápido
La llamada mínima viable solo requiere el remitente, el destinatario, un asunto y el cuerpo en Markdown:
Esto produce un correo de RealmJoin completamente personalizado con el encabezado y pie de página predeterminados, compatibilidad con modo claro/oscuro y el bloque de tenant/versión en el pie de página.
Parámetros
Requerido
EmailFrom
string
Nombre principal de usuario o id de objeto del buzón remitente. Se usa como /users/{id}/sendMail.
EmailTo
string
Dirección del destinatario. Cadena única — varias direcciones se pasan como una lista separada por comas; véase más abajo.
Subject
string
Línea de asunto. También se inserta en el HTML <title> del elemento.
MarkdownContent
string
Cuerpo del informe en Markdown. Véase Compatibilidad con Markdown para la sintaxis admitida.
Opcional — Contenido
Adjuntos
string[]
@()
Rutas de archivos locales para adjuntar. Los archivos que faltan se registran y se omiten; los archivos ilegibles generan una advertencia, pero no abortan el envío. El tipo MIME se deriva de la extensión del archivo.
saveToSentItems
bool
$true
Si $true el mensaje enviado se conserva en la carpeta Elementos enviadosdel buzón remitente. Establézcalo en $false para informes de gran volumen y evitar llenar el buzón.
TenantDisplayName
string
—
Se muestra en el cuadro de información del tenant incrustado al final del área de contenido.
ReportVersion
string
—
Se muestra en el cuadro de información del tenant (use cadenas de versión semántica, números de compilación o un nombre de runbook + fecha).
Opcional — Marca
HeaderImage
string
incluidos Assets/Header.png
Ruta local a un PNG/JPG/GIF que reemplaza la imagen de encabezado predeterminada. El runbook debe resolver previamente cualquier URL/blob a un archivo local (por ejemplo, mediante Get-AzStorageBlobContent). Los reemplazos que falten o no se puedan leer recurren al valor predeterminado incluido y generan una advertencia.
FooterImage
string
incluidos Assets/Footer.png
El mismo tratamiento que HeaderImage. El pie de página se representa como una única imagen clicable — cualquier texto de marca, logotipo o URL debe estar incrustado en el PNG.
FooterLink
string
https://www.realmjoin.com
URL usada como href y title del enlace que envuelve la imagen del pie de página.
NoHeader
interruptor
desactivado
Suprime por completo la imagen del encabezado. Si se combina con HeaderImage, se emite una advertencia y se ignora el reemplazo.
NoFooter
interruptor
desactivado
Suprime por completo la imagen del pie de página y su enlace. Si se combina con FooterImage o un FooterLinkpersonalizado, se emite una advertencia y se ignoran esos valores.
Dimensiones de imagen recomendadas: PNG de 750 × 200 px. Esto coincide con el ancho del contenedor del correo y los valores predeterminados incluidos. Las relaciones de aspecto muy diferentes pueden verse distorsionadas en vistas estrechas. Cada gráfico debe mantenerse muy por debajo de 3 MB — Graph limita la solicitud total a 4 MB y se emite una advertencia si cualquiera de las imágenes supera los 3 MB. sendMail solicitud a 4 MB y se emite una advertencia si cualquiera de las imágenes supera los 3 MB.
Opcional — Transporte
UseNativeGraphRequest
interruptor
desactivado
Envía mediante Invoke-MgGraphRequest (requiere Microsoft.Graph módulo y una Connect-MgGraph sesión) en lugar de Invoke-RjRbRestMethodGraph. Úselo cuando el runbook esté construido alrededor del SDK nativo en lugar del envoltorio de RealmJoin.
Ejemplos de uso
Varios destinatarios
EmailTo acepta una sola cadena que contiene una o más direcciones separadas por comas. Cada dirección se recorta, se eliminan las entradas vacías y se envía un correo individual por destinatario — los destinatarios no se ven entre sí.
Con adjuntos y metadatos del tenant
Los archivos adjuntos se enumeran en un cuadro "Archivos adjuntos" en la parte inferior del cuerpo del correo, además de agregarse como adjuntos reales al mensaje.
Marca de encabezado/pie de página personalizada
Traiga su propia marca descargando primero los recursos a una ruta local y luego pase las rutas resultantes. La función no obtiene URL por sí misma.
Si $headerPath falta o no se puede leer, la llamada igualmente tiene éxito — se usa el valor predeterminado de RealmJoin incluido y se registra una advertencia.
Contenido sin formato (sin encabezado/pie de página)
Para notificaciones de estilo alerta que no deben parecer un correo de marketing:
Uso del SDK nativo de Microsoft.Graph
Si el runbook ya está autenticado mediante Connect-MgGraph (identidad administrada) y prefiere no mezclar el envoltorio de RealmJoin:
Lectura del cuerpo del informe desde un archivo
Para informes más grandes, genere el Markdown en un archivo .md y léalo:
Botones de acción (llamada a la acción)
Genere uno o más botones con marca anexando {button} a un enlace de Markdown. Los botones colocados en la misma línea se agrupan en una sola fila:
Cada botón es un hipervínculo normal con estilo de CTA — seguro en todos los clientes, con esquinas redondeadas en clientes modernos y esquinas cuadradas en Outlook Classic.
Compatibilidad con Markdown
La función incluye un conversor ligero de Markdown → HTML integrado. No se requiere ningún módulo externo de Markdown. Sintaxis admitida:
# … ###### encabezados
Todos los seis niveles. El espacio después de # es opcional. h1 recibe un subrayado; el espaciado está ajustado para Outlook.
**negrita**, *cursiva*, ~~tachado~~
Solo en línea (no debe abarcar varias líneas).
`código en línea`
Representado como <code> con un fondo gris claro.
bloques de código delimitados con lang ...
La etiqueta de idioma se conserva como class="language-…". También tolera cercas mal formadas de una sola comilla invertida.
[texto](url) enlaces
Abrir en una pestaña nueva con noopener noreferrer.
[etiqueta](url){button} botones de enlace
Se representa como un botón naranja de llamada a la acción con marca, en lugar de un enlace simple. Varios {button} enlaces en la misma línea se muestran uno al lado del otro en una sola fila (ancho dividido por igual). Las esquinas redondeadas aparecen en clientes modernos (New Outlook, OWA, móviles); Outlook Classic (motor Word) las muestra cuadradas.
 imágenes
Insertadas como <img> (sin magia de adjuntos en línea: la URL debe ser accesible por el cliente de correo).
- elemento / 1. elemento listas
Se admiten listas anidadas mediante una sangría de 2 espacios por nivel. La mezcla de listas ordenadas y desordenadas cierra la lista anterior.
Elementos de lista en varias líneas
Una línea sangrada y no vacía directamente debajo de un <li> se integra en el mismo elemento con un <br> salto suave — no es necesario mantener cada elemento en una sola línea.
- [ ] / - [x] listas de tareas
Representado como ☐ / ☑ Glifos Unicode (en verde cuando están marcados). <input type="checkbox"> se evita intencionadamente porque Outlook Classic elimina los controles de formulario. La X mayúscula [X] también cuenta como marcada.
> cita en bloque
Se representa con un borde izquierdo de color y un fondo sombreado.
> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]
Amonestaciones estilo GitHub. La primera línea de la cita en bloque es el marcador (solo), las líneas restantes >prefijadas con - son el cuerpo. Cada tipo obtiene su propio color de acento, glifo y barra de título.
---, ***, ___
Regla horizontal.
|col|col| tablas
Tablas estándar con barras verticales y :---, :---:, ---: especificadores de alineación. Se requiere la fila de encabezado y el separador.
\\ escape
\*, | etc. se respetan para que puedan emitirse caracteres literales de Markdown.
Los elementos no admitidos incluyen notas al pie, listas de definiciones y paso directo de HTML — mantenga el Markdown dentro de la tabla anterior.
Comportamiento y manejo de errores
Análisis de destinatarios
EmailTo se divide por comas, cada entrada se recorta y se eliminan las entradas vacías. Si la lista resultante está vacía, la función genera No se encontraron destinatarios de correo electrónico válidos en el parámetro EmailTo. antes de realizar cualquier llamada a Graph.
Fallos por destinatario
Cada destinatario se envía de forma independiente. La función registra éxitos y fallos:
Si al menos uno el envío se realiza correctamente, pero otros fallan, se emite una advertencia que enumera las direcciones fallidas; la función devuelve normalmente.
Si todos fallan, la función lanza
No se pudo enviar el correo electrónico a todos los destinatarios: …por lo que el runbook falla de forma explícita.
Fallos en los archivos adjuntos
Archivos faltantes (la ruta no existe) — se registra con detalle y se omite silenciosamente.
Archivos existentes pero no legibles (bloqueados, permiso denegado) — se emite una advertencia, se omiten y el resto de la llamada continúa.
El cuadro "Attached Files" en la parte inferior del correo electrónico enumera solo los archivos adjuntos que se leyeron correctamente.
Fallos en la sustitución de imágenes
Ambos HeaderImage y FooterImage recurren a los valores predeterminados incluidos ante cualquier error (archivo faltante, extensión no compatible, error de E/S). Una advertencia describe el fallo e identifica qué valor predeterminado se usó.
Límite total de tamaño
Límites de Graph sendMail las solicitudes a ~4 MB combinados (cuerpo HTML + todos los archivos adjuntos, codificados en base64). La función emite una advertencia cuando cualquiera de las imágenes de marca supera los 3 MB. Si la carga total sigue superando los 4 MB, la propia llamada de Graph fallará; considere:
Cargar datos grandes en su lugar al canal Storage Account — vea Configuración de informes del runbook.
Enlazar archivos adjuntos alojados externamente en lugar de incrustarlos.
Comprimiendo datos tabulares (
Compress-Archive) antes de adjuntarlos.
Integración con la configuración de informe de Runbook
Los runbooks de informes suelen resolver la dirección del remitente desde el JSON central de personalización de RealmJoin en lugar de codificarla. Los ajustes relevantes están documentados en Configuración de informes del runbook. Un patrón de resolución típico en un runbook tiene este aspecto:
Salidas
La función no devuelve nada si se completa correctamente. Todo el progreso se escribe mediante Write-RjRbLog -Verbose (visible cuando el runbook se ejecuta con -Verbose o $VerbosePreference = 'Continue'). Las advertencias se canalizan obligatoriamente a través de $WarningPreference = 'Continue' independientemente de las anulaciones del lado del llamador, por lo que aparecen de forma fiable en el flujo de trabajos de Azure Automation.
Ayudantes exportados relacionados
Los componentes básicos detrás de Send-RjRbReportEmail también se exportan ahora desde el módulo, por lo que los runbooks pueden componer o previsualizar el HTML sin enviarlo:
ConvertFrom-RjRbMarkdownToHtml
Convertidor independiente de Markdown → HTML (el mismo motor ligero usado internamente, incluida la {button} sintaxis).
Get-RjRbReportEmailBody
Compone el cuerpo HTML completo con marca (encabezado/pie de página, cuadro de información del tenant, lista de adjuntos) a partir de HTML o Markdown — útil para renderizar e inspeccionar el correo antes de enviarlo.
Resolve-RjRbImageSource
Resuelve la ruta de una imagen de encabezado/pie de página a su origen CID en línea, volviendo al valor predeterminado incluido si ocurre un error.
Estos están pensados principalmente para escenarios avanzados/de prueba; la ruta normal es llamar a Send-RjRbReportEmail directamente.
Véase también
Configuración de informes del runbook — configuración central del buzón del remitente, la información del service desk y el canal de entrega de Storage Account.
Microsoft Graph: Enviar correo — API subyacente.
Última actualización
¿Te fue útil?