Get-RjRbBrandingMailParams

Resolver as definições do Tenant RJReport.Branding em parâmetros prontos a usar para Send-RjRbReportEmail.

Visão geral

Get-RjRbBrandingMailParams faz a ponte entre as definições centrais de configurações de identidade visual do e-mail e Send-RjRbReportEmail: as configurações usam URLs, a função de envio espera caminhos de ficheiros locais. Esta função descarrega as imagens configuradas, valida-as e devolve uma hashtable que pode ser passada diretamente no call de envio.

Disponível a partir de RealmJoin.RunbookHelper 0.8.9. Versões anteriores do runbook incluíam esta lógica como um auxiliar embutido com o mesmo nome; essas cópias podem ser eliminadas assim que o Automation Account executar 0.8.9 ou posterior.

Regras de design:

• Nunca falha o relatório. Qualquer problema — configuração vazia, URL não HTTPS, download falhado, ficheiro demasiado grande, imagem inválida, cor malformada — resulta num aviso e na omissão dessa única chave. O e-mail é então renderizado com o padrão correspondente do RealmJoin.
• Devolve apenas o que foi resolvido. A hashtable devolvida contém apenas as chaves que tiveram sucesso, por isso passá-la diretamente nunca substitui um padrão por um valor vazio.
• Um download por execução. Chame-a uma vez e reutilize o resultado para todos os e-mails que o runbook enviar — incluindo dentro de loops que notificam muitos utilizadores.

Início rápido

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

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

Sem identidade visual configurada, $brandingMailParams é uma hashtable vazia e o call comporta-se exatamente como se o parâmetro tivesse sido omitido.

Parâmetros

Todos os parâmetros são opcionais — a função foi concebida para ser chamada com o que quer que o Tenant tenha configurado.

Parâmetro	Tipo	Padrão	Descrição
HeaderImageUrl	string	—	URL HTTPS pública da imagem de cabeçalho (RJReport.Branding.HeaderImageUrl).
FooterImageUrl	string	—	URL HTTPS pública da imagem de rodapé (RJReport.Branding.FooterImageUrl).
FooterLink	string	—	URL de destino da imagem de rodapé (RJReport.Branding.FooterLink). Transmitido tal como está, não validado.
AccentColor	string	—	Cor de destaque (RJReport.Branding.AccentColor). Transmitido tal como está; o formato hexadecimal é validado por Send-RjRbReportEmail.
TextColor	string	—	Cor do texto (RJReport.Branding.TextColor). Mesmo tratamento que AccentColor.
TimeoutSec	int	30	Tempo limite de download por imagem.
MaxImageBytes	long	200KB	Tamanho máximo de imagem aceite. As imagens de branding partilham o limite de ~4 MB do sendMail com os anexos do relatório. sendMail com os anexos do relatório.

Saídas

Uma [hashtable] contendo apenas as chaves resolvidas com sucesso:

Chave	Valor
HeaderImage	Caminho local da imagem de cabeçalho descarregada
FooterImage	Caminho local da imagem de rodapé descarregada
FooterLink	Link de rodapé sem espaços
AccentColor	Cor de destaque sem espaços
TextColor	Cor do texto sem espaços

Cada chave corresponde a um parâmetro de Send-RjRbReportEmail, o que torna o splatting seguro.

Validação

Cada imagem passa pelas seguintes verificações antes de ser aceita:

Verificação	Motivo da rejeição
Esquema da URL	Apenas https é aceite — os bytes da imagem acabam no e-mail da empresa, por isso HTTP simples é recusado.
Download	Respostas não-2xx, timeouts e erros de rede são apanhados; o corpo da resposta de um erro de armazenamento não é tratado silenciosamente como uma imagem.
Tamanho	Ficheiros vazios e ficheiros maiores do que MaxImageBytes (padrão 200 KB).
Assinatura do ficheiro	Os primeiros bytes têm de identificar um PNG, JPEG ou GIF. Uma página de erro HTML guardada com um nome .png é recusada aqui.

Ao ficheiro temporário é atribuída a extensão correspondente ao seu detetado formato, porque Send-RjRbReportEmail deriva daí o tipo de conteúdo do anexo — uma URL sem extensão de ficheiro, ou com uma enganadora, funciona portanto corretamente.

Notas de comportamento

A alojar as imagens

A URL só precisa de ser alcançável a partir da sandbox do Azure Automation. Dois padrões comuns:

• blob público ou CDN — o mais simples, mas as imagens podem ser lidas por qualquer pessoa.
• contentor privado com um SAS Token na URL — o contentor permanece privado e apenas os detentores da ligação o podem ler. Lembre-se de que a expiração do SAS termina silenciosamente a identidade visual: depois de expirar, os relatórios continuam a chegar com os padrões do RealmJoin e o motivo só é visível como um aviso no registo do trabalho.

Limpeza de ficheiros temporários

As imagens descarregadas são gravadas no diretório temporário da sandbox. A sandbox é descartada após a execução, por isso a limpeza é opcional — mas os runbooks com uma região de limpeza explícita devem removê-las após o último 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
    }
}

Diagnóstico de uma identidade visual que não aparece

Quando um relatório chega com os gráficos predefinidos embora a identidade visual esteja configurada, o registo do trabalho identifica a etapa que falhou:

Entrada de registo	Causa
Sem Identidade visual: qualquer entrada	As definições nunca chegaram ao runbook — verifique o JSON de personalização e se o portal conhece esta versão do runbook.
Apenas URLs HTTPS são suportadas	A URL usa http://.
Um erro de armazenamento como PublicAccessNotPermitted	O pedido chegou sem autenticação — o SAS Token está em falta na URL, muitas vezes porque foi truncado ao ser copiado.
ultrapassa o limite de … para imagens inline de e-mail	O ficheiro é maior do que MaxImageBytes.
não é uma imagem PNG, JPEG ou GIF	O download devolveu algo diferente de uma imagem, normalmente uma página de erro.

Ver também

• Send-RjRbReportEmail — o consumidor dos parâmetros devolvidos.
• Definições de relatórios do runbook — a configurar as RJReport.Branding.* definições como administrador.