Creación de versiones de objetos

Archivado y caducidad de objetos con versión

Las configuraciones de ciclo de vida están permitidas en un grupo habilitado para la versión. Sin embargo, a diferencia de Amazon S3, las nuevas versiones están sujetas a la regla de archivado de la misma forma que los objetos normales. A los objetos se les da una fecha de transición cuando se crean y se archivan en su fecha de transición individual, independientemente de si son versiones actuales o no actuales. La sobrescritura de un objeto no afecta a la fecha de transición de la versión anterior y a la nueva versión (actual) se le asignará una fecha de transición.

No es posible utilizar reglas de NoncurrentVersionTransition para archivar sólo versiones no actuales de objetos en una configuración de ciclo de vida.

Inmutable Object Storage (WORM)

La implementación de IBM COS de Object Storage inmutable (es decir, políticas de retención) no está permitida en grupos con el mantenimiento de versiones habilitado. Los intentos de crear una política de retención fallarán, al igual que los intentos de habilitar el mantenimiento de versiones en un grupo con una política de retención.

Habilitar mantenimiento de versiones en un grupo

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?versioning" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: 8qj8HSeDu3APPMQZVG06WQ==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<VersioningConfiguration>
            <Status>Enabled</Status>
          </VersioningConfiguration>'

Una solicitud correcta devuelve una respuesta 200.

Suspender mantenimiento de versiones en un grupo

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?versioning" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: hxXDWuCDWB72Be0LG4XniQ==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<VersioningConfiguration>
            <Status>Suspended</Status>
          </VersioningConfiguration>'

Una solicitud correcta devuelve una respuesta 200.

Listar las versiones de los objetos de un cubo

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?versions" \
     -H 'Authorization: bearer $TOKEN'

Esto devuelve un cuerpo de respuesta XML:

<ListVersionsResult>
   <IsTruncated>boolean</IsTruncated>
   <KeyMarker>string</KeyMarker>
   <VersionIdMarker>string</VersionIdMarker>
   <NextKeyMarker>string</NextKeyMarker>
   <NextVersionIdMarker>string</NextVersionIdMarker>
   <Version>
      <ETag>string</ETag>
      <IsLatest>boolean</IsLatest>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Owner>
         <DisplayName>string</DisplayName>
         <ID>string</ID>
      </Owner>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
      <VersionId>string</VersionId>
   </Version>
   ...
   <DeleteMarker>
      <IsLatest>boolean</IsLatest>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Owner>
         <DisplayName>string</DisplayName>
         <ID>string</ID>
      </Owner>
      <VersionId>string</VersionId>
   </DeleteMarker>
   ...
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
   ...
   <EncodingType>string</EncodingType>
</ListVersionsResult>

delimiter: Un delimitador es un carácter que se especifica para agrupar claves. Todas las claves que contienen la misma serie entre el prefijo y la primera aparición del delimitador se agrupan bajo un único elemento de resultado en CommonPrefixes. Estos grupos se cuentan como un resultado con respecto a la limitación de máximo de claves. Estas claves no se devuelven en ningún otro lugar de la respuesta.

encoding-type: solicita COS para codificar por URL las claves de objeto en la respuesta. Las claves de objeto pueden contener cualquier carácter Unicode; sin embargo, el analizador 1.0 XML no puede analizar algunos caracteres, como los caracteres con un valor ASCII de 0 a 10. Para los caracteres que no están soportados en XML 1.0, puede añadir este parámetro para solicitar que COS codifique las claves en la respuesta. Valor válido: url.

key-marker: Especifica la clave con la que empezar a listar los objetos de un cubo.

max-keys: establece el número máximo de claves devueltas en la respuesta. De forma predeterminada, la API devuelve hasta 1.000 nombres de clave. La respuesta puede contener menos claves, pero nunca contendrá más.

prefix: utilice este parámetro para seleccionar sólo las claves que empiezan por el prefijo especificado.

version-id-marker: especifica la versión de objeto desde la que desea empezar a listar.

Eliminar versiones de objetos de un cubo

Una llamada normal a ListObjects o ListObjectsV2 no devuelve identificadores de versión. Para obtener los identificadores de versión necesarios para cualquier operación de borrado, debe utilizar ListObjectVersions: una petición GET con el parámetro de consulta ?versions. También devuelve los marcadores de borrado y sus ID de versión. Sin este paso, no es posible realizar ninguna de las operaciones de borrado que se describen a continuación.

ejemplo de curl:

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?versions" \
  -H 'Authorization: bearer $TOKEN'

IBM Cloud Ejemplo CLI:

ibmcloud cos object-versions --bucket $BUCKET

Ejemplo de Python:

pythonresponse = cosClient.list_object_versions(Bucket=BUCKET)
for version in response.get('Versions', []):
    print(version['Key'], version['VersionId'])
for marker in response.get('DeleteMarkers', []):
    print(marker['Key'], marker['VersionId'], '(delete marker)')

ibmcloud cos object-delete --bucket $BUCKET --key $OBJECT_KEY --version-id $VERSION_ID

pythoncosClient.delete_object(
    Bucket=BUCKET,
    Key='my-object.txt',
    VersionId='L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo'
)
Node.js:
javascriptawait cos.deleteObject({
  Bucket: 'my-versioning-bucket',
  Key: 'my-object.txt',
  VersionId: 'L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo'
}).promise();

curl -X "DELETE" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/$OBJECT_KEY?versionId=null" \
  -H 'Authorization: bearer $TOKEN'

cosClient.delete_object(
    Bucket=BUCKET,
    Key='my-object.txt',
    VersionId='null'
)

Operaciones en versiones específicas de objetos

Varias API utilizan un nuevo parámetro de consulta (?versionId=<VersionId>) que indica qué versión del objeto está solicitando. Este parámetro se utiliza de la misma forma para leer, suprimir, comprobar metadatos y etiquetas y restaurar objetos archivados. Por ejemplo, para leer una versión de un objeto foo con un ID de versión de L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo, la solicitud podría ser similar a la siguiente:

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/foo?versionId=L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" \
     -H 'Authorization: bearer $TOKEN'

La supresión de ese objeto se realiza de la misma forma.

curl -X "DELETE" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/foo?versionId=L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" \
     -H 'Authorization: bearer $TOKEN'

Para las solicitudes que ya utilizan un parámetro de consulta, el parámetro versionId se puede añadir al final.

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/foo?tagging&versionId=L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo" \
     -H 'Authorization: bearer $TOKEN'

La copia del lado del servidor de versiones de objetos está soportada, pero utiliza una sintaxis ligeramente diferente. El parámetro de consulta no se añade a la propia URL, sino que se añade al x-amz-copy-source encabezado. Esta es la misma sintaxis que crear una parte para una parte de varias partes a partir de un objeto de origen.

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/<new-object-key>"
 -H "Authorization: bearer $TOKEN"
 -H "x-amz-copy-source: /<source-bucket>/<object-key>?versionId=L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo"

Python

La habilitación del mantenimiento de versiones utilizando el SDK de IBM COS para Python se puede realizar utilizando la sintaxis de recurso de alto nivel o cliente de bajo nivel.

Utilización de un recurso:

#!/usr/bin/env python3

import ibm_boto3
from ibm_botocore.config import Config
from ibm_botocore.exceptions import ClientError

#Define constants
API_KEY = os.environ.get('IBMCLOUD_API_KEY')
SERVICE_INSTANCE = os.environ.get('SERVICE_INSTANCE_ID')
ENDPOINT = os.environ.get('ENDPOINT')

BUCKET = "my-versioning-bucket" # The bucket that will enable versioning.

#Create resource client with configuration info pulled from environment variables.
cos = ibm_boto3.resource("s3",
                         ibm_api_key_id=API_KEY,
                         ibm_service_instance_id=SERVICE_INSTANCE,
                         config=Config(signature_version="oauth"),
                         endpoint_url=ENDPOINT
                         )

versioning = cos.BucketVersioning(BUCKET)

versioning.enable()

El mantenimiento de versiones para el grupo se puede suspender utilizando versioning.suspend()

Utilizando ese mismo recurso cos, todas las versiones de objetos podrían listarse utilizando lo siguiente:

versions = s3.Bucket(BUCKET).object_versions.filter(Prefix=key)

for version in versions:
    obj = version.get()
    print(obj.get('VersionId'), obj.get('ContentLength'), obj.get('LastModified'))

Utilización de un cliente:

#!/usr/bin/env python3

import ibm_boto3
from ibm_botocore.config import Config
from ibm_botocore.exceptions import ClientError

#Define constants
API_KEY = os.environ.get('IBMCLOUD_API_KEY')
SERVICE_INSTANCE = os.environ.get('SERVICE_INSTANCE_ID')
ENDPOINT = os.environ.get('ENDPOINT')

BUCKET = "my-versioning-bucket" # The bucket that will enable versioning.

#Create resource client with configuration info pulled from environment variables.
cosClient = ibm_boto3.client("s3",
                         ibm_api_key_id=API_KEY,
                         ibm_service_instance_id=SERVICE_INSTANCE,
                         config=Config(signature_version="oauth"),
                         endpoint_url=ENDPOINT
                         )

response = cosClient.put_bucket_versioning(
    Bucket=BUCKET,
    VersioningConfiguration={
        'Status': 'Enabled'
    }
)

Listado de las versiones de un objeto utilizando el mismo cliente:

resp = cosClient.list_object_versions(Prefix='some-prefix', Bucket=BUCKET)

Borrar las versiones de un objeto utilizando el mismo cliente:

Las API de Python son muy flexibles y existen muchas formas distintas de realizar la misma tarea.

Node.js

Habilitación del mantenimiento de versiones utilizando IBM COS SDK for Node.js:

const IBM = require('ibm-cos-sdk');

var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    serviceInstanceId: '<resource-instance-id>',
};

var cos = new IBM.S3(config);

var params = {
    Bucket: 'my-versioning-bucket', /* required */
    VersioningConfiguration: { /* required */
    Status: 'Enabled'
   },
};

s3.putBucketVersioning(params, function(err, data) {
   if (err) console.log(err, err.stack); // an error occurred
   else     console.log(data);           // successful response
});