Append data to an object by using OSS SDK for Python V2 - Object Storage Service: Central de Documentação do Alibaba Cloud

Precauções

Os exemplos de código deste tópico usam a região China (Hangzhou), cujo ID é cn-hangzhou. Por padrão, o sistema utiliza um endpoint público. Para acessar o OSS a partir de outros serviços da Alibaba Cloud na mesma região, use um endpoint interno. Para obter mais informações sobre os mapeamentos entre regiões e endpoints do OSS, consulte Regiões e endpoints do OSS.
Se o objeto não existir, a chamada ao método de upload por acréscimo criará um objeto anexável.
Se o objeto já existir:
- Caso o objeto seja anexável e a posição de acréscimo especificada coincida com o tamanho atual, o conteúdo será adicionado ao final dele.
- Se o objeto for anexável, mas a posição de acréscimo informada diferir do tamanho atual, o sistema lançará uma exceção PositionNotEqualToLength.
- Para objetos não anexáveis, como um objeto normal enviado via upload simples, o sistema lançará uma exceção ObjectNotAppendable.

Permissões

Por padrão, uma conta Alibaba Cloud tem permissões totais. Usuários RAM ou funções RAM vinculados a essa conta não possuem permissões iniciais. A conta Alibaba Cloud ou o administrador deve conceder as permissões operacionais necessárias por meio de políticas do RAM ou Bucket Policy.

Definições de métodos

Para cenários de upload por acréscimo, o Python SDK V2 inclui o método AppendFile, que simula operações de leitura e escrita de arquivos em objetos dentro de um bucket. A tabela a seguir detalha os métodos AppendFile e AppendObject.

Método

Descrição

AppendFile

Oferece as mesmas funcionalidades do método AppendObject.

Melhora a tolerância a falhas em retransmissões após erros.

AppendObject

Executa o upload por acréscimo. O objeto final pode ter até 5 GiB.

Suporta validação de dados CRC-64 (ativada por padrão).

Compatível com barras de progresso.

AppendFile: API de upload por acréscimo da Premium Edition

Use o método AppendFile para enviar dados no modo de acréscimo. Se o objeto não existir, ele será criado como anexável. Caso exista, mas não seja anexável, o sistema retornará um erro.

O código a seguir apresenta a definição do método AppendFile.

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

Parâmetros de solicitação

Parâmetro	Tipo	Descrição
bucket	str	Nome do bucket.
key	str	Nome do objeto.
RequestPayer	str	Defina este parâmetro como 'requester' se o modo de pagamento pelo solicitante estiver ativado.
CreateParameter	AppendObjectRequest	Metadados do objeto configurados no primeiro envio, incluindo ContentType, Metadata, permissões e classe de armazenamento. Para obter mais detalhes, consulte AppendObjectRequest.

Valores de retorno

Tipo	Descrição
AppendOnlyFile	Instância do arquivo anexável. Consulte AppendOnlyFile para obter mais informações.

A tabela a seguir lista os métodos disponíveis na classe AppendOnlyFile.

Método	Descrição
Close()	Fecha o identificador de arquivo e libera recursos.
write(b)	Grava dados em bytes no arquivo e retorna a quantidade de bytes gravados.
write_from(b: str	bytes	Iterable[bytes]	IO[str]	IO[bytes])	Grava qualquer tipo de dado no arquivo e retorna o número de bytes gravados.

Para obter a definição completa do método AppendFile, acesse append_file.

AppendObject: API de upload por acréscimo da Basic Edition

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

Parâmetros de solicitação

Parâmetro	Tipo	Descrição
request	AppendObjectRequest	Parâmetros da solicitação. Consulte AppendObjectRequest para obter detalhes.

Valores de retorno

Tipo	Descrição
AppendObjectResult	Valor retornado pela operação. Consulte AppendObjectResult para obter mais informações.

Consulte append_object para obter a definição completa do método AppendObject.

Exemplos

(Recomendado) Usar AppendFile para upload por acréscimo

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.

Usar AppendObject para upload por acréscimo

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()

Cenários

Exibir barra de progresso no upload por acréscimo

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()

Referências

Para obter o código de exemplo completo de upload por acréscimo, consulte append_file.py e append_object.py.