diff --git a/README.md b/README.md index 9b41f56c..5ddc4f70 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,15 @@ Below are the available commands: ### Examples +**Backing up All Data from an Environment with Secure Asset Delivery Enabled** + +```bash +npx @kontent-ai/data-ops@latest environment backup \ + --environmentId \ + --apiKey \ + --secureAssetDeliveryKey= +``` + **Creating an Environment Backup including Content Items and Assets** ```bash diff --git a/src/commands/environment/backupRestore/README.md b/src/commands/environment/backupRestore/README.md index 04537c04..8e33f8cb 100644 --- a/src/commands/environment/backupRestore/README.md +++ b/src/commands/environment/backupRestore/README.md @@ -49,14 +49,15 @@ npx @kontent-ai/data-ops@latest environment backup --help ### Parameters -| Parameter | Description | -|-------------------|-----------------------------------------------------------------------------------| -| `--environmentId` | The ID of the environment you want to backup. | -| `--apiKey` | The Management API key for the environment. | -| `--fileName` | (Optional) The name of the output `.zip` file. Default is `backup.zip`. | -| `--include` | (Optional) Specify entities to include in the backup. | -| `--exclude` | (Optional) Specify entities to exclude from the backup. | -| `--configFile` | (Optional) Path to a JSON configuration file containing parameters. | +| Parameter | Description | +| -------------------------- | ----------------------------------------------------------------------- | +| `--environmentId` | The ID of the environment you want to backup. | +| `--apiKey` | The Management API key for the environment. | +| `--secureAssetDeliveryKey` | (Optional) The secure asset delivery API key for the environment.
Read more about enabling secure asset delivery in the [Kontent.ai documentation](https://kontent.ai/learn/docs/security/secure-access/javascript#a-retrieve-assets-securely). | +| `--fileName` | (Optional) The name of the output `.zip` file. Default is `backup.zip`. | +| `--include` | (Optional) Specify entities to include in the backup. | +| `--exclude` | (Optional) Specify entities to exclude from the backup. | +| `--configFile` | (Optional) Path to a JSON configuration file containing parameters. | ### Examples @@ -77,6 +78,15 @@ npx @kontent-ai/data-ops@latest environment backup \ --exclude roles ``` +**Backing up All Data from an Environment with Secure Asset Delivery Enabled** + +```bash +npx @kontent-ai/data-ops@latest environment backup \ + --environmentId= \ + --apiKey= \ + --secureAssetDeliveryKey= +``` + ### Backup Programmatically To backup data from an environment in your scripts, use the `backupEnvironment` function: @@ -89,6 +99,8 @@ const params: BackupEnvironmentParams = { apiKey: "", // Optional: specify output file name // fileName: "backup.zip", + // Optional: specify secure asset delivery API key + // secureAssetDeliveryKey: "", // Optional: include or exclude specific entities // include: ["contentItems", "assets"], // exclude: ["roles"], @@ -154,14 +166,14 @@ npx @kontent-ai/data-ops@latest environment restore --fileName ### Parameters -| Parameter | Description | -|-------------------|----------------------------------------------------------------------------| -| `--fileName` | The path to the `.zip` file containing the data to restore. | -| `--environmentId` | The ID of the target environment where you want to restore data to. | -| `--apiKey` | The Management API key for the target environment. | -| `--include` | (Optional) Specify entities to restore. | -| `--exclude` | (Optional) Specify entities to exclude from the restore. | -| `--configFile` | (Optional) Path to a JSON configuration file containing parameters. | +| Parameter | Description | +| ----------------- | ------------------------------------------------------------------- | +| `--fileName` | The path to the `.zip` file containing the data to restore. | +| `--environmentId` | The ID of the target environment where you want to restore data to. | +| `--apiKey` | The Management API key for the target environment. | +| `--include` | (Optional) Specify entities to restore. | +| `--exclude` | (Optional) Specify entities to exclude from the restore. | +| `--configFile` | (Optional) Path to a JSON configuration file containing parameters. | ### Examples diff --git a/src/commands/environment/backupRestore/backup.ts b/src/commands/environment/backupRestore/backup.ts index fc159949..17481039 100644 --- a/src/commands/environment/backupRestore/backup.ts +++ b/src/commands/environment/backupRestore/backup.ts @@ -36,6 +36,11 @@ export const register: RegisterCommand = yargs => demandOption: "You need to provide a Management API key for the given Kontent.ai environment.", alias: "k", }) + .option("secureAssetDeliveryKey", { + type: "string", + describe: + "You need to provide a asset delivery key when secure asset delivery is enabled for the given Kontent.ai environment.", + }) .option("include", { type: "array", describe: "Only back up specified entities.", @@ -62,6 +67,7 @@ type BackupEnvironmentCliParams = environmentId: string; fileName: string | undefined; apiKey: string; + secureAssetDeliveryKey: string | undefined; include: ReadonlyArray | undefined; exclude: ReadonlyArray | undefined; kontentUrl: string | undefined; diff --git a/src/modules/backupRestore/backup.ts b/src/modules/backupRestore/backup.ts index e8dad6ef..46dbac73 100644 --- a/src/modules/backupRestore/backup.ts +++ b/src/modules/backupRestore/backup.ts @@ -59,6 +59,7 @@ export type BackupEnvironmentParams = Readonly< environmentId: string; fileName?: string; apiKey: string; + secureAssetDeliveryKey?: string; kontentUrl?: string; } & IncludeExclude @@ -101,7 +102,12 @@ export const backupEnvironmentInternal = async ( try { const entities = await def.fetchEntities(client); - await (def as EntityDefinition).addOtherFiles?.(entities, archive, params); + await (def as EntityDefinition).addOtherFiles?.( + entities, + archive, + params, + params.secureAssetDeliveryKey, + ); const result = def.serializeEntities(entities); archive.append(result, { name: `${def.name}.json` }); diff --git a/src/modules/backupRestore/backupRestoreEntities/entities/assets.ts b/src/modules/backupRestore/backupRestoreEntities/entities/assets.ts index 8309acd0..42a9d621 100644 --- a/src/modules/backupRestore/backupRestoreEntities/entities/assets.ts +++ b/src/modules/backupRestore/backupRestoreEntities/entities/assets.ts @@ -24,8 +24,8 @@ export const assetsEntity = { fetchEntities: client => client.listAssets().toAllPromise().then(res => res.data.items.map(a => a._raw as AssetWithElements)), serializeEntities: JSON.stringify, - addOtherFiles: async (assets, archive, logOptions) => { - await serially(assets.map(a => () => saveAsset(archive, logOptions, a))); + addOtherFiles: async (assets, archive, logOptions, secureAssetDeliveryKey) => { + await serially(assets.map(a => () => saveAsset(archive, logOptions, a, secureAssetDeliveryKey))); }, deserializeEntities: JSON.parse, importEntities: async (client, fileAssets, context, logOptions, zip) => { @@ -69,9 +69,14 @@ const saveAsset = async ( archive: archiver.Archiver, logOptions: LogOptions, asset: AssetContracts.IAssetModelContract, + secureAssetDeliveryKey: string | undefined, ) => { logInfo(logOptions, "verbose", `Exporting: file ${chalk.yellow(asset.file_name)}.`); - const file = await fetch(asset.url).then(res => res.blob()).then(res => res.stream()); + const defaultOptions: RequestInit = { + headers: secureAssetDeliveryKey ? { Authorization: `Bearer ${secureAssetDeliveryKey}` } : undefined, + }; + const file = await fetch(asset.url, defaultOptions) + .then(res => res.blob()).then(res => res.stream()); archive.append(stream.Readable.fromWeb(file), { name: createFileName(asset) }); }; diff --git a/src/modules/backupRestore/backupRestoreEntities/entityDefinition.ts b/src/modules/backupRestore/backupRestoreEntities/entityDefinition.ts index 98332da1..26220172 100644 --- a/src/modules/backupRestore/backupRestoreEntities/entityDefinition.ts +++ b/src/modules/backupRestore/backupRestoreEntities/entityDefinition.ts @@ -11,7 +11,12 @@ export type EntityBackupDefinition = Readonly<{ displayName: string; fetchEntities: (client: ManagementClient) => Promise; serializeEntities: (entities: T) => string; - addOtherFiles?: (loadedEntities: T, archive: archiver.Archiver, logOptions: LogOptions) => Promise; + addOtherFiles?: ( + loadedEntities: T, + archive: archiver.Archiver, + logOptions: LogOptions, + secureAssetDeliveryKey: string | undefined, + ) => Promise; }>; export type EntityRestoreDefinition = Readonly<{ @@ -29,11 +34,7 @@ export type EntityRestoreDefinition = Readonly<{ export type EntityCleanDefinition = Readonly<{ name: string; - cleanEntities: ( - client: ManagementClient, - entities: T, - logOptions: LogOptions, - ) => Promise; + cleanEntities: (client: ManagementClient, entities: T, logOptions: LogOptions) => Promise; }>; export type DependentRestoreAction = Readonly<{