Carga por anexión (Harmony SDK) - Object Storage Service - Centro de documentación de Alibaba Cloud

Puede agregar contenido a objetos anexables existentes. Este tema describe cómo cargar contenido por anexión mediante el SDK de Object Storage Service (OSS) para Harmony 2.0.

Notas de uso

Para obtener más información sobre regiones y endpoints, consulte Regions and endpoints.
Si el objeto al que desea agregar contenido no existe, se crea un objeto anexable al invocar la operación de carga por anexión.
Si el archivo ya existe:
- Si el objeto es anexable y la posición especificada para iniciar la anexión coincide con la longitud actual del objeto, el contenido se agrega al final de este.
- Si el objeto es anexable pero la posición especificada para iniciar la anexión no coincide con la longitud actual del objeto, se devuelve el error PositionNotEqualToLength.
- Si el objeto no es anexable, se devuelve el error ObjectNotAppendable.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene todos los permisos. Los usuarios o roles de RAM bajo una cuenta de Alibaba Cloud no tienen ningún permiso predeterminado. La cuenta de Alibaba Cloud o el administrador de la cuenta deben otorgar los permisos de operación correspondientes mediante RAM policies o Bucket Policy.

API

Action

Descripción

AppendObject

oss:PutObject

Esta operación permite cargar un objeto agregándolo a uno existente.

oss:PutObjectTagging

Este permiso es obligatorio si, al cargar un objeto por anexión, se especifican etiquetas de objeto mediante x-oss-tagging.

Código de ejemplo

A continuación se muestra un ejemplo de cómo cargar contenido por anexión:

import Client, {RequestError } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append the content to an OSS object. 
 * Use the appendObject method to append data to a specific object in a specific bucket. 
 */
const appendObject = async () => {
  try {
    // Use the appendObject method to append data to a specific object in a specific bucket.
    // Do not specify the position parameter when you create an appendable object for the first time. Then, specify the position parameter when you perform the append upload operation.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'hello world' // Specify the data that you want to append. In this example, a simple string is appended.
    });

    // Display the append upload results.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the appendObject function to perform the append upload operation.
appendObject();

Escenarios comunes

Anexar un archivo local a un objeto

El siguiente código de ejemplo muestra cómo anexar un archivo local a un objeto:

import Client, { RequestError } from '@aliyun/oss';
import { fileIo as fs } from '@kit.CoreFileKit';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append content to the object using the local file path. 
 * Use the appendObject method to append the content of a local file to an object in a specific bucket. 
 */
const appendObjectByFile = async () => {
  // Open and read the local file.
  const file=await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // Specify the path of the local file.

  try {
    // Use the appendObject method to append the content of a local file to an object in a specific bucket.
    // Do not specify the position parameter when you create an appendable object for the first time. Then, specify the position parameter when you perform the append upload operation.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: file, // Specify the local file that you want to append.
    });

    // Display the append upload results.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  } finally {
    // Close the local file after the operation is complete.
    await fs.close(file);
  }
};

// Call the appendObjectByFile function to perform the append upload operation.
appendObjectByFile();

Especificar la posición de inicio de la anexión

El siguiente código de ejemplo muestra cómo especificar la posición desde la cual comienza la operación de anexión:

import Client, { RequestError, EHeaderKey } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append the content to an OSS object and specify the position from which the append operation starts. 
 * Use the appendObject method to append data blocks to a specific object in a specific bucket and specify the position from which the append operation starts. 
 */
const appendObjectWithPosition = async () => {
  try {
    // Call the appendObject method to start the first append upload to append the initial data block.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'first chunk data', // The first data block.
    });

    // Display the first append upload results.
    console.log(JSON.stringify(res));

    /* Obtain the position from which the next append operation starts.
    const nextAppendPosition = Number(res.origRes.headers[EHeaderKey.X_OSS_NEXT_APPEND_POSITION]);

    // Call the appendObject method to start the second append upload to append the second data block.
    const res1 = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'second chunk data', // The second data block.
      position: nextAppendPosition, // The append position from which the second append starts.
    });

    // Display the second append upload results.
    console.log(JSON.stringify(res1));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the appendObjectWithPosition function to perform the append upload operation to append data blocks.
appendObjectWithPosition();