Publish-RjRbFilesToStorageContainer

Téléversez des fichiers locaux vers un conteneur Azure Storage depuis des runbooks Azure Automation et renvoyez des liens de téléchargement SAS à durée limitée.

Aperçu

Publish-RjRbFilesToStorageContainer est l'assistant standard pour livrer des fichiers de rapport (CSV, XLSX, ZIP, …) depuis des runbooks de reporting RealmJoin via Azure Blob Storage. Il charge un ou plusieurs fichiers locaux vers un conteneur cible et renvoie pour chaque blob un lien de téléchargement SAS à durée limitée, adapté à l'inclusion dans des e-mails de rapport, des messages Teams ou des sorties de runbook.

Caractéristiques principales:

• Aucun Az.Storage dépendance — les opérations blob sont effectuées directement contre l'API REST Azure Storage (création du conteneur, chargement, génération du SAS Token). Cela élimine le conflit d'assemblage bien connu entre Az.Storage et ExchangeOnlineManagement qui se manifeste dans les runbooks de reporting mixtes.
• Connexion automatique — si aucun Az contexte n'est actif, la fonction appelle de manière transparente Connect-RjRbAzAccount. Un -SubscriptionId commutateur optionnel change le contexte avant toute opération de stockage.
• Conteneur créé automatiquement — si le conteneur cible n'existe pas encore, il est créé à la volée ; un conteneur existant (HTTP 409) est traité comme un succès.
• Chargements basés sur HttpClient — utilise System.Net.Http.HttpClient directement, car l'Azure Automation Invoke-RestMethod intercepteur supprime les en-têtes personnalisés requis (x-ms-blob-type) avec les corps binaires.
• Liens SAS en lecture seule — chaque URL renvoyée est signée avec la clé du Storage Account, limitée à un seul blob, HTTPS uniquement, et valable pendant LinkExpiryDays jours (6 par défaut).

Les paramètres centraux de stockage (groupe de ressources, nom du compte, jours d'expiration, préfixe du nom du blob) consommés par un runbook typique résident dans le JSON de personnalisation RealmJoin et sont documentés dans Paramètres de rapport de runbook — remise via Storage Account. Ce document se concentre sur l'appel de la fonction depuis un runbook.

Prérequis

Azure Storage Account

Un Azure Storage Account existant (general-purpose v2 recommandé) est requis. Le conteneur cible n'a pas besoin d'exister à l'avance — il est créé automatiquement à la première utilisation.

Azure RBAC sur le Storage Account

L'identité managée du compte Automation (ou le Service Principal utilisé par le runbook) a besoin des autorisations suivantes sur le Storage Account ou son groupe de ressources :

Action	Nécessaire pour
Microsoft.Storage/storageAccounts/read	Lecture du Storage Account
Microsoft.Storage/storageAccounts/listKeys/action	Récupération de la clé du compte utilisée pour la signature SharedKey et la génération du SAS

Le rôle intégré Storage Account Contributor couvre les deux. Storage Blob Data Contributor seul est renverrait suffisant, car la fonction signe les requêtes avec la clé du compte plutôt qu'en utilisant des opérations blob prises en charge par AAD.

Connectivité du module

La fonction nécessite le Az.Accounts module dans l'environnement du runbook (Get-AzContext, Set-AzContext, Connect-AzAccount, Invoke-AzRestMethod). Déclarez-le explicitement dans le runbook consommateur :

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.8.6" }
#Requires -Modules @{ModuleName = "Az.Accounts"; ModuleVersion = "5.3.4" }

Si Az.Accounts n'est pas disponible à l'exécution, la fonction échoue rapidement avec un message d'erreur clair — elle vérifie la présence de Get-AzContext en amont et lève "Publish-RjRbFilesToStorageContainer nécessite le module 'Az.Accounts'. Ajoutez #Requires -Modules @{ModuleName = 'Az.Accounts'; ModuleVersion = '5.3.4'} au runbook appelant." avant qu'un appel Azure ne soit effectué.

Pourquoi n'est-il pas Az.Accounts déclaré comme RequiredModules entrée dans RealmJoin.RunbookHelper.psd1?

Az.Accounts est intentionnellement répertorié uniquement sous ExternalModuleDependencies (informatif) et renverrait sous RequiredModules (imposé au moment de l' Import-Module ) :

• Ne payer que ce que l'on utilise. De nombreux runbooks utilisent uniquement des assistants basés sur Graph (p. ex. Send-RjRbReportEmail sans -UseNativeGraphRequest, ou Invoke-RjRbRestMethodGraph) et ne touchent jamais une cmdlet Az.*. Faire monter Az.Accounts à RequiredModules forcerait chaque runbook consommateur à embarquer le module même lorsque rien dans son chemin d'exécution n'en a besoin — ce qui augmente de manière mesurable le temps de démarrage à froid dans Azure Automation.
• Éviter les querelles de versions. Une RequiredModules contrainte déclenche la résolution automatique au moment de l'importation et peut entraîner l'inclusion d'une Az.Accounts version qui entre en conflit avec ce que le runbook lui-même verrouille (les sous-modules Az.* sont notoirement sensibles aux versions). Laisser le runbook déclarer ses propres #Requires -Modules laisse le choix de version à l'appelant.
• Autorité par runbook. Dans Azure Automation, l'endroit canonique pour déclarer les dépendances de modules est au niveau du runbook via #Requires, et non au niveau du module helper. Le module helper expose la dépendance de manière informative (via ExternalModuleDependencies dans le manifeste) et via la vérification d'exécution ci-dessus, afin qu'une mauvaise configuration échoue bruyamment avec un message exploitable plutôt que de masquer silencieusement un conflit de versions.

Az.Storage est renverrait est requise et ne doit pas être importée dans le même runbook afin d'éviter le conflit d'assemblage mentionné ci-dessus.

Démarrage rapide

L'appel minimal viable nécessite le ou les chemins de fichier locaux, le nom du conteneur, le groupe de ressources et le nom du Storage Account :

$csvPath = Join-Path $env:TEMP 'devices.csv'
$exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

$results = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $csvPath `
    -ContainerName      'reports' `
    -ResourceGroupName  'rg-reports' `
    -StorageAccountName 'stcontosoreports'

$results | Format-Table BlobName, EndTime, SASLink

Cela charge devices.csv sur le dans le conteneur dans stcontosoreports et renvoie un objet avec le nom du blob, l'horodatage d'expiration du SAS et une URL de téléchargement prête à partager, valable pendant les 6 jours par défaut.

Paramètres

Requis

Paramètre	Type	Description
FilePaths	string[]	Un ou plusieurs chemins de fichiers locaux à charger. Chaque chemin doit pointer vers un fichier existant (Test-Path -PathType Leaf); la fonction lève une erreur en amont si une entrée manque.
ContainerName	string	Conteneur blob cible. Créé automatiquement s'il n'existe pas. Doit respecter les règles de nommage des conteneurs Azure (minuscules, 3–63 caractères, alphanumériques + tiret). Le nom du conteneur est une par runbook décision et est défini dans le runbook, pas dans les paramètres centraux.
ResourceGroupName	string	Groupe de ressources qui contient le Storage Account. Généralement alimenté par le paramètre central RJReport.StorageAccount.ResourceGroup.
StorageAccountName	string	Nom du Azure Storage Account. Généralement alimenté par le paramètre central RJReport.StorageAccount.StorageAccountName.

Optionnel

Paramètre	Type	Défaut	Description
SubscriptionId	string	contexte actuel	abonnement Azure qui héberge le Storage Account. Si fourni, Set-AzContext -Subscription est appelé avant toute opération de stockage. À omettre pour utiliser le Az contexte.
LinkExpiryDays	int	6	Validité du lien SAS en jours. Validé à [1, 3650]. Le même horodatage d'expiration est appliqué à tous les blobs dans un seul appel. Généralement alimenté par le paramètre central RJReport.StorageAccount.LinkExpiryDays.
AddBlobNamePrefix	bool	$false	Lorsque $true, les noms des blobs sont préfixés par yyyyMMdd-HHmmss- (horodatage de Get-Date au moment du chargement) afin d'éviter les écrasements lors d'exécutions répétées. Le nom de fichier d'origine est conservé comme suffixe.

Remarque : Le mappage entre ces paramètres et le JSON de personnalisation RealmJoin central (y compris les valeurs par défaut recommandées) est documenté dans Paramètres de rapport de runbook — remise via Storage Account.

Exemples d'utilisation

Modèle de runbook recommandé

C'est le modèle canonique utilisé par les runbooks de reporting. La configuration du stockage est extraite de la personnalisation RealmJoin centrale via Use-RJInterface -Type Setting, le conteneur est codé en dur par runbook, et une configuration manquante provoque l'arrêt du runbook avec un message exploitable :

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.8.6" }
#Requires -Modules @{ModuleName = "Az.Accounts"; ModuleVersion = "5.3.4" }

param(
    [string] $ContainerName = "my-runbook-output",

    [ValidateScript( { Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.ResourceGroup" } )]
    [string] $ResourceGroupName,

    [ValidateScript( { Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.StorageAccountName" } )]
    [string] $StorageAccountName,

    [ValidateScript( { Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.LinkExpiryDays" } )]
    [ValidateRange(1, 3650)]
    [int] $LinkExpiryDays = 6
)

Connect-RjRbAzAccount

if ((-not $ResourceGroupName) -or (-not $StorageAccountName)) {
    "## Pour exporter vers un Storage Account, veuillez utiliser la personnalisation RJ Runbooks"
    "## ( https://portal.realmjoin.com/settings/runbooks-customizations ) pour configurer :"
    "##   - RJReport.StorageAccount.ResourceGroup"
    "##   - RJReport.StorageAccount.StorageAccountName"
    throw "Configuration du Storage Account manquante."
}

# … produire le fichier d'export …
$exportPath = "myReport.csv"

$uploadResults = Publish-RjRbFilesToStorageContainer `
    -FilePaths          @($exportPath) `
    -ContainerName      $ContainerName `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -LinkExpiryDays     $LinkExpiryDays `
    -AddBlobNamePrefix  $true

$uploadResult = $uploadResults[0]
"## Export créé."
"## Expiration du lien : $($uploadResult.EndTime)"
$uploadResult.SASLink | Out-String

Quelques conventions à respecter lors de l'adoption de ce modèle :

• (ResourceGroup, StorageAccountName, LinkExpiryDays) sont exposés comme paramètres de runbook alimentés via Use-RJInterface -Type Setting, mais généralement masqués dans la personnalisation du runbook ("Hide": true) afin que les utilisateurs finaux ne les voient jamais.
• Le nom du conteneur est codé en dur par runbook (souvent via une param par défaut) afin que les stratégies de cycle de vie et les contrôles d'accès puissent être ajustés par type d'export — il ne s'agit intentionnellement pas renverrait d'un paramètre central.
• AddBlobNamePrefix $true est la valeur sûre par défaut pour les exports périodiques qui produisent à chaque exécution un nom de fichier fixe.
• La fonction est appelée à l'intérieur du try { … } catch { throw $_ } finally { Disconnect-AzAccount … } principal du runbook afin que les échecs partiels remontent au job Automation et que le contexte Az soit libéré même en cas de succès.

Plusieurs fichiers dans un seul appel

FilePaths accepte un tableau ; chaque fichier est chargé séquentiellement et un objet résultat est renvoyé pour chaque blob chargé.

$results = Publish-RjRbFilesToStorageContainer `
    -FilePaths          @($csvPath, $xlsxPath) `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName

foreach ($r in $results) {
    "Téléchargé $($r.BlobName) — téléchargeable jusqu'à $($r.EndTime) : $($r.SASLink)"
}

Durée de vie personnalisée du lien et abonnement explicite

Publish-RjRbFilesToStorageContainer `
    -FilePaths          $exportPaths `
    -ContainerName      'quarterly-reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -SubscriptionId     '00000000-0000-0000-0000-000000000000' `
    -LinkExpiryDays     30

Utile lorsque le runbook couvre plusieurs abonnements, ou lorsque les destinataires en aval ont besoin d'une fenêtre plus longue que la valeur par défaut de 6 jours.

Combinaison avec Send-RjRbReportEmail

Un modèle courant consiste à charger les données volumineuses vers le stockage blob et à intégrer le lien SAS dans un e-mail de rapport, en maintenant l'e-mail bien en dessous de la limite Graph de 4 Mo sendMail :

$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $csvPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

$linkLine = "[Download {0}]({1}) (valable jusqu'au {2:yyyy-MM-dd HH:mm} UTC)" -f `
    $uploaded[0].BlobName, $uploaded[0].SASLink, $uploaded[0].EndTime.ToUniversalTime()

$reportMd = @"
# Inventaire des appareils

La liste complète des appareils est disponible en téléchargement :

$linkLine
"@

Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         '[e-mail]' `
    -Subject         "Inventaire des appareils — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd

Voir Send-RjRbReportEmail pour la partie e-mail de ce modèle.

Comportement et gestion des erreurs

Validation préalable des fichiers

Avant tout appel Azure, la fonction parcourt FilePaths et lève Le fichier '<path>' est introuvable. pour la première entrée manquante. Cela évite des chargements partiels lorsque l'appelant laisse une faute de frappe.

Résolution du contexte Azure

Get-AzContext est vérifié en premier. S'il n'y a pas de contexte ou si le contexte n'a pas de compte (par ex. une exécution de runbook fraîche), la fonction appelle Connect-RjRbAzAccount pour authentifier l'identité managée. Si -SubscriptionId est fourni, Set-AzContext -Subscription est invoqué ensuite.

Création du conteneur

Le conteneur est créé avec une requête PUT …?restype=container :

• HTTP 201 — conteneur créé.
• HTTP 409 — le conteneur existe déjà ; traité comme un succès.
• Tout autre statut — la fonction lève Échec de la création du conteneur (<status>) : <body>.

Échecs de chargement

Chaque fichier est chargé via HttpClient.SendAsync. Un statut non réussi termine l'appel avec Échec du chargement du blob (<status>) : <body>, y compris l'erreur brute renvoyée par Azure Storage. Les fichiers précédents déjà chargés dans le même appel restent dans le Storage Account — l'appelant peut vouloir envelopper l'appel dans un try/catch et effectuer un nettoyage si les chargements partiels ne sont pas acceptables.

Échecs de récupération des clés

Invoke-AzRestMethod est utilisé pour appeler le point de terminaison ARM listKeys . Si le statut de réponse est autre chose que 200, la fonction lève Échec de récupération des clés du Storage Account pour '<account>' dans le groupe de ressources '<rg>'. Statut : <status>. Les causes les plus courantes sont :

• Manque de Microsoft.Storage/storageAccounts/listKeys/action sur l'identité managée.
• Contexte d'abonnement incorrect (à combiner avec -SubscriptionId).
• Faute de frappe dans StorageAccountName ou ResourceGroupName.
• Les paramètres centraux RJReport.StorageAccount.ResourceGroup / RJReport.StorageAccount.StorageAccountName non configurés — voir Paramètres de rapport du runbook.

Caractéristiques du SAS Token

Les jetons générés utilisent :

• sv=2023-11-03 (version signée)
• sr=b (limité au blob)
• sp=r (lecture seule)
• spr=https (HTTPS uniquement)
• st défini à 5 minutes dans le passé (tolérance au décalage d'horloge) et se à LinkExpiryDays à partir du moment de l'appel.

Les jetons sont signés avec la clé du Storage Account. Toute personne disposant du lien peut télécharger le blob jusqu'à expiration — considérez l'URL SAS renvoyée comme un secret.

Sorties

Chaque chargement réussi produit un PSCustomObject avec ces propriétés :

Propriété	Type	Description
BlobName	string	Le nom final du blob dans le conteneur, y compris le préfixe d'horodatage si AddBlobNamePrefix est $true.
EndTime	datetime	Expiration SAS en heure locale (également encodée dans l'URL en UTC).
SASLink	string	URL de téléchargement HTTPS complète avec SAS Token intégré.

Les résultats sont renvoyés dans le même ordre que FilePaths. Même lors du chargement d'un seul fichier, la valeur de retour est un tableau — indexez-le ($results[0]) ou itérez avec foreach plutôt que de le traiter comme un scalaire.

Voir aussi

• Paramètres de rapport de runbook — remise via Storage Account — configuration centrale du Storage Account, de l'expiration du lien et du préfixe du nom de blob utilisés par les runbooks de reporting.
• Send-RjRbReportEmail — assistant complémentaire pour livrer les rapports par e-mail ; souvent combiné avec cette fonction pour garder la charge utile de l'e-mail petite.
• Documentation Microsoft : Autoriser avec Shared Key — schéma de signature utilisé par l'assistant.
• Documentation Microsoft : Créer un SAS de service — format du SAS Token renvoyé dans SASLink.