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

# Publish-RjRbFilesToStorageContainer

Carga archivos locales a un contenedor de Azure Storage desde runbooks de Azure Automation y devuelve enlaces de descarga SAS con tiempo limitado.

## Resumen

`Publish-RjRbFilesToStorageContainer` es el helper estándar para entregar archivos de informe (CSV, XLSX, ZIP, …) desde runbooks de informes de RealmJoin a través de Azure Blob Storage. Carga uno o más archivos locales a un contenedor de destino y devuelve un enlace de descarga SAS con tiempo limitado para cada blob, apto para incluir en correos de informe, mensajes de Teams o salidas del runbook.

Características clave:

* **Sin `Az.Storage` dependencia** — las operaciones con blobs se realizan directamente contra la Azure Storage REST API (creación de contenedores, carga, generación de SAS Token). Esto elimina el conocido conflicto de ensamblados entre `Az.Storage` y `ExchangeOnlineManagement` que aparece en runbooks de informes mixtos.
* **Autoconexión** — si no hay `módulo Az` un contexto activo, la función llama de forma transparente a `Connect-RjRbAzAccount`. Un `-SubscriptionId` conmutador opcional cambia el contexto antes de cualquier operación de almacenamiento.
* **Contenedor creado automáticamente** — si el contenedor de destino aún no existe, se crea sobre la marcha; un contenedor existente (HTTP 409) se trata como éxito.
* **Cargas basadas en HttpClient** — usa `System.Net.Http.HttpClient` directamente porque el `Invoke-RestMethod` interceptor de Azure Automation elimina los encabezados personalizados requeridos (`x-ms-blob-type`) con cuerpos binarios.
* **Enlaces SAS de solo lectura** — cada URL devuelta está firmada con la clave de la Storage Account, limitada a un único blob, solo HTTPS y válida durante `LinkExpiryDays` días (valor predeterminado 6).

La configuración central de almacenamiento (grupo de recursos, nombre de la cuenta, días de expiración, prefijo del nombre del blob) consumida por un runbook típico vive en el JSON de personalización de RealmJoin y se documenta en [Configuración de informe del runbook — entrega mediante Storage Account](https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-report-settings.md#storage-account-delivery). Este documento se centra en llamar a la función desde un runbook.

## Requisitos previos

### Azure Storage Account

Se requiere una Azure Storage Account existente (se recomienda general-purpose v2). El contenedor de destino no necesita existir previamente — se crea automáticamente en el primer uso.

### Azure RBAC en la Storage Account

La identidad administrada de la Automation Account (o el Service Principal usado por el runbook) necesita los siguientes permisos en la Storage Account:

| Acción                                              | Requerido para                                                                          |
| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `Microsoft.Storage/storageAccounts/read`            | Lectura de la Storage Account                                                           |
| `Microsoft.Storage/storageAccounts/listKeys/action` | Obtención de la clave de la cuenta usada para la firma SharedKey y la generación de SAS |

Asigne el rol integrado **Reader and Data Access** en la Storage Account: es el rol integrado más pequeño que cubre ambos. La creación de contenedores, la carga y la generación de SAS se autorizan con la clave de la cuenta y no necesitan más permisos de Azure RBAC. **Storage Account Contributor** también funciona, pero además permite administrar y eliminar la Storage Account. **Storage Blob Data Contributor** por sí sola es *no* suficiente porque la función firma las solicitudes con la clave de la cuenta en lugar de usar operaciones de blobs respaldadas por AAD.

Dado que la función se autentica con la clave de la cuenta, el acceso con clave compartida debe estar permitido en la Storage Account (`allowSharedKeyAccess` no debe ser `falso`). La clave concede acceso a todos los datos de la Storage Account, por lo que se recomienda una Storage Account dedicada para los informes.

### Conectividad del módulo

La función requiere el `Az.Accounts` módulo en el entorno del runbook (`Get-AzContext`, `Set-AzContext`, `Connect-AzAccount`, `Invoke-AzRestMethod`). Declárelo explícitamente en el runbook consumidor:

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

Si `Az.Accounts` no está disponible en tiempo de ejecución, la función falla rápidamente con un mensaje de error claro — comprueba `Get-AzContext` de antemano y lanza *"Publish-RjRbFilesToStorageContainer requiere el módulo 'Az.Accounts'. Agregue #Requires -Modules @{ModuleName = 'Az.Accounts'; ModuleVersion = '5.3.4'} al runbook que lo llama."* antes de hacer cualquier llamada a Azure.

> **¿Por qué no está `Az.Accounts` declarado como una entrada de `RequiredModules` en `RealmJoin.RunbookHelper.psd1`?**
>
> `Az.Accounts` se enumera intencionalmente solo en `ExternalModuleDependencies` (informativo) y *no* bajo `RequiredModules` (aplicado en `Import-Module` tiempo):
>
> * **Pague solo por lo que usa.** Muchos runbooks consumen solo helpers basados en Graph (p. ej. `Send-RjRbReportEmail` sin `-UseNativeGraphRequest`, o `Invoke-RjRbRestMethodGraph`) y nunca tocan ningún cmdlet Az.\*. Promover `Az.Accounts` a `RequiredModules` obligaría a que cada runbook consumidor empaquetara el módulo incluso cuando nada en su ruta de código lo necesita, aumentando de forma medible el tiempo de arranque en frío en Azure Automation.
> * **Evite disputas de versiones.** Una `RequiredModules` restricción rígida activa la auto-resolución en el momento de la importación y puede arrastrar una `Az.Accounts` versión específica que entre en conflicto con la que el propio runbook fija (los submódulos Az.\* son notoriamente sensibles a la versión). Permitir que el runbook declare su propio `#Requires -Modules` mantiene la elección de versión en manos del llamador.
> * **Autoridad por runbook.** En Azure Automation, el lugar canónico para declarar los requisitos de módulos es a nivel de runbook mediante `#Requires`, no a nivel del módulo helper. El módulo helper expone la dependencia de forma informativa (mediante `ExternalModuleDependencies` en el manifiesto) y mediante la comprobación en tiempo de ejecución anterior, de modo que una mala configuración falle con claridad y un mensaje accionable en lugar de ocultar silenciosamente un conflicto de versiones.

`Az.Storage` esté **no** es necesario y no debe importarse en el mismo runbook para evitar el conflicto de ensamblados mencionado arriba.

## Inicio rápido

La llamada mínima viable requiere la(s) ruta(s) local(es) del archivo, el nombre del contenedor, el grupo de recursos y el nombre de la 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
```

Esto carga `devices.csv` en el `reports` contenedor en `stcontosoreports` y devuelve un objeto con el nombre del blob, la marca de tiempo de expiración del SAS y una URL de descarga lista para compartir válida durante los 6 días predeterminados.

## Parámetros

### Obligatorio

| Parámetro            | Tipo       | Descripción                                                                                                                                                                                                                                                                                                     |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FilePaths`          | `string[]` | Una o más rutas locales de archivo para cargar. Cada ruta debe apuntar a un archivo existente (`Test-Path -PathType Leaf`); la función lanza un error de antemano si falta alguna entrada.                                                                                                                      |
| `ContainerName`      | `cadena`   | Contenedor de blob de destino. Se crea automáticamente si no existe. Debe cumplir las reglas de nomenclatura de contenedores de Azure (minúsculas, 3–63 caracteres, alfanumérico + guion). El nombre del contenedor es una decisión *por runbook* y se establece en el runbook, no en la configuración central. |
| `ResourceGroupName`  | `cadena`   | Grupo de recursos que contiene la Storage Account. Normalmente se vincula a la configuración central `RJReport.StorageAccount.ResourceGroup`.                                                                                                                                                                   |
| `StorageAccountName` | `cadena`   | Nombre de la Azure Storage Account. Normalmente se vincula a la configuración central `RJReport.StorageAccount.StorageAccountName`.                                                                                                                                                                             |

### Opcional

| Parámetro           | Tipo     | Predeterminado  | Descripción                                                                                                                                                                                                                                    |
| ------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SubscriptionId`    | `cadena` | contexto actual | suscripción de Azure que hospeda la Storage Account. Si se proporciona, `Set-AzContext -Subscription` se llama antes de cualquier operación de almacenamiento. Omítalo para usar el `módulo Az` contexto actual.                               |
| `LinkExpiryDays`    | `entero` | `6`             | Validez del enlace SAS en días. Se valida a `[1, 3650]`. La misma marca de tiempo de expiración se aplica a todos los blobs en una sola llamada. Normalmente se vincula a la configuración central `RJReport.StorageAccount.LinkExpiryDays`.   |
| `AddBlobNamePrefix` | `bool`   | `$false`        | Cuando `$true`, los nombres de blobs se prefijan con `yyyyMMdd-HHmmss-` (marca de tiempo de `Get-Date` en el momento de la carga) para evitar sobrescrituras en ejecuciones repetidas. El nombre original del archivo se conserva como sufijo. |

> **Nota:** La asignación entre estos parámetros y el JSON de personalización central de RealmJoin (incluidos los valores predeterminados recomendados) se documenta en [Configuración de informe del runbook — entrega mediante Storage Account](https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-report-settings.md#storage-account-delivery).

## Ejemplos de uso

### Patrón recomendado del runbook

Este es el patrón canónico usado por los runbooks de informes. La configuración de almacenamiento se obtiene de la personalización central de RealmJoin mediante `Use-RJInterface -Type Setting`, el contenedor está codificado de forma fija por runbook y una configuración faltante hace que el runbook se interrumpa con un mensaje accionable:

```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)) {
    "## Para exportar a una Storage Account, use RJ Runbooks Customization"
    "## ( https://portal.realmjoin.com/settings/runbooks-customizations ) para configurar:"
    "##   - RJReport.StorageAccount.ResourceGroup"
    "##   - RJReport.StorageAccount.StorageAccountName"
    throw "Missing Storage Account Configuration."
}

# … producir el archivo de exportación …
$exportPath = "myReport.csv"

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

$uploadResult = $uploadResults[0]
"## Exportación creada."
"## Expiración del enlace: $($uploadResult.EndTime)"
$uploadResult.SASLink | Out-String
```

Conviene mantener algunas convenciones al adoptar este patrón:

* Las tres configuraciones centrales (`ResourceGroup`, `StorageAccountName`, `LinkExpiryDays`) se exponen como parámetros del runbook vinculados mediante `Use-RJInterface -Type Setting`, pero normalmente se *ocultan* en la personalización del runbook (`"Hide": true`) para que los usuarios finales nunca las vean.
* El nombre del contenedor está codificado de forma fija por runbook (a menudo mediante un valor predeterminado de `param` ) para que las directivas de ciclo de vida y los controles de acceso puedan ajustarse por tipo de exportación — esto es intencionalmente *no* una configuración central.
* `AddBlobNamePrefix $true` es el valor predeterminado seguro para exportaciones periódicas que producen un nombre de archivo fijo en cada ejecución.
* La función se llama dentro del principal `try { … } catch { throw $_ } finally { Disconnect-AzAccount … }` bloque para que los fallos parciales se propaguen al trabajo de Automation y el contexto de Az se libere incluso si todo sale bien.

### Varios archivos en una sola llamada

`FilePaths` acepta un array; cada archivo se carga secuencialmente y se devuelve un objeto de resultado por cada blob cargado.

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

foreach ($r in $results) {
    "Cargado $($r.BlobName) — descarga hasta $($r.EndTime): $($r.SASLink)"
}
```

### Duración personalizada del enlace y suscripción explícita

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

Útil cuando el runbook abarca varias suscripciones, o cuando los destinatarios posteriores necesitan una ventana más larga que el valor predeterminado de 6 días.

### Combinado con `Send-RjRbReportEmail`

Un patrón común es cargar datos voluminosos al almacenamiento de blobs e incrustar el enlace SAS en un correo del informe, manteniendo el correo muy por debajo del límite de 4 MB de Graph `sendMail` límite:

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

$linkLine = "[Descargar {0}]({1}) (válido hasta {2:yyyy-MM-dd HH:mm} UTC)" -f `
    $uploaded[0].BlobName, $uploaded[0].SASLink, $uploaded[0].EndTime.ToUniversalTime()

$reportMd = @"
# Inventario de dispositivos

La lista completa de dispositivos está disponible para descarga:

$linkLine
"@

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

Consulta [Send-RjRbReportEmail](https://docs.realmjoin.com/es/dev-reference/report-functions/send-rjrbreportemail.md) para la parte de correo electrónico de este patrón.

## Comportamiento y manejo de errores

### Validación previa del archivo

Antes de hacer cualquier llamada a Azure, la función recorre `FilePaths` y lanza `No se encontró el archivo '<path>'.` para la primera entrada faltante. Esto evita cargas parciales cuando el llamador comete un error tipográfico.

### Resolución del contexto de Azure

`Get-AzContext` se comprueba primero. Si no hay contexto o el contexto no tiene `Account` (p. ej., una ejecución nueva del runbook), la función llama a `Connect-RjRbAzAccount` para autenticar la identidad administrada. Si `-SubscriptionId` se proporciona, `Set-AzContext -Subscription` se invoca a continuación.

### Creación del contenedor

El contenedor se crea con una solicitud `PUT …?restype=container` :

* **HTTP 201** — contenedor creado.
* **HTTP 409** — el contenedor ya existe; se trata como éxito.
* **Cualquier otro estado** — la función lanza `Error en la creación del contenedor (<status>): <body>`. Un HTTP 403 con `KeyBasedAuthenticationNotPermitted` significa que el acceso con clave compartida está deshabilitado en la Storage Account.

### Fallos de carga

Cada archivo se carga mediante `HttpClient.SendAsync`. Un estado no satisfactorio termina la llamada con `La carga del blob falló (<status>): <body>`, incluido el error sin procesar devuelto por Azure Storage. Los archivos anteriores que ya se habían cargado en la misma llamada permanecen en la Storage Account; es posible que el llamador quiera envolver la llamada en try/catch y ejecutar una limpieza si las cargas parciales no son aceptables.

### Fallos en la obtención de claves

`Invoke-AzRestMethod` se usa para llamar al endpoint de ARM `listKeys` . Si el estado de respuesta es cualquier cosa distinta de 200, la función lanza `No se pudieron obtener las claves de la Storage Account para '<account>' en el grupo de recursos '<rg>'. Estado: <status>`. Las causas más comunes son:

* Falta `Microsoft.Storage/storageAccounts/listKeys/action` en la identidad administrada.
* Contexto de suscripción incorrecto (combínelo con `-SubscriptionId`).
* Error tipográfico en `StorageAccountName` o `ResourceGroupName`.
* Las configuraciones centrales `RJReport.StorageAccount.ResourceGroup` / `RJReport.StorageAccount.StorageAccountName` no están configuradas — consulte [Configuración del informe del runbook](https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-report-settings.md#storage-account-delivery).

### Características del token SAS

Los tokens generados usan:

* `sv=2023-11-03` (versión firmada)
* `sr=b` (limitado al blob)
* `sp=r` (solo lectura)
* `spr=https` (solo HTTPS)
* `st` establecido 5 minutos en el pasado (tolerancia a desfase del reloj) y `se` a `LinkExpiryDays` desde el momento de la llamada.

Los tokens se firman con la clave de la Storage Account. **Cualquiera con el enlace puede descargar el blob hasta la expiración** — trate la URL SAS devuelta como un secreto.

## Salidas

Cada carga correcta produce un `PSCustomObject` con estas propiedades:

| Propiedad  | Tipo       | Descripción                                                                                                            |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| `BlobName` | `cadena`   | El nombre final del blob en el contenedor, incluido el prefijo de marca de tiempo si `AddBlobNamePrefix` esté `$true`. |
| `EndTime`  | `datetime` | Expiración SAS en hora local (también codificada en la URL como UTC).                                                  |
| `SASLink`  | `cadena`   | URL de descarga HTTPS completamente calificada con token SAS incrustado.                                               |

Los resultados se devuelven en el mismo orden que `FilePaths`. Incluso al cargar un solo archivo, el valor devuelto es un array — índicelo (`$results[0]`) o itere con `foreach` en lugar de tratarlo como un escalar.

## Véase también

* [Configuración de informe del runbook — entrega mediante Storage Account](https://docs.realmjoin.com/es/automatizacion/runbooks/runbook-report-settings.md#storage-account-delivery) — configuración central de la Storage Account, expiración del enlace y prefijo del nombre del blob utilizados por los runbooks de informes.
* [Send-RjRbReportEmail](https://docs.realmjoin.com/es/dev-reference/report-functions/send-rjrbreportemail.md) — helper complementario para entregar informes por correo electrónico; comúnmente se combina con esta función para mantener pequeño el payload del correo.
* Microsoft Docs: [Autorizar con clave compartida](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key) — esquema de firma usado por el helper.
* Microsoft Docs: [Crear un SAS de servicio](https://learn.microsoft.com/en-us/rest/api/storageservices/create-service-sas) — formato del token SAS devuelto en `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/es/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.
