> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md). # Send-RjRbReportEmail ## Visão geral `Send-RjRbReportEmail` é o auxiliar padrão para enviar emails de relatório a partir de runbooks de relatórios do RealmJoin. Recebe conteúdo Markdown, converte-o num email HTML responsivo com a marca RealmJoin, anexa ficheiros opcionais e gráficos de marca embutidos (cabeçalho/rodapé) e envia o resultado através do Microsoft Graph `sendMail` ponto de extremidade. > **Renomeado nesta versão.** A função foi renomeada de `Send-RjReportEmail` para `Send-RjRbReportEmail` para consistência na nomenclatura com o restante do módulo (`*-RjRb*`). O nome antigo `Send-RjReportEmail` é exportado como um alias compatível com versões anteriores, para que os runbooks existentes continuem a funcionar sem alterações — mas os novos runbooks devem chamar `Send-RjRbReportEmail`. Principais características: * **Markdown entra, HTML sai** — os runbooks compõem o corpo do relatório em Markdown; a função renderiza-o em HTML com tema, que funciona no Outlook Classic, Novo Outlook, Outlook Web, clientes móveis e modo escuro. * **Um email por destinatário** — quando são fornecidos vários destinatários, a função envia uma mensagem individual para cada endereço em vez de um único email com vários destinatários. Este é um design de privacidade/BCC por defeito. * **Cabeçalho e rodapé com marca embutidos** — os recursos PNG incluídos são enviados como anexos CID e referenciados pelo HTML incorporado. Ambos podem ser substituídos ou suprimidos por completo. * **Ligação automática** — se não houver uma sessão do Graph ativa, a função chama de forma transparente `Connect-RjRbGraph` (ou `Connect-MgGraph -Identity` quando `-UseNativeGraphRequest` estiver definido). * **Resiliente** — falhas na leitura de anexos, substituições de imagem em falta ou falhas do sendMail por destinatário são comunicadas, mas não interrompem todo o lote, a menos que *todos os* destinatários falhem. As definições centralizadas do email (endereço do remetente, informações da mesa de serviço) estão documentadas em [Definições do Relatório do Runbook](/pt/automacao/runbooks/runbook-report-settings.md) — este documento concentra-se em chamar a função a partir de um runbook. ## Pré-requisitos ### Caixa de correio do remetente É necessária uma caixa de correio licenciada do Microsoft 365 (normalmente uma caixa de correio partilhada dedicada, como `realmjoin-report@contoso.com`) é necessária como o endereço `From` do remetente. A identidade gerida da Automation Account deve ter permissão para enviar em nome dessa caixa de correio através da permissão de aplicação Graph `Mail.Send` (com âmbito definido via RBAC for Applications se quiser restringir a identidade a uma única caixa de correio). ### Permissões do Graph | Cenário | Permissão necessária | | ------------------------------------------- | ----------------------------------------------------------- | | Predefinição (`Invoke-RjRbRestMethodGraph`) | `Mail.Send` (Application) na caixa de correio do remetente | | Com `-UseNativeGraphRequest` | Igual — a chamada continua a atingir `/users/{id}/sendMail` | ### Conectividade do módulo Por defeito, a função usa `Invoke-RjRbRestMethodGraph` deste módulo. Se nenhuma ligação estiver ativa, liga-se automaticamente através de `Connect-RjRbGraph`. Quando `-UseNativeGraphRequest` estiver definido, a função verifica antes `Get-MgContext` e chama `Connect-MgGraph -Identity -NoWelcome` quando necessário. ## Início rápido A chamada mínima viável requer apenas o remetente, o destinatário, um assunto e o corpo Markdown: ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Weekly Report" ` -MarkdownContent @" # Relatório Semanal Olá Alice, aqui estão os números desta semana: - Novos dispositivos inscritos: **42** - Conformidade de licenças: **98%** "@ ``` Isto produz um email RealmJoin totalmente com a marca, com o cabeçalho e rodapé predefinidos, suporte para modo claro/escuro e o bloco de tenant/versão no rodapé. ## Parâmetros ### Obrigatório | Parâmetro | Tipo | Descrição | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `EmailFrom` | `string` | Nome principal de utilizador ou ID de objeto da caixa de correio do remetente. Usado como `/users/{id}/sendMail`. | | `EmailTo` | `string` | Endereço do destinatário. **String única** — vários endereços são passados como uma lista separada por vírgulas; veja abaixo. | | `Subject` | `string` | Linha de assunto. Também é inserida no HTML `` elemento. | | `MarkdownContent` | `string` | Corpo do relatório em Markdown. Veja [Suporte a Markdown](#markdown-support) para a sintaxe suportada. | ### Opcional — Conteúdo | Parâmetro | Tipo | Predefinição | Descrição | | ------------------- | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Anexos` | `string[]` | `@()` | Caminhos de ficheiros locais a anexar. Ficheiros em falta são registados e ignorados, ficheiros ilegíveis emitem um aviso mas não interrompem o envio. O tipo MIME é derivado da extensão do ficheiro. | | `saveToSentItems` | `bool` | `$true` | Se `$true` a mensagem enviada for mantida na *Itens Enviados*. Defina como `$false` para relatórios de grande volume, para evitar encher a caixa de correio. | | `TenantDisplayName` | `string` | — | Mostrado na caixa de informações do tenant incorporada no final da área de conteúdo. | | `ReportVersion` | `string` | — | Mostrado na caixa de informações do tenant (use strings de versão semântica, números de compilação ou um nome do runbook + data). | ### Opcional — Marca | Parâmetro | Tipo | Predefinição | Descrição | | ------------- | ------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HeaderImage` | `string` | incluído `Assets/Header.png` | Caminho de ficheiro local para um PNG/JPG/GIF que substitui o gráfico padrão do cabeçalho. **O runbook deve resolver previamente qualquer URL/blob para um ficheiro local** (por exemplo, através de `Get-AzStorageBlobContent`). Substituições em falta/ilegíveis recuam para o padrão incluído e emitem um aviso. | | `FooterImage` | `string` | incluído `Assets/Footer.png` | Tratamento igual ao de `HeaderImage`. O rodapé é renderizado como uma única imagem clicável — qualquer texto de marca, logótipo ou URL tem de estar incorporado no PNG. | | `FooterLink` | `string` | `https://www.realmjoin.com` | URL usada como `href` e `title` do âncora que envolve a imagem do rodapé. | | `NoHeader` | `interruptor` | desligado | Suprime completamente o gráfico do cabeçalho. Se combinado com `HeaderImage`HeaderImage | | `NoFooter` | `interruptor` | desligado | Suprime completamente o gráfico do rodapé e o respetivo link. Se combinado com `FooterImage` ou uma personalização `FooterLink`, é emitido um aviso e esses valores são ignorados. | **Dimensões recomendadas das imagens:** PNG de 750 × 200 px. Isto corresponde à largura do contentor do email e aos padrões incluídos. Proporções significativamente diferentes podem parecer distorcidas em ecrãs estreitos. Cada gráfico deve ficar bem abaixo de 3 MB — o Graph limita o tamanho total do pedido a 4 MB e é emitido um aviso se qualquer imagem exceder 3 MB. `sendMail` o pedido a 4 MB e é emitido um aviso se qualquer imagem exceder 3 MB. ### Opcional — Transporte | Parâmetro | Tipo | Predefinição | Descrição | | ----------------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `UseNativeGraphRequest` | `interruptor` | desligado | Envia através de `Invoke-MgGraphRequest` (requer `Microsoft.Graph` módulo e uma `Connect-MgGraph` sessão) em vez de `Invoke-RjRbRestMethodGraph`. Use isto quando o runbook é construído em torno do SDK nativo e não do wrapper do RealmJoin. | ## Exemplos de utilização ### Vários destinatários `EmailTo` aceita uma única string contendo um ou mais endereços separados por vírgulas. Cada endereço é aparado, as entradas vazias são removidas e **é enviado um email individual por destinatário** — os destinatários não se veem entre si. ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com, bob@contoso.com, team-lead@contoso.com" ` -Subject "Monthly Inventory" ` -MarkdownContent $reportMd ``` ### Com anexos e metadados do tenant ```powershell $csvPath = Join-Path $env:TEMP 'devices.csv' $exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8 Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "it-reports@contoso.com" ` -Subject "Device Inventory — $(Get-Date -Format 'yyyy-MM-dd')" ` -MarkdownContent $reportMd ` -Attachments @($csvPath, "$env:TEMP\\summary.xlsx") ` -TenantDisplayName "Contoso Ltd" ` -ReportVersion "DeviceInventory v1.4.2" ``` Os ficheiros anexados são listados numa caixa "Ficheiros anexados" na parte inferior do corpo do email, para além de serem adicionados como anexos reais à mensagem. ### Marca personalizada do cabeçalho/rodapé Traga a sua própria marca ao descarregar primeiro os recursos para um caminho local e, em seguida, passe os caminhos resultantes. A função não obtém URLs por si própria. ```powershell # Resolver recursos de marca a partir do Azure Blob Storage para a pasta temporária do runbook $headerPath = Join-Path $env:TEMP 'contoso-header.png' $footerPath = Join-Path $env:TEMP 'contoso-footer.png' Get-AzStorageBlobContent -Container 'branding' -Blob 'header.png' -Destination $headerPath -Force | Out-Null Get-AzStorageBlobContent -Container 'branding' -Blob 'footer.png' -Destination $footerPath -Force | Out-Null Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Relatório com Marca" ` -MarkdownContent $reportMd ` -HeaderImage $headerPath ` -FooterImage $footerPath ` -FooterLink "https://intranet.contoso.com/it-reports" ``` Se `$headerPath` está em falta ou ilegível, a chamada continua a ser bem-sucedida — o padrão incluído do RealmJoin é usado e é registado um aviso. ### Conteúdo simples (sem cabeçalho/rodapé) Para notificações ao estilo de alerta que não devem parecer um email de marketing: ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "oncall@contoso.com" ` -Subject "[ALERTA] Limite de licenças excedido" ` -MarkdownContent "## Limite de licenças excedido`n`nConsulte o painel para obter detalhes." ` -NoHeader ` -NoFooter ``` ### Usando o SDK nativo Microsoft.Graph Se o runbook já estiver autenticado através de `Connect-MgGraph` (identidade gerida) e preferir não misturar o wrapper do RealmJoin: ```powershell Connect-MgGraph -Identity -NoWelcome Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Envio nativo do Graph" ` -MarkdownContent $reportMd ` -UseNativeGraphRequest ``` ### Ler o corpo do relatório a partir de um ficheiro Para relatórios maiores, gere o Markdown para um `.md` ficheiro e leia-o: ```powershell $reportMd = Get-Content -Path .\generated-report.md -Raw Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Weekly Report" ` -MarkdownContent $reportMd ``` ### Botões de ação (call-to-action) Renderize um ou mais botões com marca ao adicionar `{button}` a uma ligação Markdown. Botões colocados na mesma linha são agrupados numa única linha: ```powershell $reportMd = @" # Pedido de acesso Um novo pedido de acesso a um dispositivo aguarda a sua decisão. [Approve](https://portal.contoso.com/approve/123){button} [Reject](https://portal.contoso.com/reject/123){button} "@ Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "approver@contoso.com" ` -Subject "Ação necessária: pedido de acesso ao dispositivo" ` -MarkdownContent $reportMd ``` Cada botão é uma hiperligação normal estilizada como CTA — segura em todos os clientes, com cantos arredondados em clientes modernos e cantos quadrados no Outlook Classic. ## Suporte a Markdown A função inclui um conversor leve Markdown → HTML integrado. **Não é necessário nenhum módulo Markdown externo.** Sintaxe suportada: | Markdown | Notas | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `# … ######` títulos | Todos os seis níveis. O espaço após `#` é opcional. `h1` recebe um sublinhado; o espaçamento é ajustado para o Outlook. | | `**bold**`, `*italic*`, `~~strike~~` | Apenas inline (não pode abranger várias linhas). | | `` `inline code` `` | Renderizado como `<code>` com um fundo cinzento-claro. | | lang ... blocos de código delimitados | A etiqueta da linguagem é preservada como `class="language-…"`. Também tolera delimitadores malformados de um único acento grave. | | `[text](url)` ligações | Abrir numa nova aba com `noopener noreferrer`. | | `[label](url){button}` botões de ligação | Renderizado como um botão laranja de call-to-action com marca em vez de uma ligação simples. Várias `{button}` ligações na **mesma linha** são renderizadas lado a lado numa única linha (largura dividida igualmente). Os cantos arredondados aparecem em clientes modernos (Novo Outlook, OWA, mobile); o Outlook Classic (motor Word) renderiza cantos quadrados. | | `![alt](url)` imagens | Inseridas como `<img>` (sem magia de anexos em linha — o URL tem de ser acessível pelo cliente de email). | | `- item` / `1. item` listas | Listas aninhadas suportadas através de indentação de 2 espaços por nível. Misturar listas ordenadas e não ordenadas fecha a lista anterior. | | Itens de lista em várias linhas | Uma linha indentada, não vazia, diretamente abaixo de um `<li>` é incorporada no mesmo item com uma `<br>` quebra suave — não há necessidade de manter cada item numa única linha. | | `- [ ]` / `- [x]` listas de tarefas | Renderizado como `☐` / `☑` glifos Unicode (verde quando assinalado). `<input type="checkbox">` é intencionalmente evitado porque o Outlook Classic remove controlos de formulário. Maiúscula `[X]` também conta como assinalado. | | `citação em bloco` | Renderizado com uma borda esquerda colorida e fundo sombreado. | | `> [!NOTE\|TIP\|IMPORTANT\|WARNING\|CAUTION]` | Admoestações ao estilo GitHub. A primeira linha do blockquote é o marcador (sozinho), as restantes linhas com prefixo - formam o corpo. Cada tipo recebe a sua própria cor de destaque, glifo e barra de título. `>`-prefixed lines are the body. Each type gets its own accent colour, glyph and title bar. | | `---`, `***`, `___` | Regra horizontal. | | `\|col\|col\|` tabelas | Tabelas padrão com barras verticais e `:---`, `:---:`, `---:` especificadores de alinhamento. É necessária uma linha de cabeçalho + separador. | | `\\` escapamento | `\*`, `\|` etc. são respeitados para que possam ser emitidos caracteres Markdown literais. | Os itens não suportados incluem notas de rodapé, listas de definição e passagem de HTML — mantenha o Markdown restrito à tabela acima. ## Comportamento e tratamento de erros ### Análise de destinatários `EmailTo` é dividido por vírgulas, cada entrada é aparada e as entradas vazias são removidas. Se a lista resultante estiver vazia, a função lança `Não foram encontrados destinatários de email válidos no parâmetro EmailTo.` antes de ser feita qualquer chamada ao Graph. ### Falhas por destinatário Cada destinatário é enviado independentemente. A função acompanha os êxitos e as falhas: * Se **pelo menos um** o envio tem sucesso, mas os outros falham, é emitido um aviso listando os endereços com falha; a função retorna normalmente. * Se **todos os** falham, a função lança `Falha ao enviar e-mail para todos os destinatários: …` para que o runbook falhe de forma explícita. ### Falhas nos anexos * Ficheiros em falta (o caminho não existe) — registados com detalhe, ignorados silenciosamente. * Ficheiros existentes, mas ilegíveis (bloqueados, permissão negada) — aviso emitido, ignorados, o restante da chamada prossegue. * A caixa "Ficheiros anexados" na parte inferior do e-mail lista apenas os anexos que foram lidos com sucesso. ### Falhas na substituição de imagens Ambos `HeaderImage` e `FooterImage` recaem nos padrões incluídos em caso de qualquer erro (ficheiro em falta, extensão não suportada, erro de IO). Um aviso descreve a falha e identifica qual padrão foi usado. ### Limite de tamanho total Limites do Graph `sendMail` solicitações em cerca de 4 MB no total (corpo HTML + todos os anexos, codificados em base64). A função emite um aviso quando qualquer imagem de marca ultrapassa 3 MB. Se a carga total ainda exceder 4 MB, a própria chamada ao Graph falhará; considere: * Carregar dados grandes para o canal Storage Account em vez disso — veja [Definições do Relatório do Runbook](/pt/automacao/runbooks/runbook-report-settings.md#storage-account-delivery). * Fazer ligação a anexos alojados externamente em vez de os incorporar. * Comprimir dados tabulares (`Compress-Archive`) antes de anexar. ## Integração com as definições de Runbook Report Os runbooks de relatório normalmente resolvem o endereço do remetente a partir do JSON central de personalização do RealmJoin, em vez de o codificar de forma fixa. As definições relevantes estão documentadas em [Definições do Relatório do Runbook](/pt/automacao/runbooks/runbook-report-settings.md). Um padrão típico de resolução num runbook é: ```powershell # Ler definições centralizadas (resolvidas pela estrutura do runbook) $emailFrom = (Get-RjRbDefaultValue -Name 'EmailSender' -Section 'RJReport') if (-not $emailFrom) { throw "Nenhum EmailSender configurado. Consulte https://docs.realmjoin.com/ para instruções de configuração." } Send-RjRbReportEmail ` -EmailFrom $emailFrom ` -EmailTo $RecipientParameter ` -Subject $Subject ` -MarkdownContent $reportMd ` -TenantDisplayName $TenantDisplayName ` -ReportVersion "MyReport v1.0" ``` ## Saídas A função não retorna nada em caso de sucesso. Todo o progresso é escrito via `Write-RjRbLog -Verbose` (visível quando o runbook é executado com `-Verbose` ou `$VerbosePreference = 'Continue'`). Os avisos são forçados através de `$WarningPreference = 'Continue'` independentemente de substituições do lado do chamador, por isso aparecem de forma fiável no fluxo de trabalhos do Azure Automation. ## Helpers Exportados Relacionados Os blocos de construção por trás de `Send-RjRbReportEmail` também são agora exportados do módulo, para que os runbooks possam compor ou pré-visualizar o HTML sem enviar: | Função | Finalidade | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ConvertFrom-RjRbMarkdownToHtml` | Conversor autónomo de Markdown → HTML (o mesmo motor leve usado internamente, incluindo a `{button}` sintaxe). | | `Get-RjRbReportEmailBody` | Compõe o corpo HTML completo com a marca (cabeçalho/rodapé, caixa de informações do Tenant, lista de anexos) a partir de HTML ou Markdown — útil para renderizar e inspecionar o e-mail antes de enviar. | | `Resolve-RjRbImageSource` | Resolve um caminho de imagem do cabeçalho/rodapé para a respetiva origem CID embutida, recaindo no padrão incluído em caso de erro. | Estes destinam-se principalmente a cenários avançados/de teste; o caminho normal é chamar `Send-RjRbReportEmail` diretamente. ## Ver também * [Definições do Relatório do Runbook](/pt/automacao/runbooks/runbook-report-settings.md) — configuração central da caixa de correio do remetente, informações do service desk e do canal de entrega Storage Account. * Microsoft Graph: [Enviar e-mail](https://learn.microsoft.com/en-us/graph/api/user-sendmail) — API subjacente. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md?ask=<question>&goal=<endgoal> ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.