Publish-RjRbFilesToStorageContainer

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

Aperçu

Publish-RjRbFilesToStorageContainer est l’utilitaire standard pour distribuer des fichiers de rapport (CSV, XLSX, ZIP, …) depuis les runbooks de reporting RealmJoin via Azure Blob Storage. Il téléverse un ou plusieurs fichiers locaux vers un conteneur cible et retourne pour chaque blob un lien de téléchargement SAS à durée limitée, adapté à une inclusion dans des e-mails de rapport, des messages Teams ou la sortie des runbooks.

Caractéristiques principales :

• Non Az.Storage dépendance — les opérations sur les blobs sont effectuées directement via l’API REST Azure Storage (création de conteneur, téléversement, génération de SAS Token). Cela élimine le conflit d’assembly 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 automatiquement Connect-RjRbAzAccount. Un paramètre facultatif -SubscriptionId bascule 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 considéré comme une réussite.
• Téléversements basés sur HttpClient — utilise System.Net.Http.HttpClient directement, car l’intercepteur d’Azure Automation Invoke-RestMethod supprime les en-têtes personnalisés requis (x-ms-blob-type) pour les corps binaires.
• Liens SAS en lecture seule — chaque URL retourné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 de stockage centraux (groupe de ressources, nom du compte, jours d’expiration, préfixe du nom de blob) utilisés par un runbook type se trouvent dans le JSON de personnalisation RealmJoin et sont documentés dans Paramètres de rapport du runbook — livraison vers 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 au préalable — il est créé automatiquement à la première utilisation.

Azure RBAC sur le Storage Account

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

Action	Requis 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 de SAS Token

Le rôle intégré Storage Account Contributor couvre les deux. Storage Blob Data Contributor à lui seul est pas suffisant, car la fonction signe les requêtes avec la clé du compte plutôt qu’en utilisant des opérations sur les blobs adossées à AAD.

Connectivité du module

La fonction requiert 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 immédiatement avec un message d’erreur clair — elle vérifie Get-AzContext dès le départ 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-ce pas Az.Accounts déclaré comme une RequiredModules entrée dans RealmJoin.RunbookHelper.psd1?

Az.Accounts est intentionnellement listé uniquement sous ExternalModuleDependencies (informatif) et pas dans RequiredModules (appliqué à Import-Module l’exécution) :

• Paiement uniquement pour ce que vous utilisez. De nombreux runbooks n’utilisent que des utilitaires basés sur Graph (par ex. Send-RjRbReportEmail sans -UseNativeGraphRequest, ou Invoke-RjRbRestMethodGraph) et ne touchent jamais le moindre cmdlet Az.*. Promouvoir Az.Accounts en 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 sensiblement le temps de démarrage à froid dans Azure Automation.
• Évitez les conflits de versions. Une contrainte stricte RequiredModules déclenche une résolution automatique au moment de l’import et peut entraîner l’installation d’une version spécifique Az.Accounts qui entre en conflit avec celle que le runbook fixe lui-même (les sous-modules Az.* sont notoirement sensibles aux versions). Permettre au runbook de déclarer ses propres #Requires -Modules laisse le choix de la version à l’appelant.
• Autorité par runbook. Dans Azure Automation, l’emplacement canonique pour déclarer les exigences de modules se situe au niveau du runbook via #Requires, et non au niveau du module utilitaire. Le module utilitaire expose la dépendance à titre informatif (via ExternalModuleDependencies dans le manifeste) ainsi que via la vérification d’exécution ci-dessus, de sorte qu’une mauvaise configuration échoue bruyamment avec un message exploitable plutôt que de masquer silencieusement un conflit de versions.

Az.Storage est pas est requis et ne doit pas être importé dans le même runbook afin d’éviter le conflit d’assembly mentionné ci-dessus.

Démarrage rapide

L’appel minimal viable requiert le ou les chemins de fichiers 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 téléverse devices.csv vers le reports conteneur in stcontosoreports et retourne un objet avec le nom du blob, l’horodatage d’expiration du SAS et une URL de téléchargement prête à partager, valide pendant les 6 jours par défaut.

Paramètres

Obligatoire

Paramètre	Type	Description
FilePaths	chaîne[]	Un ou plusieurs chemins de fichiers locaux à téléverser. Chaque chemin doit pointer vers un fichier existant (Test-Path -PathType Leaf); la fonction lève une erreur immédiatement si une entrée est manquante.
ContainerName	chaîne	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 un choix par runbook et est défini dans le runbook, pas dans les paramètres centraux.
ResourceGroupName	chaîne	Groupe de ressources qui contient le Storage Account. Généralement relié au paramètre central RJReport.AzureStorage.ResourceGroup.
StorageAccountName	chaîne	Nom de l’Azure Storage Account. Généralement relié au paramètre central RJReport.AzureStorage.StorageAccountName.

Facultatif

Paramètre	Type	Par défaut	Description
SubscriptionId	chaîne	contexte actuel	abonnement Azure qui héberge le Storage Account. Si fourni, Set-AzContext -Subscription est appelé avant toute opération de stockage. Omettez-le 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 d’un seul appel. Généralement relié au paramètre central RJReport.AzureStorage.LinkExpiryDays.
AddBlobNamePrefix	bool	$false	Lorsque $true, les noms de blob sont préfixés par yyyyMMdd-HHmmss- (horodatage de Get-Date au moment du téléversement) 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 mapping entre ces paramètres et le JSON de personnalisation central RealmJoin (y compris les valeurs par défaut recommandées) est documenté dans Paramètres de rapport du runbook — livraison vers 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 centrale RealmJoin 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.AzureStorage.ResourceGroup" } )]
    [string] $ResourceGroupName,

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

    [ValidateScript( { Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; Use-RJInterface -Type Setting -Attribute "RJReport.AzureStorage.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.AzureStorage.ResourceGroup"
    "##   - RJReport.AzureStorage.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 méritent d’être conservées lors de l’adoption de ce modèle :

• Les trois paramètres centraux (ResourceGroup, StorageAccountName, LinkExpiryDays) sont exposés comme paramètres du runbook relié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 un 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’exportation — il est intentionnellement pas un paramètre central.
• AddBlobNamePrefix $true est la valeur par défaut sûre pour les exports périodiques qui produisent un nom de fichier fixe à chaque exécution.
• La fonction est appelée dans le principal try { … } catch { throw $_ } finally { Disconnect-AzAccount … } bloc afin que les échecs partiels remontent jusqu’au job Automation et que le contexte Az soit libéré même en cas de réussite.

Plusieurs fichiers en un seul appel

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

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

foreach ($r in $results) {
    "Téléversé $($r.BlobName) — téléchargement possible jusqu’au $($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.

Association avec Send-RjRbReportEmail

Un modèle courant consiste à téléverser des données volumineuses dans le stockage de blobs et à intégrer le lien SAS dans un e-mail de rapport, en gardant l’e-mail bien en dessous de la limite Graph de 4 Mo sendMail limite :

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

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

$reportMd = @"
# Device Inventory

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 qu’un appel Azure ne soit effectué, la fonction parcourt FilePaths et lève Le fichier '<path>' est introuvable. pour la première entrée manquante. Cela empêche les téléversements partiels lorsque l’appelant fait une faute de frappe.

Résolution du contexte Azure

Get-AzContext est vérifié en premier. S’il n’y a aucun contexte ou si le contexte n’a pas de Account (par ex. une exécution fraîche du runbook), 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 PUT …?restype=container requête :

• HTTP 201 — conteneur créé.
• HTTP 409 — le conteneur existe déjà ; considéré comme une réussite.
• Tout autre statut — la fonction lève Container creation failed (<status>): <body>.

Échecs de téléversement

Chaque fichier est téléversé via HttpClient.SendAsync. Un statut d’échec met fin à l’appel avec Blob upload failed (<status>): <body>, y compris l’erreur brute renvoyée par Azure Storage. Les fichiers précédents déjà téléversés lors du même appel restent sur le Storage Account — l’appelant peut vouloir encapsuler l’appel dans un try/catch et exécuter un nettoyage si les téléversements partiels sont inacceptables.

Échecs de récupération de clé

Invoke-AzRestMethod est utilisé pour appeler le point de terminaison ARM listKeys . Si le statut de réponse est différent de 200, la fonction lève Failed to retrieve storage account keys for '<account>' in resource group '<rg>'. Status: <status>. Les causes les plus courantes sont :

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

Caractéristiques du jeton SAS

Les jetons générés utilisent :

• sv=2023-11-03 (signed version)
• sr=b (blob-scoped)
• sp=r (read-only)
• spr=https (HTTPS-only)
• st défini 5 minutes dans le passé (tolérance à la dérive de l’horloge) et se en LinkExpiryDays à partir de l’heure 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’à l’expiration — traitez l’URL SAS retournée comme un secret.

Sorties

Chaque téléversement réussi produit un PSCustomObject avec les propriétés suivantes :

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

Les résultats sont renvoyés dans le même ordre que FilePaths. Même lors du téléversement 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 du runbook — livraison vers Storage Account — configuration centrale du Storage Account, de l’expiration des liens et du préfixe des noms de blob utilisée par les runbooks de reporting.
• Send-RjRbReportEmail — utilitaire compagnon pour distribuer les rapports par e-mail ; souvent combiné avec cette fonction pour garder la charge utile de l’e-mail petite.
• Microsoft Docs: Autoriser avec Shared Key — schéma de signature utilisé par l’utilitaire.
• Microsoft Docs: Créer un SAS de service — format de SAS Token renvoyé dans SASLink.