O Guia de referência da API do AWS SDK para JavaScript V3 descreve em detalhes todas as operações da API para o AWS SDK para JavaScript versão 3 (V3).

Proteção da integridade de dados com as somas de verificação do Amazon S3

O Amazon Simple Storage Service (Amazon S3) oferece a capacidade de especificar uma soma de verificação ao fazer upload de um objeto. Quando você especifica uma soma de verificação, ela é armazenada com o objeto e pode ser validada quando o objeto é baixado.

As somas de verificação fornecem uma camada adicional de integridade de dados quando você transfere arquivos. Com somas de verificação, você pode verificar a consistência de dados confirmando que o arquivo recebido corresponde ao arquivo original. Para obter mais informações sobre as somas de verificação no Amazon S3, consulte o Guia do usuário do Amazon Simple Storage Service, incluindo os algoritmos compatíveis.

Você tem a flexibilidade de escolher o algoritmo mais adequado às suas necessidades e deixar que o SDK calcule a soma de verificação. Como alternativa, você pode fornecer um valor de soma de verificação pré-computado usando um dos algoritmos compatíveis.

Fazer upload de um objeto

Faça o upload de objetos no Amazon S3 usando o comando PutObject do S3Client. Use o parâmetro ChecksumAlgorithm do construtor do PutObjectRequest para habilitar o cálculo da soma de verificação e especificar o algoritmo. Consulte os algoritmos de soma de verificação compatíveis para obter os valores válidos.

O trecho de código a seguir mostra uma solicitação para carregar um objeto com uma soma de verificação CRC-32. Quando o SDK envia a solicitação, ele calcula a soma de verificação CRC-32 e carrega o objeto. O Amazon S3 armazena a soma de verificação com o objeto.

import { ChecksumAlgorithm, S3 } from "@aws-sdk/client-s3";

const client = new S3();
const response = await client.putObject({
  Bucket: "my-bucket",
  Key: "my-key",
  Body: "Hello, world!",
  ChecksumAlgorithm: ChecksumAlgorithm.CRC32,
});

Se você não fornecer um algoritmo de soma de verificação na solicitação, o comportamento da soma de verificação varia conforme a versão do SDK utilizado, conforme mostrado na tabela a seguir.

Comportamento da soma de verificação quando nenhum algoritmo de soma de verificação é fornecido

Se a soma de verificação calculada pelo SDK não corresponder à soma de verificação calculada pelo Amazon S3 ao receber a solicitação, um erro será retornado.

Usar um valor de soma de verificação pré-calculado

Um valor de soma de verificação pré-calculado fornecido com a solicitação desabilita a computação automática pelo SDK e, em vez disso, usa o valor fornecido.

O exemplo a seguir mostra uma solicitação com uma soma de verificação SHA-256 pré-calculada.

import { S3 } from "@aws-sdk/client-s3";
import { createHash } from "node:crypto";

const client = new S3();

const Body = "Hello, world!";
const ChecksumSHA256 = await createHash("sha256").update(Body).digest("base64");

const response = await client.putObject({
  Bucket: "my-bucket",
  Key: "my-key",
  Body,
  ChecksumSHA256,
});

Se o Amazon S3 determinar que o valor da soma de verificação está incorreto para o algoritmo especificado, o serviço retornará uma resposta de erro.

Carregamentos fracionados

Você também pode usar somas de verificação com carregamentos fracionados. O AWS SDK para JavaScript pode usar as opções de biblioteca Upload de @aws-sdk/lib-storage para usar somas de verificação com uploads fracionados.

import { ChecksumAlgorithm, S3 } from "@aws-sdk/client-s3";
import { Upload } from "@aws-sdk/lib-storage";
import { createReadStream } from "node:fs";

const client = new S3();
const filePath = "/path/to/file";
const Body = createReadStream(filePath);

const upload = new Upload({
  client,
  params: {
    Bucket: "my-bucket",
    Key: "my-key",
    Body,
    ChecksumAlgorithm: ChecksumAlgorithm.CRC32,
  },
});
await upload.done();