Utilizzo dell' IBM Cloud® Object Storage SDK for Node.js v2

Utilizza l' IBM Cloud® Object StorageSDK for Node.jsv2 per installare l'SDK, creare client e gestire bucket e oggetti con API moderne e IAM.

Il sito IBM Cloud® Object Storage SDK for Node.js v2 offre funzionalità che consentono di sfruttare al meglio IBM Cloud Object Storage.

L' IBM Cloud Object Storage SDK for Node.js v2 è completo e offre numerose funzionalità e capacità che esulano dall'ambito e dallo spazio di questa guida. Per una documentazione dettagliata sulle classi e sui metodi, consultare la documentazione di riferimento dell'API di Node.js. Il codice sorgente è disponibile nel repository GitHub.

Novità della versio v2

IBM Cloud Object Storage SDK for Node.js v2 è una versione modernizzata basata sull'architettura dell'SDK AWS v3, che apporta miglioramenti significativi:

  • Architettura modulare- Importa solo i comandi e i client di cui hai bisogno
  • Progettazione "Promise-first " - Supporto nativo di async/await con una gestione degli errori più chiara
  • Dimensioni dei pacchetti più ridotte: i moduli "tree-shakeable" riducono le dimensioni dell'applicazione
  • JavaScript e moderna- Sfrutta le funzionalità di ES6+ e il supporto di TypeScript
  • Stack middleware- Pipeline estensibile di richiesta/risposta
  • Migliore gestione degli errori- Tipi di errore strutturati con informazioni dettagliate

Gli sviluppatori che intendono effettuare la migrazione da v1 sono invitati a consultare la Guida alla migrazione.

Ottenimento dell'SDK

Il metodo consigliato per installare l' IBM Cloud Object Storage SDK for Node.js consiste nell'utilizzare il gestore di pacchetti npm per Node.js. È sufficiente digitare quanto segue in una finestra di terminale:

npm install ibm-cos-sdk-v2

Prerequisiti

  • Node.js 18 o versioni successive- L'SDK richiede almeno la versione 18 di Node.js o una versione successiva.
  • Un'istanza di IBM Cloud Object Storage
  • Una chiave API proveniente da IBM Cloud Identity and Access Management con almeno i permessi Writer
  • L'ID dell'istanza di Object Storage con cui stai lavorando
  • Endpoint per l'acquisizione dei token
  • Endpoint del servizio

Questi valori sono disponibili nella console IBM Cloud generando una "credenziale di servizio".

Importa pacchetti

Dopo aver installato l'SDK, è necessario importare i pacchetti necessari nelle applicazioni Node.js per poter utilizzare l'SDK, come illustrato nell'esempio seguente:

CommonJS:

const { S3Client } = require('ibm-cos-sdk-v2');
const {
  CreateBucketCommand,
  ListBucketsCommand,
  PutObjectCommand,
  GetObjectCommand
} = require('ibm-cos-sdk-v2');

Moduli ES / TypeScript:

import { S3Client } from 'ibm-cos-sdk-v2';
import {
  CreateBucketCommand,
  ListBucketsCommand,
  PutObjectCommand,
  GetObjectCommand
} from 'ibm-cos-sdk-v2';

Riferimenti SDK

Corsi fondamentali

  • S3Client- Client principale per l'interazione con IBM Cloud Object Storage
  • Classi di comando- Ogni operazione ha una classe di comando corrispondente (ad esempio, PutObjectCommand, GetObjectCommand)

Configurazione

  • S3Client costruttore- Crea un nuovo client S3 con opzioni di configurazione
  • regione- Imposta la regione per il cliente
  • endpoint- Imposta l'endpoint del servizio URL
  • credenziali- Imposta le credenziali di autenticazione

Creazione di un cliente e acquisizione delle credenziali del servizio

Per stabilire una connessione a IBM Cloud Object Storage, un client viene creato e configurato fornendo le informazioni delle credenziali (chiave API e ID istanza del servizio). Questi valori possono anche essere derivati automaticamente da un file di credenziali o dalle variabili di ambiente.

Le credenziali possono essere trovate creando una credenziale del servizio o tramite la CLI.

Utilizzo dell'autenticazione IAM di IBM

L'esempio seguente illustra come creare un client utilizzando l'autenticazione IAM di IBM con una chiave API:

CommonJS:

const { S3Client } = require('ibm-cos-sdk-v2');
// Initialize client
const client = new S3Client({
  endpoint: 'https://s3.us-south.cloud-object-storage.appdomain.cloud',
  region: 'us-south',
  credentials: {
    apiKey: '<API_KEY>',
    serviceInstanceId: '<SERVICE_INSTANCE_ID>'
  }
});

TypeScript:

import { S3Client } from 'ibm-cos-sdk-v2';
const client = new S3Client({
  endpoint: 'https://s3.us-south.cloud-object-storage.appdomain.cloud',
  region: 'us-south',
  credentials: {
    apiKey: '<API_KEY>',
    serviceInstanceId: '<SERVICE_INSTANCE_ID>'
  }
});

Le opzioni di configurazione richieste sono:

  • endpoint- L' URL dell'endpoint relativo alla regione del tuo bucket Object Storage
  • region- La regione in cui si trova il tuo bucket
  • credentials.apiKey- La tua chiave API di IBM Cloud con le autorizzazioni appropriate
  • credentials.serviceInstanceId- Il CRN (Cloud Resource Name) della tua istanza Object Storage

Esempi di codici

Gli esempi che seguono presuppongono che abbiate già creato un cliente come illustrato nella sezione precedente.

Creazione di un bucket

Crea un nuovo bucket nella regione specificata utilizzando un’istruzione LocationConstraint nel blocco CreateBucketConfiguration .

const { CreateBucketCommand } = require('ibm-cos-sdk-v2');
const command = new CreateBucketCommand({
  Bucket: 'my-new-bucket',
  CreateBucketConfiguration: {
    LocationConstraint: 'us-south-standard'
  }
});
try {
  const response = await client.send(command);
  console.log('Bucket created successfully');
} catch (err) {
  console.error('Error creating bucket:', err);
}

Elenco dei bucket disponibili

Restituisce tutti i bucket di proprietà dell'account autenticato, indicando il nome e la data di creazione di ciascun bucket.

const { ListBucketsCommand } = require('ibm-cos-sdk-v2');
try {
  const command = new ListBucketsCommand({});
  const response = await client.send(command);
  console.log('Buckets:');
  if (response.Buckets && response.Buckets.length > 0) {
    response.Buckets.forEach(bucket => {
      console.log(` - ${bucket.Name} (created: ${bucket.CreationDate})`);
    });
  } else {
    console.log(' No buckets found');
  }
} catch (err) {
  console.error('Failed to list buckets:', err);
}

Elenco dei bucket con informazioni dettagliate

ListBucketsExtended è un'operazione specifica di " IBM Cloud Object Storage " che restituisce metadati aggiuntivi per ogni bucket (vincolo di posizione e data di creazione) rispetto all'operazione standard " ListBuckets ":

const { ListBucketsExtendedCommand } = require('ibm-cos-sdk-v2');
const command = new ListBucketsExtendedCommand({
  IBMServiceInstanceId: '<SERVICE_INSTANCE_ID>',
  Prefix: 'my-bucket-prefix',
  MaxKeys: 100
});
try {
  const response = await client.send(command);
  console.log('Extended Bucket Information:');
  if (response.Buckets && response.Buckets.length > 0) {
    response.Buckets.forEach(bucket => {
      console.log(` Bucket: ${bucket.Name}`);
      console.log(` Location: ${bucket.LocationConstraint}`);
      console.log(` Created: ${bucket.CreationDate}`);
    });
  } else {
    console.log(' No buckets found');
  }
} catch (err) {
  console.error('Failed to list buckets:', err);
}

Recupero della posizione di un bucket

Recupera le informazioni relative a " LocationConstraint " (regione e classe di archiviazione) del bucket specificato.

const { GetBucketLocationCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new GetBucketLocationCommand({
  Bucket: bucketName
});
try {
  const response = await client.send(command);
  console.log(`Bucket '${bucketName}' is located in: ${response.LocationConstraint}`);
} catch (err) {
  console.error('Failed to get bucket location:', err);
}

Eliminazione di un bucket

Rimuove definitivamente un secchio vuoto. Prima di poter procedere alla cancellazione, il bucket non deve contenere alcun oggetto.

const { DeleteBucketCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket-to-delete';
const command = new DeleteBucketCommand({
  Bucket: bucketName
});
try {
  await client.send(command);
  console.log(`Bucket '${bucketName}' deleted successfully`);
} catch (err) {
  console.error('Failed to delete bucket:', err);
}

Nota: un bucket deve essere vuoto prima di poter essere eliminato.

Caricamento di un oggetto in un bucket

Carica un oggetto (stringa, buffer o flusso) in un bucket con la chiave specificata. La risposta include l' ETag dell'oggetto.

const { PutObjectCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'my-object.txt';
const content = 'Hello, IBM Cloud Object Storage!';
const command = new PutObjectCommand({
  Bucket: bucketName,
  Key: objectKey,
  Body: content
});
try {
  const response = await client.send(command);
  console.log(`Object '${objectKey}' uploaded successfully`);
  console.log(`ETag: ${response.ETag}`);
} catch (err) {
  console.error('Failed to upload object:', err);
}

Scaricare un oggetto da un bucket

Scarica un oggetto da un bucket. In v2, il corpo della risposta è uno stream leggibile che deve essere consumato (ad esempio, con transformToString()) o reindirizzato tramite pipe.

const { GetObjectCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'my-object.txt';
const command = new GetObjectCommand({
  Bucket: bucketName,
  Key: objectKey
});
try {
  const response = await client.send(command);
  // Convert stream to buffer
  const chunks = [];
  for await (const chunk of response.Body) {
    chunks.push(chunk);
  }
  const buffer = Buffer.concat(chunks);
  console.log(`Object '${objectKey}' downloaded successfully`);
  console.log(`Content-Type: ${response.ContentType}`);
  console.log(`Content-Length: ${response.ContentLength} bytes`);
  console.log(`Size: ${buffer.length} bytes`);
} catch (err) {
  console.error('Failed to download object:', err);
}

Elenco degli oggetti in un bucket

const { ListObjectsV2Command } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new ListObjectsV2Command({
  Bucket: bucketName,
  MaxKeys: 1000
});
try {
  const response = await client.send(command);
  console.log(`Objects in bucket '${bucketName}':`);
  if (response.Contents && response.Contents.length > 0) {
    response.Contents.forEach(object => {
      console.log(` - ${object.Key} (size: ${object.Size} bytes, modified: ${object.LastModified})`);
    });
    console.log(`\nTotal objects: ${response.Contents.length}`);
  } else {
    console.log(' No objects found');
  }
} catch (err) {
  console.error('Failed to list objects:', err);
}

Copia di un oggetto

Copia un oggetto esistente in una nuova chiave o in un nuovo bucket, interamente sul lato server. Non vengono trasferiti dati tramite il client. La risposta include l'ETag della copia.

const { CopyObjectCommand } = require('ibm-cos-sdk-v2');
const sourceBucket = 'source-bucket';
const sourceKey = 'source-object.txt';
const destinationBucket = 'destination-bucket';
const destinationKey = 'destination-object.txt';
// CopySource format: source-bucket/source-key
const copySource = `${sourceBucket}/${sourceKey}`;
const command = new CopyObjectCommand({
  Bucket: destinationBucket,
  Key: destinationKey,
  CopySource: copySource
});
try {
  const response = await client.send(command);
  console.log('Object copied successfully');
  if (response.CopyObjectResult) {
    console.log(`ETag: ${response.CopyObjectResult.ETag}`);
  }
} catch (err) {
  console.error('Failed to copy object:', err);
}

Eliminazione di un oggetto

Elimina un singolo oggetto in base alla chiave. Su un bucket con gestione delle versioni, questa operazione crea un indicatore di eliminazione anziché rimuovere definitivamente i dati.

const { DeleteObjectCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'object-to-delete.txt';
const command = new DeleteObjectCommand({
  Bucket: bucketName,
  Key: objectKey
});
try {
  await client.send(command);
  console.log(`Object '${objectKey}' deleted successfully`);
} catch (err) {
  console.error('Failed to delete object:', err);
}

Eliminazione di più oggetti

Elimina fino a 1.000 oggetti in una singola richiesta. La risposta elenca le chiavi eliminate correttamente ed eventuali errori relativi alle chiavi che non è stato possibile eliminare.

const { DeleteObjectsCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectsToDelete = [
  'object1.txt',
  'object2.txt',
  'object3.txt'
];
// Build delete request
const objects = objectsToDelete.map(key => ({ Key: key }));
const command = new DeleteObjectsCommand({
  Bucket: bucketName,
  Delete: {
    Objects: objects,
    Quiet: false
  }
});
try {
  const response = await client.send(command);
  console.log('Delete operation completed');
  if (response.Deleted && response.Deleted.length > 0) {
    console.log(`Successfully deleted ${response.Deleted.length} object(s):`);
    response.Deleted.forEach(deleted => {
      console.log(` - ${deleted.Key}`);
    });
  }
  if (response.Errors && response.Errors.length > 0) {
    console.log(`\nFailed to delete ${response.Errors.length} object(s):`);
    response.Errors.forEach(error => {
      console.log(` - ${error.Key}: ${error.Message}`);
    });
  }
} catch (err) {
  console.error('Failed to delete objects:', err);
}

Recupero dei metadati di un oggetto (HEAD)

Recupera i metadati di un oggetto (tipo di contenuto, dimensione, ETag e metadati personalizzati) senza scaricare il corpo dell'oggetto.

const { HeadObjectCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'my-object.txt';
const command = new HeadObjectCommand({
  Bucket: bucketName,
  Key: objectKey
});
try {
  const response = await client.send(command);
  console.log(`Object Metadata for '${objectKey}':`);
  console.log(` Content-Type: ${response.ContentType}`);
  console.log(` Content-Length: ${response.ContentLength} bytes`);
  console.log(` ETag: ${response.ETag}`);
  console.log(` Last-Modified: ${response.LastModified}`);
  if (response.Metadata && Object.keys(response.Metadata).length > 0) {
    console.log(' Custom Metadata:');
    for (const [key, value] of Object.entries(response.Metadata)) {
      console.log(`  ${key}: ${value}`);
    }
  }
} catch (err) {
  console.error('Failed to get object metadata:', err);
}

Utilizzo di caricamenti in più parti

Per gli oggetti di grandi dimensioni, il caricamento in più parti garantisce una maggiore velocità di trasmissione e la possibilità di riprendere il caricamento. Ogni parte deve avere una dimensione minima di 5 MB (ad eccezione dell'ultima parte).

Caricamento manuale di file multipli:

Il flusso manuale suddivide un file di grandi dimensioni in blocchi di dimensione fissa, carica ciascun blocco come parte numerata utilizzando UploadPartCommand e infine completa il caricamento con CompleteMultipartUploadCommand. Questo approccio ti offre il pieno controllo sulle dimensioni dei file, sulla logica di riprova e sui caricamenti in parallelo. Se un caricamento non va a buon fine, AbortMultipartUploadCommand provvede a rimuovere eventuali parti già caricate. Il caricamento viene avviato tramite CreateMultipartUploadCommand.

const {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
  AbortMultipartUploadCommand
} = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'large-object.dat';
try {
  // Step 1: Initiate multipart upload
  const createCommand = new CreateMultipartUploadCommand({
    Bucket: bucketName,
    Key: objectKey
  });
  const createResponse = await client.send(createCommand);
  const uploadId = createResponse.UploadId;
  console.log(`Multipart upload initiated with ID: ${uploadId}`);
  // Step 2: Upload parts (minimum 5MB per part except last)
  const completedParts = [];
  const minPartSize = 5 * 1024 * 1024; // 5MB
  // Create sample parts
  const parts = [
    'A'.repeat(minPartSize),
    'B'.repeat(minPartSize)
  ];
  for (let i = 0; i < parts.length; i++) {
    const partNumber = i + 1;
    const uploadPartCommand = new UploadPartCommand({
      Bucket: bucketName,
      Key: objectKey,
      PartNumber: partNumber,
      UploadId: uploadId,
      Body: parts[i]
    });
    try {
      const uploadResponse = await client.send(uploadPartCommand);
      completedParts.push({
        ETag: uploadResponse.ETag,
        PartNumber: partNumber
      });
      console.log(`Part ${partNumber} uploaded (ETag: ${uploadResponse.ETag})`);
    } catch (err) {
      // Abort multipart upload on error
      const abortCommand = new AbortMultipartUploadCommand({
        Bucket: bucketName,
        Key: objectKey,
        UploadId: uploadId
      });
      await client.send(abortCommand);
      throw err;
    }
  }
  // Step 3: Complete multipart upload
  const completeCommand = new CompleteMultipartUploadCommand({
    Bucket: bucketName,
    Key: objectKey,
    UploadId: uploadId,
    MultipartUpload: {
      Parts: completedParts
    }
  });
  const completeResponse = await client.send(completeCommand);
  console.log('Multipart upload completed successfully');
  console.log(`Location: ${completeResponse.Location}`);
  console.log(`ETag: ${completeResponse.ETag}`);
} catch (err) {
  console.error('Failed to complete multipart upload:', err);
}

Utilizzo di Upload Manager (consigliato):

Per semplificare il caricamento di file in più parti, utilizza il pacchetto @ibm-cos/lib-storage. L'helper di alto livello Upload racchiude il flusso manuale in tre fasi (CreateMultipartUpload, UploadPart, CompleteMultipartUpload), suddivide automaticamente il flusso in parti, carica le parti in modo concorrente ed emette eventi di avanzamento.

Il gestore " Upload " è una funzionalità di " v2-only ". " v1 " utilizzava " s3.upload() " e " ManagedUpload " del pacchetto " ibm-cos-sdk ", che non sono compatibili con l'SDK di " v2 ".

const { Upload } = require('@ibm-cos/lib-storage');
const { S3Client } = require('ibm-cos-sdk-v2');
const fs = require('fs');
const fileStream = fs.createReadStream('large-file.bin');
const upload = new Upload({
  client: client,
  params: {
    Bucket: 'my-bucket',
    Key: 'large-file.bin',
    Body: fileStream
  },
  queueSize: 4, // Concurrent parts
  partSize: 5 * 1024 * 1024, // 5MB parts
  leavePartsOnError: false
});
// Track progress
upload.on('httpUploadProgress', (progress) => {
  console.log('Upload progress:', progress);
});
try {
  const result = await upload.done();
  console.log('Upload completed:', result);
} catch (err) {
  console.error('Upload failed:', err);
}

Elenco dei caricamenti in più parti

Elenca tutti i caricamenti in più parti in corso per un bucket. I caricamenti incompleti occupano spazio di archiviazione e comportano costi aggiuntivi.

const { ListMultipartUploadsCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new ListMultipartUploadsCommand({
  Bucket: bucketName
});
try {
  const response = await client.send(command);
  console.log(`In-progress multipart uploads in bucket '${bucketName}':`);
  if (response.Uploads && response.Uploads.length > 0) {
    response.Uploads.forEach(upload => {
      console.log(` Key: ${upload.Key}`);
      console.log(` Upload ID: ${upload.UploadId}`);
      console.log(` Initiated: ${upload.Initiated}`);
    });
  } else {
    console.log(' No in-progress uploads found');
  }
} catch (err) {
  console.error('Failed to list multipart uploads:', err);
}

Elenco delle parti di un upload composto da più parti

Elenca tutti i file caricati relativi a un caricamento multiparte in corso. Utile per verificare lo stato di avanzamento o per raccogliere gli ETag prima di completare il caricamento.

const { ListPartsCommand } = require('ibm-cos-sdk-v2');
const command = new ListPartsCommand({
  Bucket: 'my-bucket',
  Key: 'my-large-object',
  UploadId: 'YOUR_UPLOAD_ID_HERE'
});
try {
  const response = await client.send(command);
  console.log('Parts listed successfully');
  if (response.Parts && response.Parts.length > 0) {
    response.Parts.forEach(p =>
      console.log(' - Part', p.PartNumber, '| ETag:', p.ETag, '| Size:', p.Size, 'bytes')
    );
  } else {
    console.log('No parts found.');
  }
} catch (err) {
  console.error('Error listing parts:', err);
}

Copia di una parte da un oggetto esistente

Carica una parte copiandola da un oggetto esistente. Utilizzare questa opzione invece di caricare byte grezzi quando i dati di origine sono già presenti in Object Storage.

const { UploadPartCopyCommand } = require('ibm-cos-sdk-v2');
const command = new UploadPartCopyCommand({
  Bucket: 'my-bucket',
  Key: 'my-large-object',
  UploadId: 'YOUR_UPLOAD_ID_HERE',
  PartNumber: 1,
  CopySource: 'my-bucket/source-object-key'
});
try {
  const response = await client.send(command);
  console.log('Part copy uploaded successfully');
  console.log('ETag:', response.CopyPartResult?.ETag);
} catch (err) {
  console.error('Error uploading part copy:', err);
}

Configurazione del ciclo di vita di un bucket

Le politiche di archiviazione consentono di trasferire automaticamente gli oggetti nelle classi di archiviazione dopo un periodo di tempo specificato.

L'esempio seguente definisce una regola che elimina gli oggetti presenti sotto il prefisso logs/ dopo 30 giorni. In v2, ogni regola deve utilizzare un blocco Filter (ad esempio, Filter: { Prefix: 'logs/' }) anziché la proprietà di primo livello Prefix utilizzata in v1. L'API rifiuta le regole che utilizzano ancora la forma piatta v1.

const { PutBucketLifecycleConfigurationCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
// Configure lifecycle rule to expire objects after 30 days
const command = new PutBucketLifecycleConfigurationCommand({
  Bucket: bucketName,
  LifecycleConfiguration: {
    Rules: [
      {
        Id: 'delete-old-logs',
        Status: 'Enabled',
        Filter: {
          Prefix: 'logs/',
        },
        Expiration: {
          Days: 30,
        },
      },
      {
        Id: 'cleanup-multipart-uploads',
        Status: 'Enabled',
        Filter: {
          Prefix: '',
        },
        AbortIncompleteMultipartUpload: {
          DaysAfterInitiation: 7,
        },
      },
    ]
  }
});
try {
  await client.send(command);
  console.log(`Lifecycle configuration set for bucket '${bucketName}'`);
} catch (err) {
  console.error('Failed to set lifecycle configuration:', err);
}

Ottenere una configurazione del ciclo di vita di un bucket

Recupera la configurazione del ciclo di vita di un bucket, restituendo tutte le regole sotto forma di array di oggetti regola.

const { GetBucketLifecycleConfigurationCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new GetBucketLifecycleConfigurationCommand({
  Bucket: bucketName
});
try {
  const response = await client.send(command);
  console.log(`Lifecycle rules for bucket '${bucketName}':`);
  if (response.Rules && response.Rules.length > 0) {
    response.Rules.forEach(rule => {
      console.log(` Rule ID: ${rule.ID}`);
      console.log(` Status: ${rule.Status}`);
      if (rule.Transitions && rule.Transitions.length > 0) {
        rule.Transitions.forEach(transition => {
          console.log(` Transition to ${transition.StorageClass} after ${transition.Days} days`);
        });
      }
    });
  } else {
    console.log(' No lifecycle rules found');
  }
} catch (err) {
  console.error('Failed to get lifecycle configuration:', err);
}

Abilitazione del controllo delle versioni dei bucket

Imposta " Status: 'Enabled' " per attivare il controllo delle versioni per il bucket. Una volta abilitata la gestione delle versioni, ogni operazione di sovrascrittura crea una nuova versione anziché sostituire l'oggetto. Utilizzare " 'Suspended' " per sospendere il controllo delle versioni. " 'Disabled' " non è un valore valido.

const { PutBucketVersioningCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new PutBucketVersioningCommand({
  Bucket: bucketName,
  VersioningConfiguration: {
    // Valid values: 'Enabled' | 'Suspended'
    Status: 'Enabled',
  },
});
try {
  await client.send(command);
  console.log(`Versioning enabled for bucket '${bucketName}'`);
} catch (err) {
  console.error('Failed to enable versioning:', err);
}

Elenco delle versioni degli oggetti

Restituisce tutte le versioni e gli indicatori di eliminazione per ogni oggetto presente in un bucket con gestione delle versioni.

const { ListObjectVersionsCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const command = new ListObjectVersionsCommand({
  Bucket: bucketName
});
try {
  const response = await client.send(command);
  console.log(`Object versions in bucket '${bucketName}':`);
  if (response.Versions && response.Versions.length > 0) {
    response.Versions.forEach(version => {
      console.log(` Key: ${version.Key}`);
      console.log(` Version ID: ${version.VersionId}`);
      console.log(` Is Latest: ${version.IsLatest}`);
      console.log(` Last Modified: ${version.LastModified}`);
    });
  } else {
    console.log(' No versions found');
  }
} catch (err) {
  console.error('Failed to list object versions:', err);
}

Impostazione della configurazione di CORS

Imposta le regole " CORS " su un bucket, definendo le origini, i metodi, le intestazioni consentite, le intestazioni esposte e la durata della cache preflight. Questa operazione sostituisce qualsiasi configurazione esistente di CORS.

const { PutBucketCorsCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
// Set CORS configuration
const command = new PutBucketCorsCommand({
  Bucket: bucketName,
  CORSConfiguration: {
    CORSRules: [
      {
        AllowedHeaders: ['*'],
        AllowedMethods: ['GET', 'PUT', 'POST', 'DELETE'],
        AllowedOrigins: ['https://example.com'],
        ExposeHeaders: ['ETag'],
        MaxAgeSeconds: 3000
      }
    ]
  }
});
try {
  await client.send(command);
  console.log(`CORS configuration set for bucket '${bucketName}'`);
} catch (err) {
  console.error('Failed to set CORS configuration:', err);
}

Impostazione dell'assegnazione di tag agli oggetti

Applica una serie di tag chiave-valore a un oggetto.

const { PutObjectTaggingCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'my-object.txt';
// Set object tags
const command = new PutObjectTaggingCommand({
  Bucket: bucketName,
  Key: objectKey,
  Tagging: {
    TagSet: [
      {
        Key: 'Environment',
        Value: 'Development'
      },
      {
        Key: 'Owner',
        Value: 'TeamA'
      }
    ]
  }
});
try {
  await client.send(command);
  console.log(`Object tagging set successfully for '${objectKey}'`);
} catch (err) {
  console.error('Failed to set object tags:', err);
}

Ottenere i tag degli oggetti

Recupera l'insieme di tag associato a un oggetto.

const { GetObjectTaggingCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-bucket';
const objectKey = 'my-object.txt';
const command = new GetObjectTaggingCommand({
  Bucket: bucketName,
  Key: objectKey
});
try {
  const response = await client.send(command);
  console.log(`Tags for object '${objectKey}':`);
  if (response.TagSet && response.TagSet.length > 0) {
    response.TagSet.forEach(tag => {
      console.log(` ${tag.Key}: ${tag.Value}`);
    });
  } else {
    console.log(' No tags found');
  }
} catch (err) {
  console.error('Failed to get object tags:', err);
}

Ripristino di un oggetto archiviato

Gli oggetti presenti nelle classi di archiviazione devono essere ripristinati prima di poter essere consultati:

const command = new RestoreObjectCommand({
  Bucket: bucketName,
  Key: objectKey,
  RestoreRequest: {
    Days: 7,
    GlacierJobParameters: {
      Tier: 'Bulk',
    },
  },
});
try {
  await client.send(command);
  console.log('Object restore initiated successfully');
  console.log(
    'Retrieval time depends on storage class: Vault typically 1-5 hours, Cold Vault typically 5-12 hours.'
  );
} catch (err) {
  console.error('Failed to restore object:', err);
}

Nota: IBM Cloud Object Storage supporta esclusivamente il livello di recupero " Bulk " per il ripristino di oggetti dalle classi di archiviazione "Vault" e "Cold Vault".

Impostazione della durata di conservazione degli oggetti

Imposta un periodo di conservazione per un oggetto specifico, impedendone la cancellazione o la sovrascrittura fino alla data di scadenza.

Modalità di governance: gli utenti con autorizzazioni IAM specifiche possono eliminare le versioni degli oggetti durante il periodo di conservazione.

Modalità di conformità: nessun utente può eliminare le versioni degli oggetti durante il periodo di conservazione.

const { PutObjectRetentionCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-protected-bucket';
const objectKey = 'important-document.pdf';
// Set retention until a specific date
const retainUntil = new Date();
retainUntil.setDate(retainUntil.getDate() + 30);
const command = new PutObjectRetentionCommand({
  Bucket: bucketName,
  Key: objectKey,
  Retention: {
    Mode: 'COMPLIANCE',
    RetainUntilDate: retainUntil,
  },
});
try {
  await client.send(command);
  console.log('Object retention set successfully');
  console.log('RetainUntil:', retainUntil.toISOString());
} catch (err) {
  console.error('Error:', err.message);
}

Ottenere la ritenzione degli oggetti

Legge la modalità di conservazione e la data di scadenza attualmente impostate su un oggetto specifico.

const { GetObjectRetentionCommand } = require('ibm-cos-sdk-v2');
const bucketName = 'my-protected-bucket';
const objectKey = 'important-document.pdf';
const command = new GetObjectRetentionCommand({
  Bucket: bucketName,
  Key: objectKey
});
try {
  const response = await client.send(command);
  console.log('Object retention retrieved successfully');
  console.log('Mode:', response.Retention?.Mode);
  console.log('RetainUntilDate:', response.Retention?.RetainUntilDate);
} catch (err) {
  console.error('Error:', err.message);
}

Creazione di un bucket con Object Lock ( S3 )

S3 Object Lock impedisce che gli oggetti vengano eliminati o sovrascritti per un periodo di conservazione prestabilito o a tempo indeterminato. Object Lock deve essere abilitato al momento della creazione del bucket: non è possibile aggiungerlo a un bucket esistente.

Modalità di governance: gli utenti con autorizzazioni IAM specifiche possono eliminare le versioni degli oggetti durante il periodo di conservazione.

Modalità di conformità: nessun utente può eliminare le versioni degli oggetti durante il periodo di conservazione.

Questa sezione tratta di “ S3-compatible ” e “Object Lock”. Per informazioni sulla protezione WORM specifica per COS ( IBM ), consultare le sezioni " Impostazione della protezione dei bucket(WORM) " e " Gestione dei blocchi legali ".

Object Lock di S3 non era supportato nella versione v1 dell'SDK di IBM Cloud Object Storage. Tutte le operazioni relative a Object Lock di S3 descritte in questo argomento sono disponibili all'indirizzo v2-only.

Questo esempio crea un bucket con la funzione Object Lock abilitata e imposta immediatamente una regola di conservazione predefinita di 30 giorni per gli oggetti ( GOVERNANCE ), in modo che tutti i nuovi oggetti siano protetti automaticamente.

const {
  CreateBucketCommand,
  PutObjectLockConfigurationCommand
} = require('ibm-cos-sdk-v2');
// Step 1: Create bucket with Object Lock enabled
const createCommand = new CreateBucketCommand({
  Bucket: 'my-locked-bucket',
  ObjectLockEnabledForBucket: true
});
try {
  await client.send(createCommand);
  console.log('Bucket created with Object Lock enabled');
} catch (err) {
  console.error('Error creating bucket:', err.message);
}
// Step 2: Set default retention rule
const lockConfigCommand = new PutObjectLockConfigurationCommand({
  Bucket: 'my-locked-bucket',
  ObjectLockConfiguration: {
    ObjectLockEnabled: 'Enabled',
    Rule: {
      DefaultRetention: {
        Mode: 'GOVERNANCE',
        Days: 30
      }
    }
  }
});
try {
  await client.send(lockConfigCommand);
  console.log('Default Object Lock configuration set successfully');
} catch (err) {
  console.error('Error setting lock config:', err.message);
}

Impostazione della configurazione di Object Lock

Imposta o aggiorna la regola di conservazione predefinita applicata a ogni nuovo oggetto caricato in un bucket.

const { PutObjectLockConfigurationCommand } = require('ibm-cos-sdk-v2');
const command = new PutObjectLockConfigurationCommand({
  Bucket: 'my-object-lock-bucket',
  ObjectLockConfiguration: {
    ObjectLockEnabled: 'Enabled',
    Rule: {
      DefaultRetention: {
        Mode: 'COMPLIANCE',
        Days: 2
      }
    }
  }
});
try {
  await client.send(command);
  console.log('Object lock configuration set successfully');
} catch (err) {
  console.error('Error:', err.message);
}

Ottenere la configurazione di Object Lock

Recupera lo stato di abilitazione dell'Object Lock del bucket e la regola di conservazione predefinita.

const { GetObjectLockConfigurationCommand } = require('ibm-cos-sdk-v2');
const command = new GetObjectLockConfigurationCommand({
  Bucket: 'my-object-lock-bucket'
});
try {
  const response = await client.send(command);
  console.log('Object lock configuration retrieved successfully');
  console.log('ObjectLockEnabled:', response.ObjectLockConfiguration?.ObjectLockEnabled);
  console.log('Rule:', JSON.stringify(response.ObjectLockConfiguration?.Rule, null, 2));
} catch (err) {
  console.error('Error:', err.message);
}

Verifica dell'esistenza di un bucket (HEAD)

Verifica se un bucket esiste e se il chiamante dispone dei permessi necessari per accedervi, senza restituire alcun contenuto del bucket.

const { HeadBucketCommand } = require('ibm-cos-sdk-v2');
const command = new HeadBucketCommand({
  Bucket: 'my-bucket'
});
try {
  await client.send(command);
  console.log('Bucket exists');
} catch (err) {
  if (err.name === 'NotFound') {
    console.log('Bucket does not exist');
  } else {
    console.error('Error checking bucket:', err);
  }
}

Caricamento in streaming da un file

Apre un file come flusso leggibile e lo passa direttamente come parametro Body di una chiamata PutObjectCommand , evitando di caricare l'intero file in memoria.

const fs = require('fs');
const { PutObjectCommand } = require('ibm-cos-sdk-v2');
const fileStream = fs.createReadStream('large-file.bin');
const command = new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'large-file.bin',
  Body: fileStream
});
try {
  const response = await client.send(command);
  console.log('File uploaded successfully');
} catch (err) {
  console.error('Error uploading file:', err);
}

Download in streaming su un file

Recupera un oggetto come flusso e lo reindirizza direttamente a un flusso di file scrivibile. In v2, response.Body è un flusso leggibile che può essere incanalato o messo in attesa.

const fs = require('fs');
const { GetObjectCommand } = require('ibm-cos-sdk-v2');
const command = new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'large-file.bin'
});
try {
  const response = await client.send(command);
  const fileStream = fs.createWriteStream('downloaded-file.bin');
  response.Body.pipe(fileStream);
  await new Promise((resolve, reject) => {
    fileStream.on('finish', resolve);
    fileStream.on('error', reject);
    response.Body.on('error', reject);
  });
  console.log('File downloaded successfully');
} catch (err) {
  console.error('Error downloading file:', err);
}

Elenco di tutti gli oggetti con impaginazione

L'SDK di v2 fornisce paginatori integrati per le operazioni che restituiscono risultati troncati.

Utilizzo di un paginatore (consigliato):

const { paginateListObjectsV2 } = require('ibm-cos-sdk-v2');
async function listAllObjects(bucket, prefix) {
  const allObjects = [];
  const paginator = paginateListObjectsV2(
    { client: client, pageSize: 1000 },
    { Bucket: bucket, Prefix: prefix }
  );
  try {
    for await (const page of paginator) {
      if (page.Contents) {
        allObjects.push(...page.Contents);
      }
    }
    console.log('Total objects:', allObjects.length);
    return allObjects;
  } catch (err) {
    console.error('Error listing objects:', err);
    throw err;
  }
}

Impaginazione manuale:

const { ListObjectsV2Command } = require('ibm-cos-sdk-v2');
async function listAllObjects(bucket, prefix) {
  const allObjects = [];
  let continuationToken = undefined;
  do {
    const command = new ListObjectsV2Command({
      Bucket: bucket,
      Prefix: prefix,
      ContinuationToken: continuationToken
    });
    const response = await client.send(command);
    if (response.Contents) {
      allObjects.push(...response.Contents);
    }
    continuationToken = response.NextContinuationToken;
  } while (continuationToken);
  console.log('Total objects:', allObjects.length);
  return allObjects;
}

Generazione di URL pre-firmati

Gli URL pre-firmati consentono un accesso temporaneo e non autenticato agli oggetti. Per prima cosa, installa il pacchetto presigner:

npm install @ibm-cos/s3-request-presigner

GET pre-firmato URL (download):

Crea un oggetto di tipo GetObjectCommand e lo passa a getSignedUrl , contenuto nel pacchetto presigner, per generare un oggetto di tipo URL a durata limitata (valido per 1 ora) che concede l'accesso in lettura non autenticato all'oggetto specificato.

const { GetObjectCommand } = require('ibm-cos-sdk-v2');
const { getSignedUrl } = require('@ibm-cos/s3-request-presigner');
const command = new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt'
});
try {
  const url = await getSignedUrl(client, command, { expiresIn: 3600 });
  console.log('Presigned URL:', url);
} catch (err) {
  console.error('Error generating presigned URL:', err);
}

PUT pre-firmato URL (caricamento):

Crea un oggetto PutObjectCommand e lo passa a getSignedUrl per generare un URL di upload pre-autenticato URL, valido per 1 ora e limitato a un tipo di contenuto specifico. Un client può utilizzare l' URL per caricare un oggetto direttamente su IBM Cloud Object Storage senza credenziali SDK.

const { PutObjectCommand } = require('ibm-cos-sdk-v2');
const { getSignedUrl } = require('@ibm-cos/s3-request-presigner');
const command = new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'upload-object.txt',
  ContentType: 'text/plain'
});
try {
  const url = await getSignedUrl(client, command, { expiresIn: 3600 });
  console.log('Presigned PUT URL:', url);
} catch (err) {
  console.error('Error generating presigned URL:', err);
}

Ottenere una configurazion CORS

Recupera la configurazione corrente di “ CORS ” per un bucket, restituendo un array di oggetti “ CORSRules ” che descrivono l’accesso cross-origin consentito.

const { GetBucketCorsCommand } = require('ibm-cos-sdk-v2');
const command = new GetBucketCorsCommand({
  Bucket: 'my-bucket'
});
try {
  const response = await client.send(command);
  console.log('CORS rules:', response.CORSRules);
} catch (err) {
  console.error('Error getting CORS configuration:', err);
}

Eliminazione della configurazione di “ CORS ”

Rimuove tutte le regole " CORS " da un bucket. Una volta rimosse le regole, le richieste cross-origin non sono più consentite.

const { DeleteBucketCorsCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteBucketCorsCommand({
  Bucket: 'my-bucket'
});
try {
  await client.send(command);
  console.log('Bucket CORS configuration deleted successfully');
} catch (err) {
  console.error('Error deleting CORS:', err);
}

Eliminazione dei tag degli oggetti

Rimuove tutti i tag da un oggetto.

const { DeleteObjectTaggingCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteObjectTaggingCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt'
});
try {
  await client.send(command);
  console.log('Object tagging deleted successfully');
} catch (err) {
  console.error('Error deleting object tags:', err);
}

Caricamento di un oggetto con metadati personalizzati

Aggiunge coppie chiave-valore arbitrarie come metadati definiti dall'utente a un oggetto al momento del caricamento, utilizzando il campo " Metadata ". I metadati sono leggibili nelle successive chiamate a HeadObject o GetObject.

const { PutObjectCommand } = require('ibm-cos-sdk-v2');
const command = new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt',
  Body: 'content',
  Metadata: {
    'author': 'John Doe',
    'department': 'Engineering'
  }
});
try {
  await client.send(command);
  console.log('Object uploaded with metadata');
} catch (err) {
  console.error('Error uploading object:', err);
}

Impostazione dell'assegnazione dei tag ai bucket

Applica una serie di tag chiave-valore all'intero bucket. Questa operazione sostituisce qualsiasi set di tag esistente.

const { PutBucketTaggingCommand } = require('ibm-cos-sdk-v2');
const command = new PutBucketTaggingCommand({
  Bucket: 'my-bucket',
  Tagging: {
    TagSet: [
      { Key: 'Environment', Value: 'Production' },
      { Key: 'Project', Value: 'WebApp' }
    ]
  }
});
try {
  await client.send(command);
  console.log('Bucket tags updated');
} catch (err) {
  console.error('Error updating bucket tags:', err);
}

Eliminazione di una configurazione del ciclo di vita di un bucket

Rimuove tutte le regole relative al ciclo di vita da un bucket, interrompendo eventuali azioni automatiche di scadenza o transizione precedentemente configurate.

const { DeleteBucketLifecycleCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteBucketLifecycleCommand({
  Bucket: 'my-bucket'
});
try {
  await client.send(command);
  console.log('Lifecycle configuration deleted successfully');
} catch (err) {
  console.error('Error deleting lifecycle:', err);
}

Configurazione dell'ACL del bucket

Applica un ACL predefinito (ad esempio, public-read) all'intero bucket, sostituendo la politica di controllo degli accessi esistente e gestendo l'accesso predefinito per tutti gli oggetti in esso contenuti.

const { PutBucketAclCommand } = require('ibm-cos-sdk-v2');
const command = new PutBucketAclCommand({
  Bucket: 'my-bucket',
  ACL: 'public-read'
});
try {
  await client.send(command);
  console.log('Bucket ACL updated');
} catch (err) {
  console.error('Error updating bucket ACL:', err);
}

Ottenere l'ACL del bucket

Recupera l'ACL corrente di un bucket, restituendo l'identità del proprietario e l'elenco delle autorizzazioni concesse (coppie composte da beneficiario e autorizzazione).

const { GetBucketAclCommand } = require('ibm-cos-sdk-v2');
const command = new GetBucketAclCommand({
  Bucket: 'my-bucket'
});
try {
  const response = await client.send(command);
  console.log('Bucket ACL retrieved successfully');
  console.log('Owner:', response.Owner);
  console.log('Grants:', response.Grants);
} catch (err) {
  console.error('Error getting bucket ACL:', err);
}

Impostazione delle ACL degli oggetti

Applica un ACL predefinito a un oggetto specifico, indipendentemente dall'ACL del bucket e sovrascrivendo l'ACL a livello di bucket per quella chiave.

const { PutObjectAclCommand } = require('ibm-cos-sdk-v2');
const command = new PutObjectAclCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt',
  ACL: 'public-read'
});
try {
  await client.send(command);
  console.log('Object ACL updated');
} catch (err) {
  console.error('Error updating object ACL:', err);
}

Ottenere l'ACL di un oggetto

Recupera l'ACL di un oggetto specifico, restituendo l'identità del proprietario e le autorizzazioni che definiscono chi può leggerlo o scriverci.

const { GetObjectAclCommand } = require('ibm-cos-sdk-v2');
const command = new GetObjectAclCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt'
});
try {
  const response = await client.send(command);
  console.log('Object ACL retrieved successfully');
  console.log('Owner:', response.Owner);
  console.log('Grants:', response.Grants);
} catch (err) {
  console.error('Error getting object ACL:', err);
}

Ottenere lo stato del controllo delle versioni

Restituisce lo stato attuale della gestione delle versioni (Enabled o Suspended) del bucket.

const { GetBucketVersioningCommand } = require('ibm-cos-sdk-v2');
const command = new GetBucketVersioningCommand({ Bucket: 'my-bucket' });
try {
  const response = await client.send(command);
  console.log('Bucket versioning configuration retrieved successfully');
  console.log('Status:', response.Status);
  // MFADelete is always undefined for IBM COS.
  console.log('MFADelete:', response.MFADelete);
} catch (err) {
  console.error('Error:', err.message);
}

Ottenere la versione di un oggetto specifico

Scarica una versione storica specifica di un oggetto specificandone l' VersionId, ignorando la versione corrente (più recente).

const { GetObjectCommand } = require('ibm-cos-sdk-v2');
const command = new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'my-file.txt',
  VersionId: '<VERSION_ID>'
});
try {
  const response = await client.send(command);
  console.log('Version ID:', response.VersionId);
  // Stream response.Body to a file or buffer as needed.
} catch (err) {
  console.error('Error:', err.message);
}

Caricamento di un oggetto in un bucket con controllo delle versioni

Quando la gestione delle versioni è abilitata, ogni chiamata a PutObjectCommand crea una nuova versione. La risposta include il nuovo VersionId.

const { PutObjectCommand } = require('ibm-cos-sdk-v2');
const command = new PutObjectCommand({
  Bucket: 'my-versioned-bucket',
  Key: 'my-file.txt',
  Body: 'Hello, World!'
});
try {
  const response = await client.send(command);
  console.log('Object uploaded successfully');
  console.log('Version ID:', response.VersionId);
} catch (err) {
  console.error('Error:', err.message);
}

Eliminazione di una versione specifica di un oggetto

Rimuove in modo definitivo una versione specifica di un oggetto includendone l' VersionId. Se in un bucket con controllo delle versioni manca l'ID della versione, viene creato invece un indicatore di eliminazione.

const { DeleteObjectCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteObjectCommand({
  Bucket: 'my-versioned-bucket',
  Key: 'my-file.txt',
  VersionId: 'YOUR_VERSION_ID_HERE'
});
try {
  const response = await client.send(command);
  console.log('Object version deleted successfully');
  console.log('Deleted Version ID:', response.VersionId);
  console.log('Delete Marker:', response.DeleteMarker ? 'Yes' : 'No');
} catch (err) {
  console.error('Error:', err.message);
}

Impostazione della protezione del bucket (WORM)

IBM Cloud Object Storage supporta la protezione dei bucket in modalità Write-Once-Read-Many (WORM) per garantire la conformità e la conservazione dei dati.

Impostazione della protezione del secchio:

const { PutBucketProtectionConfigurationCommand } = require('ibm-cos-sdk-v2');
const command = new PutBucketProtectionConfigurationCommand({
  Bucket: 'my-protected-bucket',
  ProtectionConfiguration: {
    Status: 'Retention',
    MinimumRetention: { Days: 1 },
    DefaultRetention: { Days: 30 },
    MaximumRetention: { Days: 365 },
  },
});
try {
  await client.send(command);
  console.log('Bucket protection configuration set successfully');
} catch (err) {
  console.error('Error configuring protection:', err.message);
}

Come proteggere il secchio:

const { GetBucketProtectionConfigurationCommand } = require('ibm-cos-sdk-v2');
const command = new GetBucketProtectionConfigurationCommand({
  Bucket: 'my-protected-bucket'
});
try {
  const response = await client.send(command);
  console.log('Bucket protection configuration retrieved successfully');
  console.log('Response:', JSON.stringify(response, null, 2));
} catch (err) {
  console.error('Error getting protection config:', err);
}

Creazione di un bucket crittografato con il protocollo Key Protect

IBM Key Protect fornisce la gestione delle chiavi di crittografia per la crittografia a livello di bucket:

const { CreateBucketCommand } = require('ibm-cos-sdk-v2');
const command = new CreateBucketCommand({
  Bucket: 'my-encrypted-bucket',
  CreateBucketConfiguration: {
    LocationConstraint: 'us-south-standard'
  },
  IBMSSEKPEncryptionAlgorithm: 'AES256',
  IBMSSEKPCustomerRootKeyCrn: 'crn:v1:bluemix:public:kms:us-south:...'
});
try {
  await client.send(command);
  console.log('Encrypted bucket created');
} catch (err) {
  console.error('Error creating encrypted bucket:', err);
}

Rinominare un oggetto

RenameObject è un'operazione atomica lato server specifica per COS ( IBM ). Non vengono trasferiti dati: cambiano solo le chiavi:

const { RenameObjectCommand } = require('ibm-cos-sdk-v2');
const command = new RenameObjectCommand({
  Bucket: 'my-bucket',
  Key: 'new-object-key',                    // destination key
  RenameSource: 'my-bucket/old-object-key'  // source: bucket/key
});
try {
  await client.send(command);
  console.log('Object renamed successfully');
} catch (err) {
  console.error('Error:', err.message);
}

Aggiornamento della crittografia degli oggetti

UpdateObjectEncryption aggiorna il riferimento alla chiave di crittografia su un oggetto esistente. Richiede che sul bucket sia configurato IBM Key Protect o HPCS:

const { UpdateObjectEncryptionCommand } = require('ibm-cos-sdk-v2');
const command = new UpdateObjectEncryptionCommand({
  Bucket: 'my-bucket',
  Key: 'my-object.txt'
});
try {
  await client.send(command);
  console.log('Object encryption updated successfully');
} catch (err) {
  console.error('Error:', err.message);
}

Gestione della replica dei bucket

Ottenere la configurazione della replica:

const { GetBucketReplicationCommand } = require('ibm-cos-sdk-v2');
const command = new GetBucketReplicationCommand({ Bucket: 'my-bucket' });
try {
  const response = await client.send(command);
  console.log('Bucket replication configuration retrieved successfully');
  console.log('Rules:', JSON.stringify(response.ReplicationConfiguration?.Rules, null, 2));
} catch (err) {
  console.error('Error:', err.message);
}

Eliminazione della configurazione di replica:

const { DeleteBucketReplicationCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteBucketReplicationCommand({ Bucket: 'my-bucket' });
try {
  await client.send(command);
  console.log('Bucket replication configuration deleted successfully');
} catch (err) {
  console.error('Error:', err.message);
}

Elenco degli errori di replica:

const { ListBucketReplicationFailuresCommand } = require('ibm-cos-sdk-v2');
const command = new ListBucketReplicationFailuresCommand({ Bucket: 'my-bucket' });
try {
  const response = await client.send(command);
  console.log('Bucket replication failures listed successfully');
  console.log('Response:', JSON.stringify(response, null, 2));
} catch (err) {
  console.error('Error:', err.message);
}

Ripetere i tentativi di replica falliti:

const { PutBucketReplicationReattemptCommand } = require('ibm-cos-sdk-v2');
const command = new PutBucketReplicationReattemptCommand({ Bucket: 'my-bucket' });
try {
  await client.send(command);
  console.log('Bucket replication reattempt triggered successfully');
} catch (err) {
  console.error('Error:', err.message);
}

Creazione di una sessione

CreateSession crea un token di sessione temporaneo per un bucket IBM Cloud Object Storage:

const { CreateSessionCommand } = require('ibm-cos-sdk-v2');
const command = new CreateSessionCommand({ Bucket: 'my-bucket' });
try {
  const response = await client.send(command);
  console.log('Session created successfully');
  console.log('Response:', JSON.stringify(response, null, 2));
} catch (err) {
  console.error('Error:', err.message);
}

In attesa che una risorsa sia pronta

I waiter effettuano il polling di una risorsa fino a quando questa non raggiunge lo stato desiderato, eliminando la necessità di cicli di polling manuali.

I "waiter" sono una funzionalità di v2-only. v1 non supportava i "waiter" in modo nativo, quindi era necessario implementare manualmente il polling (ad esempio, richiamando ripetutamente headBucket o headObject).

In attesa che esista un bucket:

const { waitUntilBucketExists } = require('ibm-cos-sdk-v2');
try {
  await waitUntilBucketExists(
    {
      client: client,
      maxWaitTime: 120, // Maximum wait time in seconds
      minDelay: 2,      // Minimum delay between checks in seconds
      maxDelay: 10      // Maximum delay between checks in seconds
    },
    { Bucket: 'my-bucket' }
  );
  console.log('Bucket exists and is ready');
} catch (err) {
  console.error('Bucket did not become available:', err);
}

In attesa che un oggetto esista:

const { waitUntilObjectExists } = require('ibm-cos-sdk-v2');
try {
  await waitUntilObjectExists(
    {
      client: client,
      maxWaitTime: 60,
      minDelay: 1,
      maxDelay: 5
    },
    {
      Bucket: 'my-bucket',
      Key: 'my-object.txt'
    }
  );
  console.log('Object exists and is ready');
} catch (err) {
  console.error('Object did not become available:', err);
}

Passi successivi