Requisitos mínimos

Para ejecutar el SDK, necesita Node 4.x+.

Creación de credenciales de cliente y de origen

Para conectarse a COS, se crea y se configura un cliente proporcionando información de credenciales (clave de API, ID de instancia de servicio y punto final de autenticación de IBM). Estos valores también se pueden tomar automáticamente de un archivo de credenciales o de variables de entorno.

Después de generar una credencial de servicio, el documento JSON resultante se puede guardar en ~/.bluemix/cos_credentials. El SDK tomará automáticamente las credenciales de este archivo, a menos que se establezcan explícitamente otras credenciales durante la creación del cliente. Si el archivo cos_credentials contiene claves de HMAC, el cliente se autentica con una firma; de lo contrario, el cliente utiliza la clave de API proporcionada para autenticarse con una señal de portadora.

La cabecera de sección default especifica un perfil predeterminado y los valores asociados para credenciales. Puede crear más perfiles en el mismo archivo de configuración compartido, cada uno con su propia información de credenciales. En el ejemplo siguiente se muestra un archivo de configuración con el perfil predeterminado:

[default]
ibm_api_key_id = <DEFAULT_IBM_API_KEY>
ibm_service_instance_id = <DEFAULT_IBM_SERVICE_INSTANCE_ID>
ibm_auth_endpoint = <DEFAULT_IBM_AUTH_ENDPOINT>

Si se migra desde AWS S3, también puede obtener los datos de credenciales de origen de ~/.aws/credentials en el formato:

aws_access_key_id = <DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <DEFAULT_SECRET_ACCESS_KEY>

Si existen tanto ~/.bluemix/cos_credentials como ~/.aws/credentials, prevalece cos_credentials.

Inicialización de la configuración

const IBM = require('ibm-cos-sdk');
var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    serviceInstanceId: '<resource-instance-id>',
    signatureVersion: 'iam',
};
var cos = new IBM.S3(config);

Valores de clave

• <endpoint>- Punto de acceso público para tu almacenamiento de objetos en la nube (disponible en el panel de control de IBM Cloud ). Para obtener más información sobre puntos finales, consulte Puntos finales y ubicaciones de almacenamiento.
• <api-key>- Clave API generada al crear las credenciales del servicio (se requiere acceso de escritura para los ejemplos de creación y eliminación)
• <resource-instance-id>- ID de recurso de tu almacenamiento de objetos en la nube (disponible a través de la CLI de IBM Cloud o del panel de control de IBM Cloud )

Creación de un grupo

Puede consultar la lista de códigos de suministro válidos para LocationConstraint en la guía de Storage Classes.

function createBucket(bucketName) {
    console.log(`Creating new bucket: ${bucketName}`);
    return cos.createBucket({
        Bucket: bucketName,
        CreateBucketConfiguration: {
          LocationConstraint: 'us-standard'
        },
    }).promise()
    .then((() => {
        console.log(`Bucket: ${bucketName} created!`);
    }))
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• createBucket

Creación de un objeto de texto

function createTextFile(bucketName, itemName, fileText) {
    console.log(`Creating new item: ${itemName}`);
    return cos.putObject({
        Bucket: bucketName,
        Key: itemName,
        Body: fileText
    }).promise()
    .then(() => {
        console.log(`Item: ${itemName} created!`);
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• putObject

Obtención de una lista de grupos

function getBuckets() {
    console.log('Retrieving list of buckets');
    return cos.listBuckets()
    .promise()
    .then((data) => {
        if (data.Buckets != null) {
            for (var i = 0; i < data.Buckets.length; i++) {
                console.log(`Bucket Name: ${data.Buckets[i].Name}`);
            }
        }
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• listBuckets

Obtención de la lista de elementos de un grupo

function getBucketContents(bucketName) {
    console.log(`Retrieving bucket contents from: ${bucketName}`);
    return cos.listObjects(
        {Bucket: bucketName},
    ).promise()
    .then((data) => {
        if (data != null && data.Contents != null) {
            for (var i = 0; i < data.Contents.length; i++) {
                var itemKey = data.Contents[i].Key;
                var itemSize = data.Contents[i].Size;
                console.log(`Item: ${itemKey} (${itemSize} bytes).`)
            }
        }
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• listObjects

Obtención del contenido de archivo de un elemento determinado

function getItem(bucketName, itemName) {
    console.log(`Retrieving item from bucket: ${bucketName}, key: ${itemName}`);
    return cos.getObject({
        Bucket: bucketName,
        Key: itemName
    }).promise()
    .then((data) => {
        if (data != null) {
            console.log('File Contents: ' + Buffer.from(data.Body).toString());
        }
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• getObject

Supresión de un elemento de un grupo

function deleteItem(bucketName, itemName) {
    console.log(`Deleting item: ${itemName}`);
    return cos.deleteObject({
        Bucket: bucketName,
        Key: itemName
    }).promise()
    .then(() =>{
        console.log(`Item: ${itemName} deleted!`);
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• deleteObject

Supresión de varios elementos de un grupo

La solicitud de supresión puede contener un máximo de 1000 claves que desea suprimir. Si bien la supresión de objetos por lotes es muy útil para reducir la sobrecarga por solicitud, cuando suprima varias claves tenga en cuenta que la solicitud puede tardar en completarse. Además, ten en cuenta el tamaño de los objetos para garantizar un rendimiento adecuado.

function deleteItems(bucketName) {
    var deleteRequest = {
        "Objects": [
            { "Key": "deletetest/testfile1.txt" },
            { "Key": "deletetest/testfile2.txt" },
            { "Key": "deletetest/testfile3.txt" },
            { "Key": "deletetest/testfile4.txt" },
            { "Key": "deletetest/testfile5.txt" }
        ]
    }
    return cos.deleteObjects({
        Bucket: bucketName,
        Delete: deleteRequest
    }).promise()
    .then((data) => {
        console.log(`Deleted items for ${bucketName}`);
        console.log(data.Deleted);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• deleteObjects

Supresión de un grupo

function deleteBucket(bucketName) {
    console.log(`Deleting bucket: ${bucketName}`);
    return cos.deleteBucket({
        Bucket: bucketName
    }).promise()
    .then(() => {
        console.log(`Bucket: ${bucketName} deleted!`);
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• deleteBucket

Ejecución de una carga de varias partes

function multiPartUpload(bucketName, itemName, filePath) {
    var uploadID = null;
    if (!fs.existsSync(filePath)) {
        log.error(new Error(`The file \'${filePath}\' does not exist or is not accessible.`));
        return;
    }
    console.log(`Starting multi-part upload for ${itemName} to bucket: ${bucketName}`);
    return cos.createMultipartUpload({
        Bucket: bucketName,
        Key: itemName
    }).promise()
    .then((data) => {
        uploadID = data.UploadId;
        //begin the file upload
        fs.readFile(filePath, (e, fileData) => {
            //min 5MB part
            var partSize = 1024 * 1024 * 5;
            var partCount = Math.ceil(fileData.length / partSize);
            async.timesSeries(partCount, (partNum, next) => {
                var start = partNum * partSize;
                var end = Math.min(start + partSize, fileData.length);
                partNum++;
                console.log(`Uploading to ${itemName} (part ${partNum} of ${partCount})`);
                cos.uploadPart({
                    Body: fileData.slice(start, end),
                    Bucket: bucketName,
                    Key: itemName,
                    PartNumber: partNum,
                    UploadId: uploadID
                }).promise()
                .then((data) => {
                    next(e, {ETag: data.ETag, PartNumber: partNum});
                })
                .catch((e) => {
                    cancelMultiPartUpload(bucketName, itemName, uploadID);
                    console.error(`ERROR: ${e.code} - ${e.message}\n`);
                });
            }, (e, dataPacks) => {
                cos.completeMultipartUpload({
                    Bucket: bucketName,
                    Key: itemName,
                    MultipartUpload: {
                        Parts: dataPacks
                    },
                    UploadId: uploadID
                }).promise()
                .then(console.log(`Upload of all ${partCount} parts of ${itemName} successful.`))
                .catch((e) => {
                    cancelMultiPartUpload(bucketName, itemName, uploadID);
                    console.error(`ERROR: ${e.code} - ${e.message}\n`);
                });
            });
        });
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
function cancelMultiPartUpload(bucketName, itemName, uploadID) {
    return cos.abortMultipartUpload({
        Bucket: bucketName,
        Key: itemName,
        UploadId: uploadID
    }).promise()
    .then(() => {
        console.log(`Multi-part upload aborted for ${itemName}`);
    })
    .catch((e)=>{
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• abortMultipartUpload
• completeMultipartUpload
• createMultipartUpload
• uploadPart

Creación de una política de copias de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config values
const apiKey = '<API_KEY>';
const sourceBucketName = '< SOURCE_BUCKET_NAME>';
const backupVaultCrn = '<BACKUP_VAULT_CRN>';
const policyName = '<BACKUP_POLICY_NAME>';
async function  createBackupPolicy () {
  try {
    // Authenticator and client setup
    const authenticator = new IamAuthenticator({ apikey: apiKey });
    const rcClient = new ResourceConfigurationV1({ authenticator });
    // Create backup policy
    const response = await rcClient.createBackupPolicy({
      bucket: sourceBucketName,
      policyName: policyName,
      targetBackupVaultCrn: backupVaultCrn,
      backupType: “continuous”,
      initialRetention: {delete_after_days:1},
    });
    console.log('Backup  policy created successfully: ‘, response.result);
  } catch (err) {
    console.error('Error:', err);
  }
}
// Run the function
createBackupPolicy ();

Listado de una política de copias de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const sourceBucketName = '<SOURCE_BUCKET_NAME>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function listBackupPolicies() {
  try {
    // List all backup policies
    const listResponse = await rcClient.listBackupPolicies({
      bucket: sourceBucketName,
    });
    console.log('\n List of backup policies:');
    const policies = listResponse.result.backup_policies || [];
    policies.forEach(policy => console.log(policy));
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
listBackupPolicies();

Obtener una política de copias de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const sourceBucketName = '<SOURCE_BUCKET_NAME>';
const policyId = '<POLICY_ID>'; // Policy ID to retrieve backup Policy
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function fetchBackupPolicy () {
  try {
    // Fetch backup policy
    const getResponse = await rcClient.getBackupPolicy({
      bucket: sourceBucketName,
      policyId: policyId,
    });
    console.log('\nFetched Backup Policy Details:');
    console.log(getResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
fetchBackupPolicy ();

Eliminar una política de copia de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const sourceBucketName = '<SOURCE_BUCKET_NAME>';
const policyId = '<POLICY_ID_TO_DELETE>'; // Policy ID of the policy to be deleted
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function deleteBackupPolicy() {
try {
    // Delete backup policy
    await rcClient.deleteBackupPolicy({
      bucket: sourceBucketName,
      policyId: policyId,
    });
    console.log(`Backup policy '${policyId}' deleted successfully.`);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
deleteBackupPolicy ();

Creación de una copia de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const serviceInstanceId = '<SERVICE_INSTANCE_ID>';
const region = '<REGION>';
const backupVaultName = <BACKUP_VAULT_NAME>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function createBackupVault() {
  try {
    const createResponse = await rcClient.createBackupVault({
      serviceInstanceId: serviceInstanceId,
      backupVaultName: backupVaultName,
      region: region,
    });
    console.log('Backup vault created:');
    console.log(createResponse.result);
  } catch (error) {
    console.error('Error creating backup vault:', error);
  }
}
// Run the function
createBackupVault();

Listado de bóvedas de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const serviceInstanceId = '<SERVICE_INSTANCE_ID>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function listBackupVaults() {
  try {
    // List backup vaults
    const listResponse = await rcClient.listBackupVaults({
      serviceInstanceId: serviceInstanceId,
    });
    console.log('List of backup vaults:');
    console.log(listResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
listBackupVaults ();

Obtener bóvedas de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>'; // Name of the backup vault to fetch
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function fetchBackupVault () {
  try {
    // Get backup vault
    const getResponse = await rcClient.getBackupVault({
      backupVaultName: backupVaultName,
    });
    console.log('Backup vault details:');
    console.log(getResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
fetchBackupVault ();

Actualizar bóvedas de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
// Config
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>'; // Keep consistent for create + update
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function updateBackupVault() {
  try {
    // Update backup vault to disable tracking and monitoring
    const patch = {
      activity_tracking: {
        management_events: false,
      },
      metrics_monitoring: {
        usage_metrics_enabled: false,
      },
    };
    const updateResponse = await rcClient.updateBackupVault({
      backupVaultName: backupVaultName,
      backupVaultPatch: patch,
    });
    console.log(`Backup vault updated. Status code: ${updateResponse.status}`);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
updateBackupVault ();

Eliminar una copia de seguridad

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function deleteBackupVault() {
  try {
    // Delete the backup vault
    await rcClient.deleteBackupVault({
      backupVaultName: backupVaultName,
    });
    console.log(`Backup vault '${backupVaultName}' deleted successfully.`);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
deleteBackupVault();

Rangos de recuperación de listados

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function listRecoveryRanges() {
  try {
    // List recovery ranges
    const recoveryRangesResponse = await rcClient.listRecoveryRanges({
      backupVaultName: backupVaultName,
    });
    console.log('Recovery Ranges:');
    console.log(recoveryRangesResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
listRecoveryRanges();

Obtener rango de recuperación

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const recoveryRangeId = '<RECOVERY_RANGE_ID>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function fetchRecoveryRangeInfo() {
try {
    // Fetch details of the recovery range
    const recoveryRangeId = createResponse.result.recovery_range_id;  // Assuming the recovery range info is part of the response
    const getRecoveryRangeResponse = await rcClient.getSourceResourceRecoveryRange({
      backupVaultName: backupVaultName,
      recoveryRangeId: recoveryRangeId,
    });
    console.log('Recovery Range Details:');
    console.log(getRecoveryRangeResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
fetchRecoveryRangeInfo();

Actualizar el intervalo de recuperación

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
// Config
const apiKey = '<API_KEY>';
const backupVaultCrn = '<BACKUP_VAULT_CRN>';
const recoveryRangeId = '<RECOVERY_RANGE_ID>';
const policyId = '<POLICY_ID>';
// Setup authenticator and client
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
async function patchRecoveryRange() {
  try {
    // Patch the recovery range retention
    const patchResponse = await rcClient.patchSourceResourceRecoveryRange({
      backupVaultName: backupVaultName,
      recoveryRangeId: recoveryRangeId,
      retention: {
          delete_after_days: 99
        }
    });
    console.log('Recovery range updated successfully:');
    console.log(patchResponse.result);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
patchRecoveryRange ();

Iniciar una restauración

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Configuration
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
const recoveryRangeId = '<RECOVERY_RANGE_ID>';
const targetBucketCrn = '<TARGET_BUCKET_CRN>';
const restorePointInTime = '<RESTORE_POINT_TIME>';
const endpoint = '<COS_ENDPOINT>';
// Setup authenticator and clients
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
rcClient.setServiceUrl("SERVICE_URL");
async function initiateRestore () {
  try {
    // Initiate restore
    const createRestoreResponse = await rcClient.createRestore({
      backupVaultName: backupVaultName,
      recoveryRangeId: recoveryRangeId,
      restoreType: 'in_place',
      restorePointInTime: restorePointInTime,
      targetResourceCrn: targetBucketCrn,
    });
    const restoreId = createRestoreResponse.result.restore_id;
    console.log(`Restore initiated with ID: ${restoreId}`);
  } catch (error) {
    console.error('Error:', error);
  }
}
// Run the function
initiateRestore ();

Restaurar listado

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Config
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
// Auth & Clients
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
rcClient.setServiceUrl("SERVICE_URL");
async function listRestore()  {
  try {
    // List restore operations
    const listRestoreResp = await rcClient.listRestores({
      backupVaultName: backupVaultName
    });
    console.log('Restore operations:', listRestoreResp.result);
  } catch (err) {
    console.error('Error occurred:', err);
  }
};
// Run the function
listRestore();

Obtener detalles de restauración

const { IamAuthenticator } = require('ibm-cloud-sdk-core');
const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1')
// Configuration
const apiKey = '<API_KEY>';
const backupVaultName = '<BACKUP_VAULT_NAME>';
const restoreId = '<RESTORE_ID>';
const authenticator = new IamAuthenticator({ apikey: apiKey });
const rcClient = new ResourceConfigurationV1({ authenticator });
rcClient.setServiceUrl("SERVICE_URL");
async function getRestore()  {
  try {
    // Get specific restore
    const restoreDetails = await rcClient.getRestore({
      backupVaultName: backupVaultName,
      restoreId: restoreId
    });
    console.log('Restore details:', restoreDetails.result);
  } catch (err) {
    console.error('Error:', err);
  }
}
getRestore();

Crear un nuevo bucket COS con bloqueo de objetos habilitado (próximamente)

function createBucket(bucketName) {
    console.log(`Creating new bucket: ${bucketName}`);
    return cos.createBucket({
        Bucket: bucketName,
        ObjectLockEnabledForBucket: true,
        CreateBucketConfiguration: {
            LocationConstraint: ''
          },
    }).promise()
    .then((() => {
        console.log(`Bucket: ${bucketName} created!`);
    }))
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Configurar el bloqueo de objetos con modo de cumplimiento en el depósito COS (próximamente)

function putObjectLockConfigurationOnBucket(bucketName) {
    console.log(`Putting Objectlock Configuration on : ${bucketName}`);
    // Putting objectlock configuration
    var defaultRetention = {Mode: 'COMPLIANCE', Days: 1}
    var objectLockRule = {DefaultRetention : defaultRetention}
    var param = {ObjectLockEnabled: 'Enabled', Rule: objectLockRule}
    return cos.putObjectLockConfiguration({
        Bucket: bucketName,
        ObjectLockConfiguration: param
    }).promise()
    .then(() => {
        console.log(`Object lock Configurtion added!!`);
        logDone();
    })
    .catch(logError);
}

Configurar el bloqueo de objetos con modo de gobernanza en el depósito COS (próximamente)

function putObjectLockConfigurationWithGovernanceModeOnBucket(bucketName) {
    console.log(`Putting Objectlock Configuration on : ${bucketName}`);
    // Putting objectlock configuration
    var defaultRetention = {Mode: 'GOVERNANCE', Days: 1}
    var objectLockRule = {DefaultRetention : defaultRetention}
    var param = {ObjectLockEnabled: 'Enabled', Rule: objectLockRule}
    return cos.putObjectLockConfiguration({
        Bucket: bucketName,
        ObjectLockConfiguration: param
    }).promise()
    .then(() => {
        console.log(`Object lock Configurtion with Governance mode added!!`);
        logDone();
    })
    .catch(logError);
}

Obtener la configuración de bloqueo de objetos en el depósito COS (próximamente)

function getObjectLockConfigurationonBucket(bucketName) {
    console.log(`Getting Objectlock Configuration for : ${bucketName}`);
    // Getting objectlock configuration
    return cos.getObjectLockConfiguration({
        Bucket: bucketName,
    }).promise()
    .then((data) => {
        console.log(`objectlock configuration`);
        console.log( JSON.stringify(data.ObjectLockConfiguration, null, "    ") );
        logDone();
    })
    .catch(logError);
}

Subir un objeto con modo de gobernanza al depósito COS (próximamente)

function createTextFile(bucketName, itemName, fileText) {
    console.log(`Creating new item: ${itemName}`);
    return cos.putObject({
        Bucket: bucketName,
        Key: itemName,
        Body: fileText
    }).promise()
    .then(() => {
        console.log(`Item: ${itemName} created!`);
        logDone();
    })
    .catch(logError);
}

Activar la retención del bloqueo de objetos con el modo de cumplimiento en el objeto (próximamente)

function putObjectLockRetention(bucketName,keyName) {
    console.log(`Putting Objectlock Retention on : ${keyName}`);
    var inFiveSecond = (new Date(Date.now() + (1000 * 5)))
    var rule = {Mode: 'COMPLIANCE', RetainUntilDate: inFiveSecond}
     // Putting objectlock retention
    return cos.putObjectRetention({
        Bucket: bucketName,
        Key: keyName,
        Retention: rule
    }).promise()
    .then(() => {
        console.log(`Object lock Retention added!!`);
        logDone();
    })
    .catch(logError);
}

Activar la retención de bloqueo de objetos con el modo de gobernanza en el objeto (próximamente)

function putObjectLockRetentionWithGovernanceMode(bucketName,keyName) {
    console.log(`Putting Objectlock Retention on : ${keyName}`);
    var inFiveSecond = (new Date(Date.now() + (1000 * 5)))
    var rule = {Mode: 'GOVERNANCE', RetainUntilDate: inFiveSecond}
     // Putting objectlock retention
    return cos.putObjectRetention({
        Bucket: bucketName,
        Key: keyName,
        Retention: rule
    }).promise()
    .then(() => {
        console.log(`Object lock Retention with governance mode added!!`);
        logDone();
    })
    .catch(logError);
}

Obtener retención de bloqueo de objetos (próximamente)

function getObjectLockRetention(bucketName,keyName) {
    console.log(`Getting Objectlock Retention for : ${keyName}`);
    // Getting objectlock retention
    return cos.getObjectRetention({
        Bucket: bucketName,
        Key: keyName
    }).promise()
    .then((data) => {
        console.log(`Objectlock retention for : ${keyName} `);
        console.log( JSON.stringify(data.Retention, null, "    ") );
        logDone();
    })
    .catch(logError);
}

Poner objeto en bloqueo legal (próximamente)

function putObjectLocklegalHold(bucketName,keyName) {
    console.log(`Putting Objectlock legal-hold status ON for  : ${keyName}`);
     // Putting objectlock legal-hold status
    return cos.putObjectlegalHold({
        Bucket: bucketName,
        Key: keyName,
        LegalHold: {Status: 'ON'}
    }).promise()
    .then(() => {
        console.log(`Object lock legal-hold added!!`);
        logDone();
    })
    .catch(logError);
}

Obtener bloqueo de objeto legalhold (próximamente)

function getObjectLocklegalHold(bucketName,keyName) {
    console.log(`Getting Objectlock legal-hold for : ${keyName}`);
    // Getting objectlock legal-hold
    return cos.getObjectlegal-hold({
        Bucket: bucketName,
        Key: keyName
    }).promise()
    .then((data) => {
        console.log(`Objectlock legal-hold for : ${keyName} `);
        console.log( JSON.stringify(data.legal-hold, null, "    ") );
        logDone();
    })
    .catch(logError);
}

Eliminación de un objeto con modo de control de bloqueo de objetos mediante el control de omisión (próximamente)

function deleteObjectWithGovernanceMode(bucketName,keyName) {
    console.log(`Deleting an object with bypass governance : ${keyName}`);
    // Deleting an object with bypass governance
    return cos.deleteObject({
     Bucket: bucketName,
     Key: objectKey,
     BypassGovernanceRetention: true,
    }).promise()
    .then(() => {
       console.log("Object deleted");
    })
    .catch(err => {
       console.error("Error deleting object:", err);
    });
}

Antes de empezar

Para crear un bucket con la función Key-Protect activada, se necesitan los siguientes elementos:

• Un servicio de Key Protect suministrado
• Una clave raíz disponible (ya sea generada o importada)

Recuperación del CRN de la clave raíz

1. Recupere el ID de instancia del servicio Key Protect
2. Utilice la API de Key Protect para recuperar todas las claves disponibles
   • Puede utilizar mandatos curl o un cliente de API REST, como Postman, para acceder a la API de Key Protect.
3. Recupere el CRN de la clave raíz que utilizará para activar Key Protect en el grupo. El CRN se parecerá al siguiente:

crn:v1:bluemix:public:kms:us-south:a/3d624cd74a0dea86ed8efe3101341742:90b6a1db-0fe1-4fe9-b91e-962c327df531:key:0bg3e33e-a866-50f2-b715-5cba2bc93234

Creación de un grupo con Key Protect habilitado

function createBucketKP(bucketName) {
    console.log(`Creating new encrypted bucket: ${bucketName}`);
    return cos.createBucket({
        Bucket: bucketName,
        CreateBucketConfiguration: {
          LocationConstraint: '<bucket-location>'
        },
        IBMSSEKPEncryptionAlgorithm: '<algorithm>',
        IBMSSEKPCustomerRootKeyCrn: '<root-key-crn>'
    }).promise()
    .then((() => {
        console.log(`Bucket: ${bucketName} created!`);
        logDone();
    }))
    .catch(logError);
}

Valores de clave

• <bucket-location>- Región o ubicación de tu bucket ( Key Protect: solo está disponible en determinadas regiones. Asegúrese de que su ubicación coincide con el servicio de Key Protect). Puede consultar la lista de códigos de suministro válidos para LocationConstraint en la guía de Storage Classes.
• <algorithm>- El algoritmo de cifrado utilizado para los nuevos objetos añadidos al depósito (el valor por defecto es « AES256 »).
• <root-key-crn>- El CRN de la clave raíz obtenido del servicio Key Protect.

Referencias del SDK

• createBucket

Visualización de la configuración del ciclo de vida de un grupo

function getLifecycleConfiguration(bucketName) {
    return cos.getBucketLifecycleConfiguration({
        Bucket: bucketName
    }).promise()
    .then((data) => {
        if (data != null) {
            console.log(`Retrieving bucket lifecycle config from: ${bucketName}`);
            console.log(JSON.stringify(data, null, 4));
        }
        else {
            console.log(`No lifecycle configuration for ${bucketName}`);
        }
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• getBucketLifecycleConfiguration

Creación de una configuración de ciclo de vida

Encontrará información detallada sobre la estructura de las reglas de configuración del ciclo de vida en la publicación Consulta de API

function createLifecycleConfiguration(bucketName) {
    //
    var config = {
        Rules: [{
            Status: 'Enabled',
            ID: '<policy-id>',
            Filter: {
                Prefix: ''
            },
            Transitions: [{
                Days: <number-of-days>,
                StorageClass: 'GLACIER'
            }]
        }]
    };
    return cos.putBucketLifecycleConfiguration({
        Bucket: bucketName,
        LifecycleConfiguration: config
    }).promise()
    .then(() => {
        console.log(`Created bucket lifecycle config for: ${bucketName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Valores de clave

• <policy-id>- Nombre de la política de ciclo de vida (debe ser único)
• <number-of-days>- Número de días durante los que se conservará el archivo restaurado

Referencias del SDK

• putBucketLifecycleConfiguration

Supresión de la configuración del ciclo de vida de un grupo

function deleteLifecycleConfiguration(bucketName) {
    return cos.deleteBucketLifecycle({
        Bucket: bucketName
    }).promise()
    .then(() => {
        console.log(`Deleted bucket lifecycle config from: ${bucketName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• deleteBucketLifecycle

Restauración temporal de un objeto

Encontrará información detallada sobre los parámetros de la solicitud de restauración en la publicación Consulta de API

function restoreItem(bucketName, itemName) {
    var params = {
        Bucket: bucketName,
        Key: itemName,
        RestoreRequest: {
            Days: <number-of-days>,
            GlacierJobParameters: {
                Tier: 'Bulk'
            },
        }
    };
    return cos.restoreObject(params).promise()
    .then(() => {
        console.log(`Restoring item: ${itemName} from bucket: ${bucketName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Valores de clave

• <number-of-days>- Número de días durante los que se conservará el archivo restaurado

Referencias del SDK

• restoreObject

Visualización de información de HEAD para un objeto

function getHEADItem(bucketName, itemName) {
    return cos.headObject({
        Bucket: bucketName,
        Key: itemName
    }).promise()
    .then((data) => {
        console.log(`Retrieving HEAD for item: ${itemName} from bucket: ${bucketName}`);
        console.log(JSON.stringify(data, null, 4));
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Referencias del SDK

• headObject

Utilización de PUT para actualizar metadatos

Nota: La solicitud « PUT » sobrescribe el contenido actual del objeto, por lo que primero hay que descargarlo y volver a subirlo con los nuevos metadatos.

function updateMetadataPut(bucketName, itemName, metaValue) {
    console.log(`Updating metadata for item: ${itemName}`);
    //retrieve the existing item to reload the contents
    return cos.getObject({
        Bucket: bucketName,
        Key: itemName
    }).promise()
    .then((data) => {
        //set the new metadata
        var newMetadata = {
            newkey: metaValue
        };
        return cos.putObject({
            Bucket: bucketName,
            Key: itemName,
            Body: data.Body,
            Metadata: newMetadata
        }).promise()
        .then(() => {
            console.log(`Updated metadata for item: ${itemName} from bucket: ${bucketName}`);
        })
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Utilización de COPY para actualizar metadatos

function updateMetadataCopy(bucketName, itemName, metaValue) {
    console.log(`Updating metadata for item: ${itemName}`);
    //set the copy source to itself
    var copySource = bucketName + '/' + itemName;
    //set the new metadata
    var newMetadata = {
        newkey: metaValue
    };
    return cos.copyObject({
        Bucket: bucketName,
        Key: itemName,
        CopySource: copySource,
        Metadata: newMetadata,
        MetadataDirective: 'REPLACE'
    }).promise()
    .then((data) => {
        console.log(`Updated metadata for item: ${itemName} from bucket: ${bucketName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Adición de una configuración de protección a un grupo existente

Los objetos que se escriben en un grupo protegido no se pueden suprimir hasta que transcurre el periodo de protección y se eliminan todas las retenciones legales sobre el objeto. Se proporciona el valor de retención predeterminado del grupo a un objeto a menos que se proporcione un valor específico de objeto cuando se crea el objeto. Los objetos de grupos protegidos que ya no están bajo retención (el periodo de retención ha caducado y el objeto no tiene retenciones legales) vuelven a estar bajo retención cuando se sobrescriben. El nuevo periodo de retención se puede proporcionar como parte de la solicitud de sobrescritura del objeto o se asigna el tiempo de retención predeterminado del grupo al objeto.

Los valores mínimos y máximos admitidos para los valores de periodo de retención MinimumRetention, DefaultRetention y MaximumRetention son de 0 días y 365243 días (1000 años) respectivamente.

function addProtectionConfigurationToBucket(bucketName) {
    console.log(`Adding protection to bucket ${bucketName}`);
    return cos.putBucketProtectionConfiguration({
        Bucket: bucketName,
        ProtectionConfiguration: {
            'Status': 'Retention',
            'MinimumRetention': {'Days': 10},
            'DefaultRetention': {'Days': 100},
            'MaximumRetention': {'Days': 1000}
        }
    }).promise()
    .then(() => {
        console.log(`Protection added to bucket ${bucketName}!`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Comprobación de la protección sobre un grupo

function getProtectionConfigurationOnBucket(bucketName) {
    console.log(`Retrieve the protection on bucket ${bucketName}`);
    return cos.getBucketProtectionConfiguration({
        Bucket: bucketName
    }).promise()
    .then((data) => {
        console.log(`Configuration on bucket ${bucketName}:`);
        console.log(data);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Carga de un objeto protegido

Los objetos de grupos protegidos que ya no están bajo retención (el periodo de retención ha caducado y el objeto no tiene retenciones legales) vuelven a estar bajo retención cuando se sobrescriben. El nuevo periodo de retención se puede proporcionar como parte de la solicitud de sobrescritura del objeto o se asigna el tiempo de retención predeterminado del grupo al objeto.

function putObjectAddLegalHold(bucketName, objectName, legalHoldId) {
    console.log(`Add legal hold ${legalHoldId} to ${objectName} in bucket ${bucketName} with a putObject operation.`);
    return cos.putObject({
        Bucket: bucketName,
        Key: objectName,
        Body: 'body',
        RetentionLegalHoldId: legalHoldId
    }).promise()
    .then((data) => {
        console.log(`Legal hold ${legalHoldId} added to object ${objectName} in bucket ${bucketName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
function copyProtectedObject(sourceBucketName, sourceObjectName, destinationBucketName, newObjectName, ) {
    console.log(`Copy protected object ${sourceObjectName} from bucket ${sourceBucketName} to ${destinationBucketName}/${newObjectName}.`);
    return cos.copyObject({
        Bucket: destinationBucketName,
        Key: newObjectName,
        CopySource: sourceBucketName + '/' + sourceObjectName,
        RetentionDirective: 'Copy'
    }).promise()
    .then((data) => {
        console.log(`Protected object copied from ${sourceBucketName}/${sourceObjectName} to ${destinationBucketName}/${newObjectName}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Adición o eliminación de una retención legal de un objeto protegido

El objeto da soporte a 100 retenciones legales:

• Un identificador de retención legal es una serie de caracteres con una longitud máxima de 64 caracteres y una longitud mínima de 1 carácter. Los caracteres válidos son letras, números, !, _, ., *, (, ), - y '.
• Si la adición de la retención legal especificada supera las 100 retenciones legales en total del objeto, la nueva retención legal no se añade y se devuelve el error 400.
• Si un identificador es demasiado largo, no se añade al objeto y se devuelve el error 400.
• Si un identificador contiene caracteres no válidos, no se añade al objeto y se devuelve el error 400.
• Si un identificador ya se está utilizando sobre un objeto, la retención legal existente no se modifica y la respuesta indica que el identificador ya se está utilizando con el error 409.
• Si un objeto no tiene metadatos de periodo de retención, se devuelve el error 400 y no se permite añadir ni eliminar una retención legal.

El usuario que añade o elimina una retención legal debe tener el permiso de Manager sobre el grupo.

function addLegalHoldToObject(bucketName, objectName, legalHoldId) {
    console.log(`Adding legal hold ${legalHoldId} to object ${objectName} in bucket ${bucketName}`);
    return cos.client.addLegalHold({
        Bucket: bucketName,
        Key: objectId,
        RetentionLegalHoldId: legalHoldId
    }).promise()
    .then(() => {
        console.log(`Legal hold ${legalHoldId} added to object ${objectName} in bucket ${bucketName}!`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
function deleteLegalHoldFromObject(bucketName, objectName, legalHoldId) {
    console.log(`Deleting legal hold ${legalHoldId} from object ${objectName} in bucket ${bucketName}`);
    return cos.client.deleteLegalHold({
        Bucket: bucketName,
        Key: objectId,
        RetentionLegalHoldId: legalHoldId
    }).promise()
    .then(() => {
        console.log(`Legal hold ${legalHoldId} deleted from object ${objectName} in bucket ${bucketName}!`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Ampliación del periodo de retención de un objeto protegido

El periodo de retención de un objeto solo se puede ampliar. No se puede reducir con respecto al valor configurado actualmente.

El valor de ampliación de retención se establece de una de las tres maneras siguientes:

• tiempo adicional a partir del valor actual (Additional-Retention-Period o un método similar)
• nuevo periodo de ampliación en segundos (Extend-Retention-From-Current-Time o un método similar)
• nueva fecha de caducidad de retención del objeto (New-Retention-Expiration-Date o método similar)

El periodo de retención actual almacenado en los metadatos de objeto se incrementa en el tiempo adicional especificado o bien se sustituye por el nuevo valor, en función del parámetro establecido en la solicitud extendRetention. En cualquiera de los casos, el parámetro de retención de ampliación se comprueba con respecto al periodo de retención actual y el parámetro ampliado solo se acepta si el periodo de retención actualizado es mayor que el periodo de retención actual.

Los objetos de grupos protegidos que ya no están bajo retención (el periodo de retención ha caducado y el objeto no tiene retenciones legales) vuelven a estar bajo retención cuando se sobrescriben. El nuevo periodo de retención se puede proporcionar como parte de la solicitud de sobrescritura del objeto o se asigna el tiempo de retención predeterminado del grupo al objeto.

function extendRetentionPeriodOnObject(bucketName, objectName, additionalSeconds) {
    console.log(`Extend the retention period on ${objectName} in bucket ${bucketName} by ${additionalSeconds} seconds.`);
    return cos.extendObjectRetention({
        Bucket: bucketName,
        Key: objectName,
        AdditionalRetentionPeriod: additionalSeconds
    }).promise()
    .then((data) => {
        console.log(`New retention period on ${objectName} is ${data.RetentionPeriod}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Obtención de una lista de las retenciones legales sobre un objeto protegido

Esta operación devuelve:

• Fecha de creación del objeto
• Periodo de retención del objeto en segundos
• Fecha de caducidad de retención calculada en función del periodo y de la fecha de creación
• Lista de retenciones legales
• Identificador de retención legal
• Indicación de fecha y hora en que se ha aplicado la retención legal

Si no hay ninguna retención legal sobre el objeto, se devuelve un LegalHoldSet vacío. Si no se ha especificado ningún periodo de retención sobre el objeto, se devuelve el error 404.

function listLegalHoldsOnObject(bucketName, objectName) {
    console.log(`List all legal holds on object ${objectName} in bucket ${bucketName}`);
    return cos.listLegalHolds({
        Bucket: bucketName,
        Key: objectId
    }).promise()
    .then((data) => {
        console.log(`Legal holds on bucket ${bucketName}: ${data}`);
    })
    .catch((e) => {
        console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}

Crear un sitio web estático alojado

Esta operación requiere permisos, ya que normalmente solo se permite al propietario del grupo configurar un grupo para alojar un sitio web estático. Los parámetros determinan el sufijo predeterminado para los visitantes del sitio, así como un documento de error opcional.

var websiteParams = {
  Bucket: "bucketName",
  WebsiteConfiguration: {
    ErrorDocument: {
      Key: "error.html"
    },
    IndexDocument: {
      Suffix: "index.html"
    }
  }
};
function putBucketWebsiteConfiguration(websiteParams) {
  return cos.putBucketWebsite({websiteParams}).promise()
    .then((data) => {
       console.log(`Website configured for ${bucketName}`);
    })
    .catch((e) => {
       console.log(`ERROR: ${e.code} - ${e.message}\n`);
    });
}