> 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/fr/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md).

# 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 la remise 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é à être inclus dans les e-mails de rapport, les messages Teams ou les sorties de runbook.

Caractéristiques principales :

* **Aucune `Az.Storage` dépendance** — les opérations blob 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 apparaît dans les runbooks de reporting mixtes.
* **Connexion automatique** — si aucun `module Az` contexte n’est actif, la fonction appelle de manière transparente `Connect-RjRbAzAccount`. Une option facultative `-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`) avec 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 valide 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 de blob) utilisés par un runbook type se trouvent dans le JSON de personnalisation RealmJoin et sont documentés dans [Paramètres du rapport de runbook — livraison du Storage Account](https://docs.realmjoin.com/fr/automatisation/runbooks/runbook-report-settings.md#storage-account-delivery). Ce document se concentre sur l’appel de la fonction depuis un runbook.

## Prérequis

### Azure Storage Account

Un Azure Storage Account existant (généralement de type v2 recommandé) est requis. Le conteneur cible n’a pas besoin d’exister à l’avance — il est créé automatiquement à la première utilisation.

### RBAC Azure 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 :

| 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 |

Attribuez le rôle intégré **Lecture et accès aux données** sur le Storage Account : c’est le plus petit rôle intégré qui couvre les deux. La création de conteneur, le téléversement et la génération de SAS sont autorisés avec la clé du compte et ne nécessitent aucune autre autorisation Azure RBAC. **Storage Account Contributor** fonctionne également, mais permet en plus de gérer et de supprimer le Storage Account. **Storage Blob Data Contributor** à lui seul est *ne* suffisant, car la fonction signe les requêtes avec la clé du compte plutôt que d’utiliser des opérations blob adossées à AAD.

Comme la fonction s’authentifie avec la clé du compte, l’accès par clé partagée doit être autorisé sur le Storage Account (`allowSharedKeyAccess` ne doit pas être `false`). La clé donne accès à toutes les données du Storage Account, il est donc recommandé d’utiliser un Storage Account dédié aux rapports.

### 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 :

```powershell
#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 la présence de `Get-AzContext` à l’avance 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 tout appel Azure.

> **Pourquoi n’est-il pas `Az.Accounts` déclaré comme `RequiredModules` entrée dans `RealmJoin.RunbookHelper.psd1`?**
>
> `Az.Accounts` est intentionnellement listé uniquement sous `ExternalModuleDependencies` (informatif) et *ne* sous `RequiredModules` (appliqué au `Import-Module` moment) :
>
> * **Payez uniquement ce que vous utilisez.** De nombreux runbooks n’utilisent que des assistants basés sur Graph (par ex. `Send-RjRbReportEmail` sans `-UseNativeGraphRequest`, ou `Invoke-RjRbRestMethodGraph`) et n’utilisent jamais de cmdlet Az.\*. Promouvoir `Az.Accounts` à `RequiredModules` obligerait chaque runbook consommateur à embarquer le module même si 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 `RequiredModules` contrainte déclenche une résolution automatique au moment de l’import et peut entraîner l’inclusion d’une `Az.Accounts` version qui entre en conflit avec celle 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 module est au niveau du runbook via `#Requires`, et non au niveau du module d’aide. Le module d’aide expose la dépendance à titre informatif (via `ExternalModuleDependencies` dans le manifeste) et via la vérification à l’exécution ci-dessus, de sorte qu’une mauvaise configuration échoue de façon explicite avec un message exploitable plutôt que de masquer silencieusement un conflit de versions.

`Az.Storage` est **ne** 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 nécessite les chemins de fichier locaux, le nom du conteneur, le groupe de ressources et le nom du Storage Account :

```powershell
$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` sur l’ `rapports` dans le conteneur `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, valable pendant les 6 jours par défaut.

## Paramètres

### Obligatoire

| Paramètre            | Type       | Description                                                                                                                                                                                                                                                                                           |
| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FilePaths`          | `string[]` | 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 dès le départ 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 relié au paramètre central `RJReport.StorageAccount.ResourceGroup`.                                                                                                                                                                |
| `StorageAccountName` | `string`   | Nom de l’Azure Storage Account. Généralement relié au paramètre central `RJReport.StorageAccount.StorageAccountName`.                                                                                                                                                                                 |

### Facultatif

| Paramètre           | Type     | Valeur par défaut | Description                                                                                                                                                                                                                                    |
| ------------------- | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SubscriptionId`    | `string` | contexte actuel   | abonnement Azure qui héberge le Storage Account. S’il est fourni, `Set-AzContext -Subscription` est appelé avant toute opération de stockage. Omettez-le pour utiliser le `module Az` contexte.                                                |
| `LinkExpiryDays`    | `int`    | `6`               | Validité du lien SAS en jours. Validée pour `[1, 3650]`. Le même horodatage d’expiration est appliqué à tous les blobs dans un même appel. Généralement relié au paramètre central `RJReport.StorageAccount.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 mappage 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 du rapport de runbook — livraison du Storage Account](https://docs.realmjoin.com/fr/automatisation/runbooks/runbook-report-settings.md#storage-account-delivery).

## Exemples d'utilisation

### Modèle de runbook recommandé

C’est le modèle canonique utilisé par les runbooks de reporting. La configuration de stockage est récupérée depuis la personnalisation centrale RealmJoin via `Use-RJInterface -Type Setting`, le conteneur est codé en dur par runbook, et une configuration manquante provoque l’abandon du runbook avec un message exploitable :

```powershell
#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 RJ Runbooks Customization"
    "## ( https://portal.realmjoin.com/settings/runbooks-customizations ) pour configurer :"
    "##   - RJReport.StorageAccount.ResourceGroup"
    "##   - RJReport.StorageAccount.StorageAccountName"
    throw "Missing Storage Account Configuration."
}

# … 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 utiles à respecter lors de l’adoption de ce modèle :

* Les trois paramètres centraux (`ResourceGroup`, `StorageAccountName`, `LinkExpiryDays`) sont exposés comme paramètres de 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’export — il n’est intentionnellement *ne* 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 `bloc principal try { … } catch { throw $_ } finally { Disconnect-AzAccount … }` afin que les échecs partiels remontent vers le travail Automation et que le contexte Az soit libéré même en cas de réussite.

### Plusieurs fichiers dans un seul appel

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

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

foreach ($r in $results) {
    "Téléversé $($r.BlobName) — téléchargeable jusqu’au $($r.EndTime) : $($r.SASLink)"
}
```

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

```powershell
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.

### En combinaison avec `Send-RjRbReportEmail`

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

```powershell
$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 = @"
# Inventaire des appareils

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

$linkLine
"@

Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         'it-reports@contoso.com' `
    -Subject         "Inventaire des appareils — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd
```

Voir [Send-RjRbReportEmail](https://docs.realmjoin.com/fr/dev-reference/report-functions/send-rjrbreportemail.md) 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 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 compte` (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 `Échec de la création du conteneur (<status>) : <body>`. Un HTTP 403 avec `KeyBasedAuthenticationNotPermitted` signifie que l’accès par clé partagée est désactivé sur le Storage Account.

### Échecs de téléversement

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

### Échecs de récupération de la 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 `Échec de la 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 :

* 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.StorageAccount.ResourceGroup` / `RJReport.StorageAccount.StorageAccountName` non configurés — voir [Paramètres de rapport du runbook](https://docs.realmjoin.com/fr/automatisation/runbooks/runbook-report-settings.md#storage-account-delivery).

### Caractéristiques du jeton SAS

Les jetons générés utilisent :

* `sv=2023-11-03` (version signée)
* `sr=b` (à portée de blob)
* `sp=r` (lecture seule)
* `spr=https` (HTTPS uniquement)
* `st` réglé à 5 minutes dans le passé (tolérance aux écarts d’horloge) et `se` à `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** — considérez 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` | `string`   | 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`  | `string`   | URL de téléchargement HTTPS complète avec jeton SAS 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 du rapport de runbook — livraison du Storage Account](https://docs.realmjoin.com/fr/automatisation/runbooks/runbook-report-settings.md#storage-account-delivery) — configuration centrale du Storage Account, de l’expiration du lien et du préfixe de nom de blob utilisés par les runbooks de reporting.
* [Send-RjRbReportEmail](https://docs.realmjoin.com/fr/dev-reference/report-functions/send-rjrbreportemail.md) — assistant complémentaire pour la remise des rapports par e-mail ; souvent combiné avec cette fonction pour conserver une charge utile d’e-mail réduite.
* Microsoft Docs : [Autoriser avec Shared Key](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key) — schéma de signature utilisé par l’assistant.
* Microsoft Docs : [Créer un SAS de service](https://learn.microsoft.com/en-us/rest/api/storageservices/create-service-sas) — format de jeton SAS renvoyé dans `SASLink`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/fr/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
