Verwendung des IBM Cloud® Object Storage- SDK for Node.jsv2

Verwenden Sie das IBM Cloud® Object Storage- SDK for Node.jsv2, um das SDK zu installieren, Clients zu erstellen und Buckets sowie Objekte mithilfe moderner APIs und IAM zu verwalten.

Die „ IBM Cloud® Object Storage “ SDK for Node.js v2 bietet Funktionen, mit denen Sie IBM Cloud Object Storage optimal nutzen können.

Das IBM Cloud Object Storage- SDK for Node.jsv2 ist sehr umfangreich und verfügt über zahlreiche Funktionen und Möglichkeiten, die den Rahmen dieses Handbuchs sprengen würden. Ausführliche Informationen zu Klassen und Methoden finden Sie in der Node.js-API-Referenzdokumentation. Den Quellcode finden Sie im GitHub-Repository.

Neuerungen in v2

IBM Cloud Object Storage ( SDK for Node.js ) ( v2 ) ist eine modernisierte Version, die auf der Architektur des AWS SDK ( v3 ) basiert und erhebliche Verbesserungen mit sich bringt:

Modulare Architektur – Importieren Sie nur die Befehle und Clients, die Sie benötigen
„Promise-first“-Design – Native Unterstützung für „async/await“ mit übersichtlicherer Fehlerbehandlung
Kleinere Bundle-Größen – Durch „Tree-Shake“ optimierte Module reduzieren die Anwendungsgröße
Modern JavaScript – Nutzt die Funktionen von ES6+ und die Unterstützung von TypeScript
Middleware-Stack – Erweiterbare Request/Response-Pipeline
Bessere Fehlerbehandlung – Strukturierte Fehlertypen mit detaillierten Informationen

Entwickler, die von „ v1 “ migrieren, finden weitere Informationen im Migrationsleitfaden.

SDK abrufen

Die empfohlene Vorgehensweise zur Installation des IBM Cloud Object Storage- SDK for Node.js ist die Verwendung des npm-Paketmanagers für Node.js. Geben Sie dazu einfach Folgendes in ein Terminalfenster ein:

npm install ibm-cos-sdk-v2

Voraussetzungen

Node.js 18 oder höher – Das SDK erfordert mindestens die Version 18 von „ Node.js “ oder eine neuere Version.
Eine Instanz von IBM Cloud Object Storage
Ein API-Schlüssel von IBM Cloud Identity and Access Management mit mindestens den Berechtigungen „ Writer “
Die ID der Instanz von Object Storage, mit der Sie arbeiten
Endpunkt für den Token-Erwerb
Serviceendpunkt

Diese Werte finden Sie in der „ IBM Cloud “-Konsole unter „ Erstellen einer „Dienstanmeldeinformation“ “.

Pakete importieren

Nachdem Sie das SDK installiert haben, müssen Sie die benötigten Pakete in Ihre Node.js-Anwendungen importieren, um das SDK nutzen zu können, wie im folgenden Beispiel gezeigt:

CommonJS:

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

ES-Module / TypeScript:

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

SDK-Referenzen

Kernklassen

S3Client- Hauptklient für die Interaktion mit IBM Cloud Object Storage
Befehlsklassen – Jeder Vorgang hat eine entsprechende Befehlsklasse (zum Beispiel PutObjectCommand, GetObjectCommand)

Konfiguration

S3Client Konstruktor – Erstellt einen neuen „ S3 “-Client mit Konfigurationsoptionen
Region – Legt die Region für den Client fest
endpoint – Legt den Service-Endpunkt fest URL
Anmeldedaten – Legt die Anmeldedaten fest

Erstellen eines Clients und Abrufen der Anmeldedaten für den Dienst

Zum Herstellen einer Verbindung zu IBM Cloud Object Storage wird ein Client erstellt und durch Bereitstellen der Berechtigungsnachweisinformationen (API-Schlüssel und Serviceinstanz-ID) konfiguriert. Diese Werte können auch automatisch aus einer Berechtigungsnachweisdatei oder aus Umgebungsvariablen abgeleitet werden.

Die Berechtigungsnachweise können durch Erstellen eines Serviceberechtigungsnachweises oder über eine Befehlszeilenschnittstelle gesucht werden.

IAM-Authentifizierung mit „ IBM “

Das folgende Beispiel zeigt, wie man einen Client mithilfe der IAM-Authentifizierung von „ IBM “ mit einem API-Schlüssel erstellt:

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>'
  }
});

Die erforderlichen Konfigurationsoptionen lauten:

endpoint- Die Endpunkt- URL für die Region Ihres Object Storage-Buckets
region- Die Region, in der sich Ihr Bucket befindet
credentials.apiKey- Ihren API-Schlüssel für „ IBM Cloud “ mit den entsprechenden Berechtigungen
credentials.serviceInstanceId- Der CRN (Cloud Resource Name) Ihrer Object Storage-Instanz

Codebeispiele

In den folgenden Beispielen wird davon ausgegangen, dass Sie bereits einen Mandanten angelegt haben, wie im vorherigen Abschnitt beschrieben.

Einen Protokollbereich erstellen

Erstellt einen neuen Bucket in der angegebenen Region mithilfe eines im LocationConstraint Block 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);
}

Verfügbare Buckets auflisten

Gibt alle Buckets zurück, die dem authentifizierten Konto gehören, einschließlich des Namens und des Erstellungsdatums jedes Buckets.

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);
}

Auflistung von Buckets mit erweiterten Informationen

ListBucketsExtended ist eine IBM Cloud Object Storage-spezifische Operation, die im Vergleich zur Standardoperation ListBuckets zusätzliche Metadaten für jeden Bucket (Standortbeschränkung und Erstellungsdatum) zurückgibt:

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);
}

Den Speicherort eines Buckets abrufen

Ruft die ( LocationConstraint Region und Speicherklasse) des angegebenen Buckets ab.

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);
}

Bucket löschen

Löscht einen leeren Bucket dauerhaft. Der Bucket darf keine Objekte enthalten, bevor eine Löschung zulässig ist.

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);
}

Hinweis: Ein Bucket muss leer sein, bevor er gelöscht werden kann.

Ein Objekt in einen Bucket hochladen

Lädt ein Objekt (Zeichenkette, Puffer oder Stream) unter dem angegebenen Schlüssel in einen Bucket hoch. Die Antwort enthält das Objekt ETag.

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);
}

Ein Objekt aus einem Bucket herunterladen

Lädt ein Objekt aus einem Bucket herunter. In Version v2 ist der Antworttext ein lesbarer Datenstrom, der verarbeitet (beispielsweise mit transformToString()) oder weitergeleitet werden muss.

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);
}

Objekte in einem Protokollbereich auflisten

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);
}

Ein Objekt kopieren

Kopiert ein vorhandenes Objekt vollständig serverseitig auf einen neuen Schlüssel oder in einen neuen Bucket. Über den Client werden keine Daten übertragen. Die Antwort enthält den ETag der Kopie.

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);
}

Objekt löschen

Löscht ein einzelnes Objekt anhand seines Schlüssels. Bei einem versionierten Bucket erstellt dieser Vorgang eine Löschmarkierung, anstatt die Daten dauerhaft zu entfernen.

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);
}

Mehrere Objekte löschen

Löscht bis zu 1.000 Objekte in einer einzigen Anfrage. Die Antwort listet die erfolgreich gelöschten Schlüssel sowie etwaige Fehler bei Schlüsseln auf, die nicht gelöscht werden konnten.

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);
}

Objektmetadaten abrufen (HEAD)

Ruft die Metadaten eines Objekts (Inhaltstyp, Größe, ETag und benutzerdefinierte Metadaten) ab, ohne den Objektkörper herunterzuladen.

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);
}

Mehrteilige Uploads verwenden

Bei großen Objekten bietet der mehrteilige Upload einen höheren Durchsatz und die Möglichkeit, den Upload fortzusetzen. Jeder Teil muss mindestens 5 MB groß sein (mit Ausnahme des letzten Teils).

Manuelles Hochladen mehrerer Dateien:

Der im Handbuch beschriebene Ablauf teilt eine große Datei in Blöcke fester Größe auf, lädt jeden Block mithilfe von als nummerierten Teil UploadPartCommand hoch und schließt den Upload anschließend mit ab CompleteMultipartUploadCommand. Dieser Ansatz ermöglicht Ihnen die vollständige Kontrolle über die Teilgröße, die Wiederholungslogik und parallele Uploads. Wenn ein Upload fehlschlägt, AbortMultipartUploadCommand werden alle bereits hochgeladenen Teile entfernt. Der Upload wird mit CreateMultipartUploadCommand. gestartet.

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);
}

Verwendung des Upload-Managers (empfohlen):

Verwenden Sie das Paket @ibm-cos/lib-storage, um das Hochladen mehrteiliger Dateien zu vereinfachen. Der übergeordnete Helper Upload umschließt den dreistufigen manuellen Ablauf (CreateMultipartUpload, UploadPart, CompleteMultipartUpload), unterteilt den Datenstrom automatisch in Abschnitte, lädt Teile parallel hoch und gibt Fortschrittsereignisse aus.

Der Upload Manager ist eine ausschließlich in v2-only-verfügbare Funktion. In v1 wurden s3.upload() und ManagedUpload aus dem ibm-cos-sdk Paket verwendet, die nicht mit dem v2-SDK kompatibel sind.

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);
}

Auflistung von mehrteiligen Uploads

Listet alle laufenden mehrteiligen Uploads für einen Bucket auf. Unvollständige Uploads belegen Speicherplatz und verursachen Kosten.

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);
}

Auflistung von Teilen eines mehrteiligen Uploads

Listet alle hochgeladenen Teile eines laufenden mehrteiligen Uploads auf. Nützlich, um den Fortschritt zu überprüfen oder ETags zu erfassen, bevor der Upload abgeschlossen ist.

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);
}

Einen Teil aus einem vorhandenen Objekt kopieren

Lädt ein Teil hoch, indem es aus einem vorhandenen Objekt kopiert wird. Verwenden Sie dies anstelle des Hochladens von Rohdaten, wenn die Quelldaten bereits in Object Storage vorhanden sind.

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);
}

Konfiguration des Lebenszyklus eines Buckets

Mithilfe von Archivierungsrichtlinien können Sie Objekte nach Ablauf eines festgelegten Zeitraums automatisch in Archivspeicherklassen verschieben.

Das folgende Beispiel definiert eine Regel, die Objekte unter dem Präfix logs/ nach 30 Tagen löscht. In v2 muss jede Regel einen Filter Block (zum Beispiel Filter: { Prefix: 'logs/' }) verwenden, anstatt der in v1 verwendeten Eigenschaft Prefix auf oberster Ebene. Die API lehnt Regeln ab, die noch das flache v1-Format verwenden.

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);
}

Konfiguration des Lebenszyklus eines Buckets abrufen

Ruft die Lebenszykluskonfiguration für einen Bucket ab und gibt alle Regeln als Array von Regelobjekten zurück.

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);
}

Versionsverwaltung für Buckets aktivieren

Legt fest, Status: 'Enabled' dass die Versionsverwaltung für den Bucket aktiviert wird. Nachdem die Versionsverwaltung aktiviert wurde, wird bei jedem Überschreiben eine neue Version erstellt, anstatt das Objekt zu ersetzen. Verwenden Sie, 'Suspended' um die Versionsverwaltung anzuhalten. 'Disabled' ist kein gültiger Wert.

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);
}

Objektversionen auflisten

Gibt alle Versionen und Löschmarkierungen für jedes Objekt in einem versionierten Bucket zurück.

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);
}

CORS-Konfiguration festlegen

Legt CORS-Regeln für einen Bucket fest und definiert dabei zulässige Ursprünge, Methoden, Header, offengelegte Header sowie die Gültigkeitsdauer des Preflight-Caches. Dieser Vorgang ersetzt alle bestehenden CORS-Konfigurationen.

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);
}

Objektkennzeichnung einrichten

Wendet eine Reihe von Schlüssel-Wert-Tags auf ein Objekt an.

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);
}

Objekt-Tags abrufen

Ruft die für ein Objekt festgelegten Tags ab.

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);
}

Ein archiviertes Objekt wiederherstellen

Objekte in Archivspeicherklassen müssen wiederhergestellt werden, bevor auf sie zugegriffen werden kann:

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);
}

Hinweis: IBM Cloud Object Storage unterstützt nur die Bulk Abrufebene für die Wiederherstellung von Objekten aus den Speicherklassen Vault und Cold Vault.

Festlegen der Aufbewahrungsdauer von Objekten

Legt eine Aufbewahrungsfrist für ein bestimmtes Objekt fest und verhindert so dessen Löschung oder Überschreiben bis zum Ablaufdatum.

Verwaltungsmodus: Benutzer mit bestimmten IAM-Berechtigungen können Objektversionen während der Aufbewahrungsfrist löschen.

Compliance-Modus: Kein Benutzer darf Objektversionen während der Aufbewahrungsfrist löschen.

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);
}

Objektspeicherung abrufen

Liest den derzeit für ein bestimmtes Objekt festgelegten Aufbewahrungsmodus und das Aufbewahrungsende ab.

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);
}

Erstellen eines Buckets mit Object Lock ( S3 )

S3 Object Lock verhindert, dass Objekte für einen festgelegten Aufbewahrungszeitraum oder auf unbestimmte Zeit gelöscht oder überschrieben werden. Object Lock muss bei der Erstellung des Buckets aktiviert werden – es kann nicht zu einem bereits vorhandenen Bucket hinzugefügt werden.

Verwaltungsmodus: Benutzer mit bestimmten IAM-Berechtigungen können Objektversionen während der Aufbewahrungsfrist löschen.

Compliance-Modus: Kein Benutzer darf Objektversionen während der Aufbewahrungsfrist löschen.

Dieser Abschnitt behandelt S3-compatible: Object Lock. Informationen zum COS-spezifischen WORM-Schutz für IBM finden Sie unter Bucket-Schutz(WORM)einrichten und Rechtliche Aufbewahrungspflichten verwalten.

S3-Objektsperre wurde in v1 des IBM Cloud Object Storage-SDK nicht unterstützt. Alle in diesem Thema beschriebenen S3-Object-Lock-Vorgänge sind v2-only.

In diesem Beispiel wird ein Bucket mit aktivierter Object Lock-Funktion erstellt und sofort eine Standard-Aufbewahrungsregel GOVERNANCE von 30 Tagen festgelegt, sodass alle neuen Objekte automatisch geschützt sind.

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);
}

Konfiguration von Object Lock

Legt die Standard-Aufbewahrungsregel fest oder aktualisiert sie, die auf jedes neue Objekt angewendet wird, das in einen Bucket hochgeladen wird.

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);
}

Konfiguration von Object Lock

Ruft den Status der aktivierten Objekt-Sperre des Buckets sowie die Standard-Aufbewahrungsregel ab.

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);
}

Einrichten einer rechtlichen Aufbewahrungspflicht für Object Lock in S3

Legt eine Aufbewahrungsverpflichtung für ein Objekt fest oder hebt diese auf. Solange eine rechtliche Aufbewahrungsverpflichtung besteht, kann das Objekt unabhängig von seiner Aufbewahrungsfrist nicht gelöscht werden.

const { PutObjectLegalHoldCommand } = require('ibm-cos-sdk-v2');
const command = new PutObjectLegalHoldCommand({
  Bucket: 'my-locked-bucket',
  Key: 'my-file.txt',
  LegalHold: {
    Status: 'ON' // 'ON' or 'OFF'
  }
});
try {
  await client.send(command);
  console.log('Legal hold set successfully');
} catch (err) {
  console.error('Error:', err.message);
}

S3-Objektsperre für die Aufbewahrungspflicht

Prüft, ob für das angegebene Objekt derzeit eine Aufbewahrungsverpflichtung aktiv (ON) oder inaktiv (OFF) ist.

const { GetObjectLegalHoldCommand } = require('ibm-cos-sdk-v2');
const command = new GetObjectLegalHoldCommand({
  Bucket: 'my-locked-bucket',
  Key: 'my-file.txt'
});
try {
  const response = await client.send(command);
  console.log('Legal hold retrieved successfully');
  console.log('Status:', response.LegalHold?.Status);
} catch (err) {
  console.error('Error:', err.message);
}

Prüfen, ob ein Bucket existiert (HEAD)

Prüft, ob ein Bucket vorhanden ist und der Aufrufer Zugriff darauf hat, ohne dabei den Inhalt des Buckets zurückzugeben.

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);
  }
}

Streaming-Upload aus einer Datei

Öffnet eine Datei als lesbaren Datenstrom und übergibt sie direkt als Argument Body eines Aufrufs PutObjectCommand, wodurch vermieden wird, dass die gesamte Datei in den Arbeitsspeicher geladen wird.

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);
}

Streaming-Download in eine Datei

Ruft ein Objekt als Stream ab und leitet es direkt an einen beschreibbaren Dateistrom weiter. In v2 ist response.Body ein lesbarer Datenstrom, der weitergeleitet oder abgefragt werden kann.

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);
}

Alle Objekte mit Paginierung auflisten

Das v2-SDK bietet integrierte Paginatoren für Operationen, die gekürzte Ergebnisse zurückgeben.

Verwendung eines Paginators (empfohlen):

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

Manuelle Paginierung:

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

Vorab signierte URLs generieren

Vorsignierte URLs ermöglichen einen vorübergehenden, nicht authentifizierten Zugriff auf Objekte. Installieren Sie zunächst das presigner-Paket:

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

Vorsignierte GET- URL-Datei (Download):

Erstellt ein GetObjectCommand und übergibt es an aus getSignedUrl dem presigner-Paket, um eine zeitlich begrenzte URL (gültig für 1 Stunde) zu generieren, die nicht authentifizierten Lesezugriff auf das angegebene Objekt gewährt.

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);
}

Vorgesignierte PUT- URL en (Upload):

Erstellt ein PutObjectCommand und übergibt es an, getSignedUrl um eine vorab authentifizierte Upload- URL zu generieren, die 1 Stunde lang gültig ist und auf einen bestimmten Inhaltstyp beschränkt ist. Ein Client kann die URL verwenden, um ein Objekt direkt in IBM Cloud Object Storage hochzuladen, ohne dass SDK-Anmeldedaten erforderlich sind.

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);
}

CORS-Konfiguration einrichten

Ruft die aktuelle CORS-Konfiguration für einen Bucket ab und gibt ein Array zurück, CORSRules das den zulässigen Cross-Origin-Zugriff beschreibt.

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);
}

CORS-Konfiguration löschen

Entfernt alle CORS-Regeln aus einem Bucket. Nachdem die Regeln entfernt wurden, sind domänenübergreifende Anfragen nicht mehr zulässig.

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);
}

Objekt-Tags löschen

Entfernt alle Tags aus einem Objekt.

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);
}

Hochladen eines Objekts mit benutzerdefinierten Metadaten

Fügt beim Hochladen mithilfe des Metadata Feldes beliebige Schlüssel-Wert-Paare als benutzerdefinierte Metadaten an ein Objekt an. Die Metadaten können bei nachfolgenden oder HeadObject GetObject Aufrufen gelesen werden.

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);
}

Einrichten von Bucket-Tags

Wendet eine Reihe von Schlüssel-Wert-Tags auf einen gesamten Bucket an. Dieser Vorgang ersetzt alle vorhandenen Tag-Sätze.

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);
}

Löschen einer Lebenszykluskonfiguration für einen Bucket

Entfernt alle Lebenszyklusregeln aus einem Bucket und stoppt damit alle zuvor konfigurierten automatisierten Ablauf- oder Übergangsaktionen.

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);
}

Bucket-ACL festlegen

Wendet eine vorgefertigte ACL (zum Beispiel public-read) auf einen gesamten Bucket an, ersetzt dabei die bestehende Zugriffskontrollrichtlinie und regelt den Standardzugriff für alle darin enthaltenen Objekte.

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);
}

Bucket-ACL abrufen

Ruft die aktuelle ACL für einen Bucket ab und gibt die Identität des Eigentümers sowie die Liste der Berechtigungen (Paare aus Berechtigungsempfänger und Berechtigung) zurück.

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);
}

ACL für Objekte festlegen

Wendet eine vordefinierte ACL auf ein bestimmtes Objekt an, unabhängig von der ACL des Buckets und unter Überschreibung der ACL auf Bucket-Ebene für diesen Schlüssel.

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);
}

Objekt-ACL abrufen

Ruft die ACL für ein bestimmtes Objekt ab und gibt die Identität des Eigentümers sowie die Berechtigungen zurück, die festlegen, wer das Objekt lesen oder schreiben darf.

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);
}

Versionsstatus abrufen

Gibt den aktuellen Versionsstatus (Enabled oder Suspended) des Buckets zurück.

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);
}

Eine bestimmte Objektversion abrufen

Lädt eine bestimmte historische Version eines Objekts herunter, indem dessen ID angegeben wird VersionId, und umgeht dabei die aktuelle (neueste) Version.

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);
}

Ein Objekt in einen versionierten Bucket hochladen

Wenn die Versionsverwaltung aktiviert ist, wird bei jedem Aufruf PutObjectCommand eine neue Version erstellt. Die Antwort enthält das neue 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);
}

Eine bestimmte Objektversion löschen

Löscht eine bestimmte Version eines Objekts dauerhaft, indem dessen VersionId. Fehlt bei einem versionierten Bucket eine Versions-ID, wird stattdessen eine Löschmarkierung erstellt.

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);
}

Einrichten des Bucket-Schutzes (WORM)

IBM Cloud Object Storage Unterstützt den WORM-Schutz (Write-Once-Read-Many) für Buckets zur Einhaltung gesetzlicher Vorschriften und zur Datenaufbewahrung.

Einrichten des Bucket-Schutzes:

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);
}

So richten Sie den Bucket-Schutz ein:

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);
}

Verwaltung von Aufbewahrungspflichten

Rechtliche Aufbewahrungspflichten sind eine IBM Cloud Object Storage-spezifische Funktion (Immutable Object Storage ). Sie verhindern das Löschen von Objekten, unabhängig davon, ob die Aufbewahrungsfrist abgelaufen ist. Jede Sperre wird durch eine eindeutige ID identifiziert, und alle Sperren müssen ausdrücklich aufgehoben werden, bevor ein Objekt gelöscht werden kann.

Hinweis: Für rechtliche Aufbewahrungspflichten muss für den Bucket eine Schutzkonfiguration für IBM Cloud Object Storage festgelegt sein. Diese Aufbewahrungspflichten unterscheiden sich von den Aufbewahrungspflichten für S3 Object Lock.

Hinzufügen einer Aufbewahrungsverpflichtung:

const { AddLegalHoldCommand } = require('ibm-cos-sdk-v2');
const command = new AddLegalHoldCommand({
  Bucket: 'my-protected-bucket',
  Key: 'important-document.pdf',
  RetentionLegalHoldId: 'legal-case-12345'
});
try {
  await client.send(command);
  console.log('Legal hold added');
} catch (err) {
  console.error('Error adding legal hold:', err);
}

Auflistung der Aufbewahrungspflichten:

const { ListLegalHoldsCommand } = require('ibm-cos-sdk-v2');
const command = new ListLegalHoldsCommand({
  Bucket: 'my-protected-bucket',
  Key: 'important-document.pdf'
});
try {
  const response = await client.send(command);
  console.log('Legal holds listed successfully');
  console.log('Legal holds:', JSON.stringify(response.LegalHolds, null, 2));
} catch (err) {
  console.error('Error listing legal holds:', err);
}

Aufhebung einer Aufbewahrungsverpflichtung:

const { DeleteLegalHoldCommand } = require('ibm-cos-sdk-v2');
const command = new DeleteLegalHoldCommand({
  Bucket: 'my-protected-bucket',
  Key: 'important-document.pdf',
  RetentionLegalHoldId: 'legal-case-12345'
});
try {
  await client.send(command);
  console.log('Legal hold removed');
} catch (err) {
  console.error('Error removing legal hold:', err);
}

Erstellen eines verschlüsselten Buckets mit Key Protect

IBM Key Protect bietet Verschlüsselungsschlüsselverwaltung für die Verschlüsselung auf Bucket-Ebene:

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);
}

Umbenennen eines Objekts

RenameObject ist eine COS-spezifische atomare serverseitige Operation des IBM. Es werden keine Daten übertragen – lediglich die wichtigsten Änderungen:

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);
}

Aktualisierung der Objektverschlüsselung

UpdateObjectEncryption Aktualisiert die Verschlüsselungsschlüsselreferenz für ein bestehendes Objekt. Voraussetzung ist, dass für den Bucket IBM, Key Protect oder HPCS konfiguriert ist:

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);
}

Verwaltung der Bucket-Replikation

Replikationskonfiguration abrufen:

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);
}

Replikationskonfiguration löschen:

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);
}

Auflistung von Replikationsfehlern:

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);
}

Wiederholung fehlgeschlagener Replikationen:

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);
}

Eine Sitzung erstellen

CreateSession Erstellt ein temporäres Sitzungstoken für einen IBM Cloud Object Storage-Bucket:

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);
}

Warten, bis eine Ressource bereit ist

Waiter fragen eine Ressource so lange ab, bis diese den gewünschten Zustand erreicht hat, wodurch manuelle Abfrageschleifen überflüssig werden.

Waiter sind eine Funktion, die nur in Version v2-only verfügbar ist. In Version v1 gab es keine integrierte Unterstützung für Waiter, sodass das Abfragen (beispielsweise durch wiederholtes Aufrufen von oder headBucket headObject) manuell implementiert werden musste.

Warten auf die Existenz eines Buckets:

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);
}

Warten auf das Vorhandensein eines Objekts:

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);
}

Nächste Schritte

Lesen Sie die API-Referenzdokumentation zu „ Node.js “, um detaillierte Informationen zu allen verfügbaren Methoden und Typen zu erhalten
Weitere Beispiele und Quellcode finden Sie im Repository „ GitHub “
Lesen Sie den Migrationsleitfaden, wenn Sie ein Upgrade von v1
In der „ IBM Cloud Object Storage Dokumentation “ finden Sie dienstspezifische Funktionen und bewährte Vorgehensweisen
Für Hilfe und Unterstützung:
- Stelle Fragen auf Stack Overflow mit den Tags „ ibm “ und object-storage
- Eröffne ein Ticket auf GitHub
- Kontakt zum IBM Cloud-Support