Carga por adición (SDK de Python V2) - Object Storage Service - Centro de documentación de Alibaba Cloud

La carga por adición permite agregar datos al final de un objeto existente que admite este tipo de operación. En este tema se describe cómo ejecutar una carga por adición con el SDK de OSS para Python V2.

Precauciones

El código de ejemplo de este tema utiliza la región China (Hangzhou), cuyo identificador es cn-hangzhou. De forma predeterminada, se usa un endpoint público. Si necesita acceder a OSS desde otros servicios de Alibaba Cloud en la misma región, debe usar un endpoint interno. Para más información sobre las correspondencias entre regiones y endpoints de OSS, consulte OSS regions and endpoints.
Si el objeto no existe, la llamada al método de carga por adición crea un objeto que admite esta operación.
Si el objeto ya existe:
- Cuando el objeto admite adiciones y la posición especificada coincide con la longitud actual del objeto, el contenido se agrega al final.
- Cuando el objeto admite adiciones, pero la posición especificada difiere de la longitud actual, se genera una excepción PositionNotEqualToLength.
- Cuando el objeto no admite adiciones, como ocurre con un objeto normal cargado mediante carga simple, se genera una excepción ObjectNotAppendable.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene todos los permisos. Los usuarios o roles de RAM asociados a una cuenta no cuentan con ningún permiso de manera predeterminada. La cuenta de Alibaba Cloud o su administrador deben otorgar los permisos de operación mediante RAM policies o Bucket Policy.

API

Action

Descripción

AppendObject

oss:PutObject

Esta operación permite cargar un objeto al agregarlo al final de uno existente.

oss:PutObjectTagging

Este permiso es obligatorio cuando se especifican etiquetas de objeto mediante x-oss-tagging durante una carga por adición.

Definiciones de métodos

Para los escenarios de carga por adición, el SDK de Python V2 incorpora el método AppendFile, que simula operaciones de lectura y escritura de archivos sobre los objetos de un bucket. A continuación se describen los métodos AppendFile y AppendObject.

Método

Descripción

AppendFile

Ofrece las mismas funciones que el método AppendObject.

Optimiza la tolerancia a fallos en las retransmisiones tras un error.

AppendObject

Ejecuta una carga por adición. El objeto resultante puede alcanzar un tamaño máximo de 5 GiB.

Admite la validación de datos CRC-64 (habilitada de forma predeterminada).

Es compatible con barras de progreso.

AppendFile: API de carga por adición de la edición Premium

Llame al método AppendFile para cargar datos en modo de adición. Si el objeto no existe, se crea uno que admite esta operación. Si el objeto existe pero no admite adiciones, se devuelve un error.

A continuación se muestra la definición del método AppendFile.

append_file(bucket: str, key: str, request_payer: str | None = None, create_parameter: AppendObjectRequest | None = None, **kwargs) → AppendOnlyFile

Parámetros de solicitud

Parámetro	Tipo	Descripción
bucket	str	Nombre del bucket.
key	str	Nombre del objeto.
RequestPayer	str	Si el modo de pago por solicitante está habilitado, establezca este parámetro en 'requester'.
CreateParameter	AppendObjectRequest	Metadatos del objeto configurados en la primera carga, incluidos ContentType, Metadata, permisos y clase de almacenamiento. Para más información, consulte AppendObjectRequest.

Valores devueltos

Tipo	Descripción
AppendOnlyFile	Instancia del archivo que solo admite adiciones. Para más información, consulte AppendOnlyFile.

En la siguiente tabla se describen los métodos de la clase AppendOnlyFile.

Método	Descripción
Close()	Cierra el manejador del archivo y libera los recursos.
write(b)	Escribe datos en bytes en el archivo y devuelve la cantidad de bytes escritos.
write_from(b: str	bytes	Iterable[bytes]	IO[str]	IO[bytes])	Escribe cualquier dato en el archivo y devuelve la cantidad de bytes escritos.

Para consultar la definición completa del método AppendFile, consulte append_file.

AppendObject: API de carga por adición de la edición Basic

append_object(request: AppendObjectRequest, **kwargs) → AppendObjectResult

Parámetros de solicitud

Parámetro	Tipo	Descripción
request	AppendObjectRequest	Parámetros de la solicitud. Para más información, consulte AppendObjectRequest.

Valores devueltos

Tipo	Descripción
AppendObjectResult	Valor devuelto. Para más información, consulte AppendObjectResult.

Para consultar la definición completa del método AppendObject, consulte append_object.

Ejemplos

(Recomendado) Uso de AppendFile para ejecutar una carga por adición

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This example shows how to append data to an OSS object.
parser = argparse.ArgumentParser(description="append file sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This argument is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --bucket command-line argument, which specifies the name of the bucket to operate on. This argument is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Add the --endpoint command-line argument, which specifies the domain name that other services can use to access OSS. This argument is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Add the --key command-line argument, which specifies the key of the object (file) in OSS. This argument is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command-line arguments to obtain the user-provided values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client with the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Define the data to be appended.
    data1 = b'hello'
    data2 = b' world. '

    # Append data for the first time.
    with client.append_file(bucket=args.bucket, key=args.key) as f:
        append_f = f
        f.write(data1)
    # Print the file status after the first append operation.
    print(f'closed: {append_f.closed},'
          f' name: {append_f.name}'
    )

    # Append data for the second time.
    with client.append_file(bucket=args.bucket, key=args.key) as f:
        append_f = f
        f.write(data2)
    # Print the file status after the second append operation.
    print(f'closed: {append_f.closed},'
          f' name: {append_f.name}'
    )

    # Obtain the content of the object after appending data.
    result = client.get_object(oss.GetObjectRequest(
        bucket=args.bucket,
        key=args.key,
    ))
    # Print the result of obtaining the object.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content: {result.body.content.decode("utf-8")}'
    )

# When this script is executed directly, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, where the program flow starts.

Uso de AppendObject para ejecutar una carga por adición

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser.
parser = argparse.ArgumentParser(description="append object sample")

# Add command-line arguments.
# --region: Specifies the region where the OSS bucket is located.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# --bucket: Specifies the name of the bucket to operate on.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# --endpoint: An optional parameter that specifies the domain name used to access the OSS service.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# --key: Specifies the key of the object (file) in OSS.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command-line arguments.
    args = parser.parse_args()

    # Load the authentication information required for OSS from environment variables.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations provided by the SDK.
    cfg = oss.config.load_default()

    # Set the credential provider to the previously created object.
    cfg.credentials_provider = credentials_provider

    # Set the region for the OSS client based on user input.
    cfg.region = args.region

    # If the user provides a custom endpoint, update the configuration.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Create an OSS client instance using the preceding configurations.
    client = oss.Client(cfg)

    # Define the data to be appended.
    data1 = b'hello'
    data2 = b' world'

    # Append data for the first time.
    result = client.append_object(oss.AppendObjectRequest(
        bucket=args.bucket,  # Specify the destination bucket.
        key=args.key,  # Specify the key of the object.
        position=0,  # The starting position for appending, which is initially 0.
        body=data1,  # The data to be appended.
    ))

    # Print the result of the first append operation.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' version id: {result.version_id},'
          f' hash crc64: {result.hash_crc64},'
          f' next position: {result.next_position},' 
    )

    # Append data for the second time.
    result = client.append_object(oss.AppendObjectRequest(
        bucket=args.bucket,  # Specify the destination bucket.
        key=args.key,  # Specify the key of the object.
        position=result.next_position,  # Start from the next position of the previous append operation.
        body=data2,  # The data to be appended.
    ))

    # Print the result of the second append operation.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' version id: {result.version_id},'
          f' hash crc64: {result.hash_crc64},'
          f' next position: {result.next_position},'
    )

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()

Escenarios

Mostrar una barra de progreso durante una carga por adición

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser.
parser = argparse.ArgumentParser(description="append object sample")

# Add command-line arguments.
# --region: Specifies the region where the OSS bucket is located.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# --bucket: Specifies the name of the bucket to operate on.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# --endpoint: An optional parameter that specifies the domain name used to access the OSS service.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# --key: Specifies the key of the object (file) in OSS.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command-line arguments.
    args = parser.parse_args()

    # Load the authentication information required for OSS from environment variables.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations provided by the SDK.
    cfg = oss.config.load_default()

    # Set the credential provider to the previously created object.
    cfg.credentials_provider = credentials_provider

    # Set the region for the OSS client based on user input.
    cfg.region = args.region

    # If the user provides a custom endpoint, update the configuration.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Create an OSS client instance using the preceding configurations.
    client = oss.Client(cfg)

    # Define a dictionary variable named progress_state to save the upload progress status. The initial value is 0.
    progress_state = {'saved': 0}
    def _progress_fn(n, written, total):
        # Use a dictionary to store the cumulative number of written bytes to avoid using global variables.
        progress_state['saved'] += n

        # Calculate the current upload percentage. The value is obtained by dividing the number of written bytes by the total number of bytes and rounding down the result.
        rate = int(100 * (float(written) / float(total)))

        # Print the current upload progress. \r indicates returning to the beginning of the line to implement real-time refresh in the command line.
        # end='' indicates no line break, so that the next printout overwrites the current line.
        print(f'\rUpload progress: {rate}% ', end='')

    # Define the data to be appended.
    data1 = b'hello'
    data2 = b' world'

    # Append data for the first time.
    result = client.append_object(oss.AppendObjectRequest(
        bucket=args.bucket,  # Specify the destination bucket.
        key=args.key,  # Specify the key of the object.
        position=0,  # The starting position for appending, which is initially 0.
        body=data1,  # The data to be appended.
        progress_fn=_progress_fn,  # Set the progress callback function.
    ))

    # Print the result of the first append operation.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' version id: {result.version_id},'
          f' hash crc64: {result.hash_crc64},'
          f' next position: {result.next_position},'
    )

    # Append data for the second time.
    result = client.append_object(oss.AppendObjectRequest(
        bucket=args.bucket,  # Specify the destination bucket.
        key=args.key,  # Specify the key of the object.
        position=result.next_position,  # Start from the next position of the previous append operation.
        body=data2,  # The data to be appended.
        progress_fn=_progress_fn,  # Set the progress callback function.
    ))

    # Print the result of the second append operation.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' version id: {result.version_id},'
          f' hash crc64: {result.hash_crc64},'
          f' next position: {result.next_position},'
    )

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()

Referencias

Para consultar el código de ejemplo completo de la carga por adición, consulte append_file.py y append_object.py.