Ajout de données à un objet à l'aide du SDK OSS pour Python V2 - Object Storage Service

Précautions

L'exemple de code de cette rubrique utilise la région Chine (Hangzhou), dont l'ID est cn-hangzhou. Par défaut, un endpoint public est utilisé. Pour accéder à OSS depuis d'autres services Alibaba Cloud situés dans la même région, vous devez utiliser un endpoint interne. Pour plus d'informations sur les correspondances entre les régions et les endpoints OSS, consultez Régions et endpoints OSS.
Si l'objet n'existe pas, l'appel de la méthode de chargement par ajout crée un objet de type « appendable ».
Si l'objet existe :
- Si l'objet est de type « appendable » et que la position d'ajout spécifiée correspond à la longueur actuelle de l'objet, le contenu est ajouté à la fin de l'objet.
- Si l'objet est de type « appendable » mais que la position d'ajout spécifiée ne correspond pas à la longueur actuelle de l'objet, une exception PositionNotEqualToLength est levée.
- Si l'objet n'est pas de type « appendable » (par exemple, un objet standard chargé via un chargement simple), une exception ObjectNotAppendable est levée.

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations. Les utilisateurs RAM ou les rôles RAM associés à un compte Alibaba Cloud ne disposent d'aucune autorisation par défaut. Le compte Alibaba Cloud ou l'administrateur du compte doit accorder les autorisations d'opération via des politiques RAM ou une Bucket Policy.

Définitions des méthodes

Pour les scénarios de chargement par ajout, le SDK Python V2 ajoute la méthode AppendFile afin de simuler les opérations de lecture et d'écriture de fichiers sur les objets d'un bucket. Le tableau suivant décrit les méthodes AppendFile et AppendObject.

Méthode

Description

AppendFile

Offre les mêmes fonctionnalités que la méthode AppendObject.

Optimise la tolérance aux pannes pour les retransmissions après un échec.

AppendObject

Effectue un chargement par ajout. La taille finale de l'objet peut atteindre 5 GiB.

Prend en charge la validation des données CRC-64 (activée par défaut).

Prend en charge les barres de progression.

AppendFile : L'API de chargement par ajout de l'édition Premium

Appelez la méthode AppendFile pour charger des données en mode ajout. Si l'objet n'existe pas, un objet de type « appendable » est créé. Si l'objet existe mais n'est pas de type « appendable », une erreur est renvoyée.

Le code suivant montre la définition de la méthode AppendFile.

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

Paramètres de requête

Paramètre

Type

Description

bucket

str

Le nom du bucket.

key

str

Le nom de l'objet.

RequestPayer

str

Si le mode de paiement par demandeur est activé, définissez ce paramètre sur 'requester'.

CreateParameter

AppendObjectRequest

Les métadonnées de l'objet définies lors du premier chargement, y compris ContentType, Metadata, les permissions et la classe de stockage. Pour plus d'informations, consultez AppendObjectRequest.

Valeurs de retour

Type

Description

AppendOnlyFile

L'instance du fichier de type « appendable ». Pour plus d'informations, consultez AppendOnlyFile.

Le tableau suivant décrit les méthodes incluses dans la classe AppendOnlyFile.

Méthode

Description

Close()

Ferme le handle de fichier et libère les ressources.

write(b)

Écrit des données octet dans le fichier et renvoie le nombre d'octets écrits.

write_from(b: str

bytes

Iterable[bytes]

IO[str]

IO[bytes])

Écrit n'importe quelles données dans le fichier et renvoie le nombre d'octets écrits.

Pour la définition complète de la méthode AppendFile, consultez append_file.

AppendObject : L'API de chargement par ajout de l'édition Basic

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

Paramètres de requête

Paramètre

Type

Description

request

AppendObjectRequest

Les paramètres de la requête. Pour plus d'informations, consultez AppendObjectRequest.

Valeurs de retour

Type

Description

AppendObjectResult

La valeur de retour. Pour plus d'informations, consultez AppendObjectResult.

Pour la définition complète de la méthode AppendObject, consultez append_object.

Exemples

(Recommandé) Utiliser AppendFile pour effectuer un chargement par ajout

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.

Utiliser AppendObject pour effectuer un chargement par ajout

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

Scénarios

Afficher une barre de progression pour un chargement par ajout

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

Références

Pour l'exemple de code complet relatif au chargement par ajout, consultez append_file.py et append_object.py.