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

# Publish-RjRbFilesToStorageContainer

Laden Sie lokale Dateien aus Azure Automation-Runbooks in einen Azure Storage-Container hoch und geben Sie zeitlich begrenzte SAS-Downloadlinks zurück.

## Übersicht

`Publish-RjRbFilesToStorageContainer` ist der Standardhelfer für die Bereitstellung von Berichtsdateien (CSV, XLSX, ZIP, …) aus RealmJoin-Reporting-Runbooks über Azure Blob Storage. Er lädt eine oder mehrere lokale Dateien in einen Ziel-Container hoch und gibt für jedes Blob einen zeitlich begrenzten SAS-Downloadlink zurück, der sich für die Einbindung in E-Mail-Berichte, Teams-Nachrichten oder Runbook-Ausgaben eignet.

Wesentliche Merkmale:

* **Kein `Az.Storage` Abhängigkeit** — Blob-Operationen werden direkt über die Azure Storage REST API ausgeführt (Containererstellung, Upload, SAS-Token-Generierung). Dadurch wird der bekannte Assembly-Konflikt zwischen `Az.Storage` und `ExchangeOnlineManagement` vermieden, der in gemischten Reporting-Runbooks auftritt.
* **Selbstverbindend** — wenn kein `Az` Kontext aktiv ist, ruft die Funktion transparent `Connect-RjRbAzAccount`. Ein optionaler `-SubscriptionId` schaltet vor jeder Speicheroperation den Kontext um.
* **Container automatisch erstellt** — wenn der Ziel-Container noch nicht existiert, wird er bei Bedarf erstellt; ein vorhandener Container (HTTP 409) wird als Erfolg behandelt.
* **HttpClient-basierte Uploads** — verwendet `System.Net.Http.HttpClient` direkt, weil der Interceptor von Azure Automation `Invoke-RestMethod` erforderliche benutzerdefinierte Header (`x-ms-blob-type`) bei binären Bodies entfernt.
* **Schreibgeschützte SAS-Links** — jede zurückgegebene URL wird mit dem Schlüssel des Storage Account signiert, auf ein einzelnes Blob beschränkt, nur für HTTPS gültig und für `LinkExpiryDays` Tage gültig (Standard 6).

Die zentralen Speichereinstellungen (Resource Group, Kontoname, Ablauf-Tage, Blob-Namenspräfix), die von einem typischen Runbook verwendet werden, sind im RealmJoin-Anpassungs-JSON hinterlegt und in [Runbook Report Settings — Storage Account-Bereitstellung](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-report-settings.md#storage-account-delivery)dokumentiert. Dieses Dokument konzentriert sich auf den Aufruf der Funktion aus einem Runbook.

## Voraussetzungen

### Azure Storage Account

Ein vorhandener Azure Storage Account (General Purpose v2 empfohlen) ist erforderlich. Der Ziel-Container muss vorher nicht existieren — er wird bei der ersten Verwendung automatisch erstellt.

### Azure RBAC auf dem Storage Account

Die verwaltete Identität des Automation Accounts (oder der Service Principal, der vom Runbook verwendet wird) benötigt die folgenden Berechtigungen auf dem Storage Account:

| Aktion                                              | Erforderlich für                                                                             |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `Microsoft.Storage/storageAccounts/read`            | Lesen des Storage Account                                                                    |
| `Microsoft.Storage/storageAccounts/listKeys/action` | Abrufen des Kontoschlüssels, der für SharedKey-Signierung und SAS-Generierung verwendet wird |

Weisen Sie die integrierte Rolle **Reader and Data Access** dem Storage Account zu: Sie ist die kleinste integrierte Rolle, die beides abdeckt. Containererstellung, Upload und SAS-Generierung werden mit dem Kontoschlüssel autorisiert und benötigen keine weiteren Azure RBAC-Berechtigungen. **Storage Account Contributor** funktioniert ebenfalls, erlaubt aber zusätzlich das Verwalten und Löschen des Storage Account. **Storage Blob Data Contributor** allein ist *nicht* ausreichend, da die Funktion Anfragen mit dem Kontoschlüssel signiert, anstatt AAD-gestützte Blob-Operationen zu verwenden.

Da sich die Funktion mit dem Kontoschlüssel authentifiziert, muss der Shared-Key-Zugriff auf dem Storage Account zulässig sein (`allowSharedKeyAccess` darf nicht `falsch`). Der Schlüssel gewährt Zugriff auf alle Daten im Storage Account, daher wird ein dedizierter Storage Account für Berichte empfohlen.

### Modulverbindung

Die Funktion benötigt das `Az.Accounts` Modul in der Runbook-Umgebung (`Get-AzContext`, `Set-AzContext`, `Connect-AzAccount`, `Invoke-AzRestMethod`). Deklarieren Sie es explizit im konsumierenden Runbook:

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

Wenn `Az.Accounts` nicht zur Laufzeit verfügbar ist, schlägt die Funktion sofort mit einer klaren Fehlermeldung fehl — sie prüft im Vorfeld auf `Get-AzContext` im Vorfeld und wirft *"Publish-RjRbFilesToStorageContainer requires the 'Az.Accounts' module. Add #Requires -Modules @{ModuleName = 'Az.Accounts'; ModuleVersion = '5.3.4'} to the calling runbook."* bevor ein Azure-Aufruf erfolgt.

> **Warum ist `Az.Accounts` nicht als `RequiredModules` Eintrag in `RealmJoin.RunbookHelper.psd1`?**
>
> `Az.Accounts` ist absichtlich nur unter `ExternalModuleDependencies` (informativ) und *nicht* unter `RequiredModules` (erzwungen bei `Import-Module` Laufzeit):
>
> * **Zahle nur für das, was du nutzt.** Viele Runbooks verwenden nur Graph-basierte Hilfsfunktionen (z. B. `Send-RjRbReportEmail` ohne `-UseNativeGraphRequest`, oder `Invoke-RjRbRestMethodGraph`) und verwenden nie ein Az.\*-Cmdlet. Das Hochstufen von `Az.Accounts` an `RequiredModules` würde jedes konsumierende Runbook zwingen, das Modul auszuliefern, selbst wenn nichts in seinem Codepfad es benötigt — dadurch würde die Kaltstartzeit in Azure Automation messbar steigen.
> * **Vermeide Versionsgefechte.** Eine harte `RequiredModules` Vorgabe löst beim Import eine automatische Auflösung aus und kann eine bestimmte `Az.Accounts` Version mitbringen, die mit dem kollidiert, was das Runbook selbst festlegt (Az.\*-Untermodule sind notorisch versionssensibel). Wenn das Runbook seine eigene `#Requires -Modules` deklarieren lässt, bleibt die Versionswahl beim Aufrufer.
> * **Autorität pro Runbook.** In Azure Automation ist der kanonische Ort zum Deklarieren von Modulanforderungen auf Runbook-Ebene über `#Requires`, nicht auf der Ebene des Hilfsmoduls. Das Hilfsmodul macht die Abhängigkeit informativ sichtbar (über `ExternalModuleDependencies` im Manifest) und über die Laufzeitprüfung oben, sodass eine Fehlkonfiguration laut mit einer umsetzbaren Meldung fehlschlägt, statt einen Versionskonflikt stillschweigend zu verbergen.

`Az.Storage` ist **nicht** erforderlich und sollte nicht im selben Runbook importiert werden, um den oben genannten Assembly-Konflikt zu vermeiden.

## Schnellstart

Der minimale funktionsfähige Aufruf erfordert die lokalen Dateipfade, den Containernamen, die Ressourcengruppe und den Namen des 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
```

Dies lädt `devices.csv` für das `Berichte` Container in `stcontosoreports` und gibt ein Objekt mit dem Blob-Namen, dem SAS-Ablaufzeitpunkt und einer direkt teilbaren Download-URL zurück, die standardmäßig 6 Tage gültig ist.

## Parameter

### Erforderlich

| Parameter            | Typ        | Beschreibung                                                                                                                                                                                                                                                                                                           |
| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FilePaths`          | `string[]` | Ein oder mehrere lokale Dateipfade zum Hochladen. Jeder Pfad muss auf eine vorhandene Datei verweisen (`Test-Path -PathType Leaf`); die Funktion wirft im Vorfeld, wenn ein Eintrag fehlt.                                                                                                                             |
| `ContainerName`      | `string`   | Ziel-Blob-Container. Wird automatisch erstellt, falls er nicht existiert. Muss den Azure-Container-Namensregeln entsprechen (Kleinbuchstaben, 3–63 Zeichen, alphanumerisch + Bindestrich). Der Containername ist eine *pro Runbook* Entscheidung und wird im Runbook festgelegt, nicht in den zentralen Einstellungen. |
| `ResourceGroupName`  | `string`   | Ressourcengruppe, die den Storage Account enthält. Normalerweise an die zentrale Einstellung gekoppelt `RJReport.StorageAccount.ResourceGroup`.                                                                                                                                                                        |
| `StorageAccountName` | `string`   | Name des Azure Storage Account. Normalerweise an die zentrale Einstellung gekoppelt `RJReport.StorageAccount.StorageAccountName`.                                                                                                                                                                                      |

### Optional

| Parameter           | Typ      | Standard          | Beschreibung                                                                                                                                                                                                                                        |
| ------------------- | -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SubscriptionId`    | `string` | aktueller Kontext | Azure-Abonnement, das den Storage Account hostet. Wenn angegeben, `Set-AzContext -Subscription` wird vor jeder Speicheroperation aufgerufen. Weglassen, um den aktuellen `Az` Kontext zu verwenden.                                                 |
| `LinkExpiryDays`    | `int`    | `6`               | Gültigkeit des SAS-Links in Tagen. Wird validiert auf `[1, 3650]`. Derselbe Ablaufzeitpunkt wird auf alle Blobs in einem einzelnen Aufruf angewendet. Normalerweise an die zentrale Einstellung gekoppelt `RJReport.StorageAccount.LinkExpiryDays`. |
| `AddBlobNamePrefix` | `bool`   | `$false`          | Wenn `$true`, erhalten Blob-Namen das Präfix `yyyyMMdd-HHmmss-` (Zeitstempel von `Get-Date` zum Zeitpunkt des Uploads), um Überschreibungen bei wiederholten Läufen zu verhindern. Der ursprüngliche Dateiname bleibt als Suffix erhalten.          |

> **Hinweis:** Die Zuordnung zwischen diesen Parametern und dem zentralen RealmJoin-Anpassungs-JSON (einschließlich der empfohlenen Standardwerte) ist dokumentiert in [Runbook Report Settings — Storage Account-Bereitstellung](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-report-settings.md#storage-account-delivery).

## Verwendungsbeispiele

### Empfohlenes Runbook-Muster

Dies ist das kanonische Muster, das von Reporting-Runbooks verwendet wird. Die Speicherkonfiguration wird aus der zentralen RealmJoin-Anpassung über `Use-RJInterface -Type Setting`, der Container ist pro Runbook fest codiert, und eine fehlende Konfiguration führt dazu, dass das Runbook mit einer umsetzbaren Meldung abbricht:

```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)) {
    "## Um in einen Storage Account zu exportieren, verwenden Sie bitte RJ Runbooks Customization"
    "## ( https://portal.realmjoin.com/settings/runbooks-customizations ) zum Konfigurieren:"
    "##   - RJReport.StorageAccount.ResourceGroup"
    "##   - RJReport.StorageAccount.StorageAccountName"
    throw "Fehlende Storage Account-Konfiguration."
}

# … die Exportdatei erzeugen …
$exportPath = "myReport.csv"

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

$uploadResult = $uploadResults[0]
"## Export erstellt."
"## Ablauf des Links: $($uploadResult.EndTime)"
$uploadResult.SASLink | Out-String
```

Einige Konventionen, die es sich lohnt beizubehalten, wenn dieses Muster übernommen wird:

* Die drei zentralen Einstellungen (`ResourceGroup`, `StorageAccountName`, `LinkExpiryDays`) werden als Runbook-Parameter bereitgestellt und über `Use-RJInterface -Type Setting`, aber typischerweise *ausgeblendet* in der Runbook-Anpassung (`"Hide": true`) sodass Endbenutzer sie nie sehen.
* Der Containername ist pro Runbook fest codiert (oft über einen `Param` -Standardwert), sodass Lebenszyklusrichtlinien und Zugriffssteuerungen pro Exporttyp angepasst werden können — er ist absichtlich *nicht* keine zentrale Einstellung.
* `AddBlobNamePrefix $true` ist die sichere Standardeinstellung für regelmäßige Exporte, die bei jedem Lauf einen festen Dateinamen erzeugen.
* Die Funktion wird innerhalb des Haupt- `try { … } catch { throw $_ } finally { Disconnect-AzAccount … }` Blocks aufgerufen, sodass Teilfehler an den Automation-Job weitergereicht werden und der Az-Kontext selbst bei Erfolg freigegeben wird.

### Mehrere Dateien in einem Aufruf

`FilePaths` akzeptiert ein Array; jede Datei wird nacheinander hochgeladen und für jedes hochgeladene Blob wird ein Ergebnisobjekt zurückgegeben.

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

foreach ($r in $results) {
    "$($r.BlobName) wurde hochgeladen — Download bis $($r.EndTime): $($r.SASLink)"
}
```

### Benutzerdefinierte Link-Laufzeit und explizites Abonnement

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

Nützlich, wenn das Runbook mehrere Abonnements umfasst oder wenn nachgelagerte Empfänger ein längeres Zeitfenster als die 6-Tage-Standardeinstellung benötigen.

### Kombinieren mit `Send-RjRbReportEmail`

Ein gängiges Muster besteht darin, umfangreiche Daten in Blob Storage hochzuladen und den SAS-Link in eine Berichts-E-Mail einzubetten, sodass die E-Mail deutlich unter der 4-MB-Graph `sendMail` Limit bleibt:

```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 = @"
# Geräteinventar

Die vollständige Geräteliste steht als Download zur Verfügung:

$linkLine
"@

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

Siehe [Send-RjRbReportEmail](https://docs.realmjoin.com/de/dev-reference/report-functions/send-rjrbreportemail.md) für den E-Mail-Teil dieses Musters.

## Verhalten & Fehlerbehandlung

### Frühe Dateivalidierung

Bevor ein Azure-Aufruf erfolgt, iteriert die Funktion über `FilePaths` und wirft `Datei '<path>' wurde nicht gefunden.` für den ersten fehlenden Eintrag. Dadurch werden Teil-Uploads verhindert, wenn der Aufrufer sich vertippt.

### Azure-Kontextauflösung

`Get-AzContext` wird zuerst geprüft. Wenn kein Kontext vorhanden ist oder der Kontext kein `Konto` (z. B. bei einer frischen Runbook-Ausführung) ruft die Funktion `Connect-RjRbAzAccount` auf, um die verwaltete Identität zu authentifizieren. Wenn `-SubscriptionId` angegeben ist, `Set-AzContext -Subscription` wird anschließend aufgerufen.

### Containererstellung

Der Container wird mit einem `PUT …?restype=container` Aufruf:

* **HTTP 201** — Container erstellt.
* **HTTP 409** — Container existiert bereits; wird als Erfolg behandelt.
* **Jeder andere Status** — die Funktion wirft `Containererstellung fehlgeschlagen (<status>): <body>`. Ein HTTP 403 mit `KeyBasedAuthenticationNotPermitted` bedeutet, dass Shared-Key-Zugriff auf dem Storage Account deaktiviert ist.

### Upload-Fehler

Jede Datei wird hochgeladen über `HttpClient.SendAsync`. Ein nicht erfolgreicher Status beendet den Aufruf mit `Blob-Upload fehlgeschlagen (<status>): <body>`, einschließlich des von Azure Storage zurückgegebenen Rohfehlers. Früher hochgeladene Dateien, die im selben Aufruf bereits übertragen wurden, verbleiben im Storage Account — der Aufrufer sollte den Aufruf möglicherweise in ein try/catch einschließen und bei nicht akzeptablen Teil-Uploads eine Bereinigung durchführen.

### Fehler beim Abrufen der Schlüssel

`Invoke-AzRestMethod` wird verwendet, um den ARM `listKeys` Endpunkt aufzurufen. Wenn der Antwortstatus etwas anderes als 200 ist, wirft die Funktion `Fehler beim Abrufen der Storage-Account-Schlüssel für '<account>' in der Ressourcengruppe '<rg>'. Status: <status>`. Die häufigsten Ursachen sind:

* Fehlend `Microsoft.Storage/storageAccounts/listKeys/action` bei der verwalteten Identität.
* Falscher Abonnementkontext (kombiniert mit `-SubscriptionId`).
* Tippfehler in `StorageAccountName` oder `ResourceGroupName`.
* Die zentralen Einstellungen `RJReport.StorageAccount.ResourceGroup` / `RJReport.StorageAccount.StorageAccountName` nicht konfiguriert — siehe [Runbook-Report-Einstellungen](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-report-settings.md#storage-account-delivery).

### SAS-Token-Eigenschaften

Die generierten Tokens verwenden:

* `sv=2023-11-03` (signierte Version)
* `sr=b` (auf Blob-Ebene)
* `sp=r` (schreibgeschützt)
* `spr=https` (nur HTTPS)
* `st` auf 5 Minuten in der Vergangenheit gesetzt (Toleranz für Zeitabweichungen) und `se` an `LinkExpiryDays` ab dem Zeitpunkt des Aufrufs.

Tokens werden mit dem Schlüssel des Storage Account signiert. **Jeder mit dem Link kann das Blob bis zum Ablauf herunterladen** — behandle die zurückgegebene SAS-URL als Geheimnis.

## Ausgaben

Jeder erfolgreiche Upload erzeugt ein `PSCustomObject` mit diesen Eigenschaften:

| Eigenschaft | Typ        | Beschreibung                                                                                                          |
| ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| `BlobName`  | `string`   | Der endgültige Blob-Name im Container, einschließlich des Zeitstempelpräfixes, falls `AddBlobNamePrefix` ist `$true`. |
| `EndTime`   | `datetime` | Lokale SAS-Ablaufzeit (auch in der URL als UTC kodiert).                                                              |
| `SASLink`   | `string`   | Voll qualifizierte HTTPS-Download-URL mit eingebettetem SAS-Token.                                                    |

Ergebnisse werden in derselben Reihenfolge zurückgegeben wie `FilePaths`. Selbst beim Hochladen einer einzelnen Datei ist der Rückgabewert ein Array — greife mit einem Index darauf zu (`$results[0]`) oder iteriere mit `foreach` anstatt es als Skalar zu behandeln.

## Siehe auch

* [Runbook Report Settings — Storage Account-Bereitstellung](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-report-settings.md#storage-account-delivery) — zentrale Konfiguration des Storage Account, der Link-Ablaufzeit und des Blob-Namenspräfixes, die von Reporting-Runbooks verwendet wird.
* [Send-RjRbReportEmail](https://docs.realmjoin.com/de/dev-reference/report-functions/send-rjrbreportemail.md) — begleitender Helfer für die Zustellung von Berichten per E-Mail; wird häufig mit dieser Funktion kombiniert, um die E-Mail-Nutzlast klein zu halten.
* Microsoft Docs: [Autorisierung mit Shared Key](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key) — vom Helfer verwendetes Signierschema.
* Microsoft Docs: [Einen Service-SAS erstellen](https://learn.microsoft.com/en-us/rest/api/storageservices/create-service-sas) — SAS-Token-Format, das zurückgegeben wird in `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/de/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.
