Documentation Oracle Cloud Infrastructure

Prise en charge de l'API de compatibilité Amazon S3 Object Storage

Découvrez comment Object Storage prend en charge l'API de compatibilité Amazon S3.

La prise en charge de l'API de compatibilité Amazon S3 est fournie au niveau des buckets et au niveau des objets. L'API de compatibilité Amazon S3 prend en charge les ID de version.

Prise en charge SSE-C

A l'aide des en-têtes d'API facultatifs, vous pouvez fournir votre propre clé de cryptage AES 256 bits utilisée pour crypter et décrypter les objets téléchargés vers et depuis Object Storage.

Pour utiliser vos propres clés pour le cryptage côté serveur, indiquez les trois en-têtes de demande suivants avec les informations de clé de cryptage :

En-têtes Description API prises en charge
x-amz-server-side-encryption-customer-algorithm Indique "AES256" en tant qu'algorithme de cryptage.

GetObject

HeadObject

PutObject

InitiateMultipartUpload

UploadPart

x-amz-server-side-encryption-customer-key Indique la clé de cryptage 256 bits encodée en base64 à utiliser pour crypter ou décrypter les données.
x-amz-server-side-encryption-customer-key-md5 Indique le condensé MD5 128 bits encodé en base64 de la clé de cryptage. Cette valeur sert à vérifier l'intégrité de la clé de cryptage.

Object Storage dispose d'API distinctes pour copier des objets et copier des parties. Amazon S3 utilise la présence des En-têtes suivants dans PutObject et UploadPart pour déterminer les opérations d'impression. Pour copier un objet source crypté avec une clé SSE-C, vous devez indiquer ces trois en-têtes afin qu'Object Storage puisse décrypter l'objet.

En-têtes Description API prises en charge
x-amz-copy-source-server-side-encryption-customer-algorithm Indique "AES256" comme algorithme de cryptage à utiliser pour décrypter l'objet source.

PutObject

UploadPart

x-amz-copy-source-server-side-encryption-customer-key Indique la clé de cryptage 256 bits encodée en base64 à utiliser pour décrypter l'objet source.
x-amz-copy-source-server-side-encryption-customer-key-md5 Indique le condensé MD5 128 bits encodé en base64 de la clé de cryptage utilisée pour décrypter l'objet source.

Utilisation de kits SDK S3

Notez les points suivants concernant les fonctionnalités d'API qui ne sont pas prises en charge lors de l'utilisation des kits SDK et outils précédents :

  • AWS Signature Version 2 (SigV2) n'est pas pris en charge. Utilisez plutôt le mécanisme de signature AWS Signature Version 4.

Prise en charge du cryptage à l'aide de vos propres clés dans Vault

A l'aide des en-têtes d'API facultatifs, vous pouvez fournir votre propre clé de cryptage dans Vault pour crypter les objets téléchargés vers Object Storage.

Afin d'utiliser vos propres clés dans Vault pour le cryptage côté serveur, indiquez l'en-tête de demande suivant avec l'OCID de la clé dans Vault :

En-têtes Description API prises en charge
x-amz-server-side-encryption-aws-kms-key-id OCID de la clé existante dans Vault à utiliser pour crypter l'objet.

PutObject

InitiateMultipartUpload

UploadPart

Content-Encoding Prise en charge des en-têtes pour aws-chunked

Les clients compatibles S3 peuvent télécharger des objets à l'aide de aws-chunked dans l'en-tête Content-Encoding. Les téléchargements en une seule partie et les demandes UploadPart multipart sont pris en charge. Les charges utiles de transmission en continu AWS SigV4 sont prises en charge, notamment :

  • STREAMING-AWS4-HMAC-SHA256-PAYLOAD
  • STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER
  • STREAMING-UNSIGNED-PAYLOAD-TRAILER

Les clients peuvent envoyer des téléchargements aws-chunked avec des en-têtes HTTP Content-Length ou Transfer-Encoding: chunked. Les clients doivent fournir x-amz-decoded-content-length, que l'API de compatibilité Amazon S3 traite comme la taille réelle de l'objet ou de la pièce. Les signatures de bloc sont validées, de sorte que les chargements avec des données de bloc altérées ou des signatures de bloc non valides sont rejetés. Les signatures de bloc de fin sont validées pour les téléchargements en mode de fin signés. Les blocs de fin altérés sont donc également rejetés. La validation de somme de contrôle de fin est prise en charge pour :

  • CRC32
  • CRC32C
  • SHA256
  • CRC64NVME

Les non-concordances de checksum entraînent l'échec du téléchargement lors du traitement de la demande. Les checksums de fin SHA256 s'intègrent au comportement additional-checksum existant. Ils peuvent donc être conservés de manière cohérente avec la sémantique de checksum existante de l'API de compatibilité Amazon S3. Les checksums de fin CRC32, CRC32C et CRC64NVME sont de type vérification uniquement. Ils sont donc validés mais ne sont pas conservés en tant que métadonnées d'objet. Le comportement de téléchargement de l'API de compatibilité Amazon S3 existant pour les téléchargements non regroupés reste inchangé.

Prise en charge du total de contrôle pour S3 DeleteObjects / BulkDelete

Les versions plus récentes du kit SDK AWS n'ajoutent pas automatiquement l'en-tête Content-MD5 et sont passées à de nouveaux en-têtes (tels que x-amz-checksum-crc32) en tant que checksum par défaut. Le flux DeleteObjects / BulkDelete dans l'API de compatibilité Amazon S3 prend en charge x-amz-checksum-sha256 et x-amz-checksum-crc32c en tant qu'alternatives à Content-MD5 pour valider le corps de la demande.

Si la compatibilité amont est nécessaire avec les sommes de contrôle MD5, utilisez LegacyMd5Plugin afin que le kit SDK ajoute l'en-tête Content-MD5 comme précédemment.

Par exemple :

S3Client s3Client = S3Client.builder()
    .addPlugin(LegacyMd5Plugin.create())
    .endpointOverride(URI.create(endpoint))
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create(accessKey, secretKey)))
    .forcePathStyle(true)
    .build();
Remarque

Si vous indiquez checksumAlgorithm dans la demande, LegacyMd5Plugin omet l'en-tête Content-MD5.

Clients Amazon S3 pris en charge

Vous pouvez configurer différentes applications client pour qu'elles communiquent avec les points de terminaison compatibles Amazon S3 d'Object Stockage. Cette rubrique fournit des exemples de configuration pour les clients Amazon S3 pris en charge.

Kit SDK AWS pour Java

Le référentiel du kit SDK AWS pour Java, le téléchargement de fichiers et les liens vers la documentation sont disponibles sur GitHub : https://github.com/aws/aws-sdk-java.

Exemple de configuration du kit SDK AWS pour Java afin qu'il utilise Object Storage 


                // Put the Access Key and Secret Key here
                
AWSCredentialsProvider credentials = new AWSStaticCredentialsProvider(new BasicAWSCredentials(
 "gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID",
                         "7fa22331ebe62bf4605dc9a42aaeexampleuniqueID"))));

// Your namespace
String namespace = "namespace";

// The region to connect to
String region = "us-ashburn-1";

// Create an S3 client pointing at the region
String endpoint = String.format("%s.compat.objectstorage.%s.oraclecloud.com",namespace,region);
AwsClientBuilder.EndpointConfiguration endpointConfiguration = new AwsClientBuilder.EndpointConfiguration(endpoint, region);
AmazonS3 client = AmazonS3Client.builder()
 .standard()
 .withCredentials(credentials)
 .withEndpointConfiguration(endpointConfiguration)
 .disableChunkedEncoding()
 .enablePathStyleAccess()
 .build();

Kit SDK AWS pour JavaScript

Le référentiel du kit SDK AWS pour JavaScript, les liens vers la documentation et les instructions d'installation sont disponibles sur GitHub : https://github.com/aws/aws-sdk-js.

Voici un exemple de configuration du kit SDK AWS pour Javascript afin d'utiliser Object Storage 

s3 = new AWS.S3({
  region: 'us-ashburn-1',
  endpoint: 'https://' + mynamespace + '.compat.objectstorage.us-ashburn-1.oraclecloud.com',
  accessKeyId: 'gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID',
  secretAccessKey: '7fa22331ebe62bf4605dc9a42aaeexampleuniqueID',
  s3ForcePathStyle: true,
  signatureVersion: 'v4',
});

Kit SDK AWS pour Python (Boto3)

Le référentiel du kit SDK AWS pour Python (Boto3), les liens vers la documentation et les instructions d'installation sont disponibles sur GitHub : https://github.com/boto/boto3.

Exemple de configuration du kit SDK AWS pour que Python utilise Object Storage 

import boto3
  
s3 = boto3.resource(
    's3',
    aws_access_key_id="gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID",
    aws_secret_access_key="7fa22331ebe62bf4605dc9a42aaeexampleuniqueID",
    region_name="us-phoenix-1", # Region name here that matches the endpoint
    endpoint_url="https://mynamespace.compat.objectstorage.us-phoenix-1.oraclecloud.com" # Include your namespace in the URL
)
  
# Print out the bucket names
for bucket in s3.buckets.all():
    print bucket.name

Montage de buckets Object Storage à l'aide de s3fs

s3fs permet à Linux et à macOS de monter Object Storage en tant que système de fichiers. Le référentiel s3fs, les liens vers la documentation, les instructions d'installation et des exemples sont disponibles sur GitHub : https://github.com/s3fs-fuse/s3fs-fuse.

s3fs n'est pas adapté à toutes les applications. Tenez compte des restrictions suivantes :

  • Les services de stockage d'objet présentent une latence élevée par rapport aux systèmes de fichiers locaux pour le délai de réception du premier octet et ne disposent pas d'accès en écriture aléatoire. s3fs offre le meilleur débit sur les charges globales qui lisent uniquement les fichiers volumineux.
  • Vous ne pouvez pas mettre à jour partiellement un fichier. Par conséquent, la modification d'un seul octet nécessite le téléchargement de l'intégralité du fichier.
  • Les écritures aléatoires dans un fichier ou les ajouts à un fichier nécessitent la réécriture de l'intégralité du fichier.
  • s3fs ne prend pas en charge les téléchargements partiels. Par conséquent, même si vous ne voulez lire qu'un octet d'un fichier, vous devez télécharger l'intégralité du fichier.
  • s3fs ne prend pas en charge les copies de fichiers côté serveur. Les fichiers copiés doivent d'abord être téléchargés vers le client, puis téléchargés vers le nouvel emplacement.
  • Les opérations de métadonnées, telles que l'énumération des répertoires, présentent des performances médiocres en raison de la latence du réseau.
  • s3fs ne prend pas en charge les hard links ni les changements de nom atomiques de fichiers ou de répertoires.
  • s3fs ne fournit aucune coordination entre plusieurs clients montant le même bucket.

Procédure de montage d'un bucket Object Storage en tant que système de fichiers

  1. Suivez les instructions d'installation fournies sur GitHub : https://github.com/s3fs-fuse/s3fs-fuse.

    Si vous ne pouvez pas effectuer l'installation à l'aide d'un package prédéfini, consultez les instructions de compilation sur la page suivante : https://github.com/s3fs-fuse/s3fs-fuse/blob/master/COMPILATION.md.

  2. Saisissez les informations d'identification de paire clé d'accès/clé secrète dans un fichier d'informations d'identification ${HOME}/.passwd-s3fs : 
    cat ${HOME}/.passwd-s3fs
access_key:secret_key

    Par exemple :

    cat ${HOME}/.passwd-s3fs
gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID:7fa22331ebe62bf4605dc9a42aaeexampleuniqueID

    Définissez ensuite pour le fichier d'informations d'identification des droits d'accès de propriétaire uniquement :

    chmod 600 ${HOME}/.passwd-s3fs
  3. Créez un point de montage pour monter un bucket Object Storage :

    Où :

    • bucket_name est le nom du bucket à monter.
    • local_directory_name est le nom du répertoire local où monter le bucket.
    • namespace_name est le nom d'espace de noms unique généré par votre système et affecté à votre location au moment de sa création. Vous pouvez utiliser l'interface de ligne de commande ou la console pour obtenir votre nom d'espace de noms. Pour plus de détails, reportez-vous à Espaces de noms Object Storage.
    • region_ID est l'identificateur de la région où réside le bucket. Pour obtenir des détails, reportez-vous à Régions et domaines de disponibilité.
    • endpoint : si vous voulez monter un bucket créé dans votre région d'origine, vous n'avez pas besoin d'indiquer le paramètre endpoint. Si vous voulez monter un bucket créé dans une autre région, vous devez indiquer le paramètre endpoint.
  4. Pour monter automatiquement le bucket en tant que Système de fichiers à l'aide de s3fs au démarrage du système, ajoutez ce qui suit au fichier /etc/fstab : 
    
                                    bucket_name /path/to/local_directory_name fuse.s3fs use_path_request_style,passwd_file=/root/.s3fs-password,url=https://namespace_name.compat.objectstorage.region_ID.oraclecloud.com,endpoint=region_ID kernel_cache,multipart_size=128,parallel_count=50,multireq_max=100,max_background=1000,_netdev
  5. Pour vérifier le montage du bucket s3fs, exécutez la commande df -h. La sortie indique le nouveau point de montage du bucket. Accédez au nouveau point de montage et exécutez la commande ls pour répertorier tous les objets du bucket.

Procédure de dépannage du montage d'un bucket Object Storage

  • Si vous obtenez des erreurs d'autorisation, vérifiez vos stratégies IAM et assurez-vous que vous en avez une qui vous permet de monter un bucket en tant que système de fichiers. Par exemple :
    Allow group s3fsAdmins to manage object-family in compartment MyCompartment
  • Assurez-vous que l'URL de la commande s3fs contient le nom d'espace d'espace de noms correct. Pour vérifier votre nom d'espace de nom, reportez-vous à Espaces de noms Object Storage.
  • Assurez-vous que le bucket nommé que vous essayez de monter existe et qu'il se trouve dans un compartiment auquel vous avez accès. Utilisez l'une des méthodes suivantes pour vérifier le nom du bucket :
    • Connectez-vous à la console et recherchez le bucket nommé dans le compartiment auquel vous avez accès.
    • Utilisez la commande d'interface de ligne de commande oci os bucket list --namespace <object_storage_namespace> --compartment-id <target_compartment_id> .
  • Pour monter un bucket qui a été créé dans une région autre que votre région d'origine, vous devez indiquer cette autre région dans les paramètres url et endpoint.
  • Si vous montez un bucket en tant qu'utilisateur root, les autres utilisateurs ne peuvent pas répertorier les objets du bucket ni y accéder, sauf si vous ajoutez -o allow_other à la commande s3fs ou allow_other aux options de montage /etc/fstab. Vous pouvez également fournir des paramètres UID et GID spécifiques pour indiquer les détails d'accès utilisateur.

  • Si vous avez passé en revue et appliqué les solutions de dépannage et que vous devez contacter le support technique, réexécutez la commande de montage en mode DEBUG pour obtenir plus de détails sur l'échec. Ajoutez ce qui suit à la fin de la commande et enregistrez la sortie : 

    -o dbglevel=info -f -o curldbg

Procédure de démontage d'un bucket Object Storage à partir d'un système de fichiers

Exécutez la commande suivante, en indiquant le point de montage :
umount /path/to/<local_directory_name>

Interface de ligne de commande AWS