Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Transfert de fichiers entre Amazon RDS for Oracle et un compartiment Amazon S3
Pour transférer des fichiers entre une instance de base de données RDS for Oracle et un compartiment Amazon S3, vous pouvez utiliser le package Amazon RDS `rdsadmin_s3_tasks`. Vous pouvez compresser les fichiers avec GZIP lorsque vous les chargez et les décompresser lors du téléchargement.
**Topics**
+ [Exigences et limites relatives aux transferts de fichiers](#oracle-s3-integration.using.reqs)
+ [Chargement de fichiers depuis votre instance de base de données RDS for Oracle vers un compartiment Amazon S3](#oracle-s3-integration.using.upload)
+ [Téléchargement des fichiers d'un compartiment Amazon S3 vers une instance de base de données Oracle](#oracle-s3-integration.using.download)
+ [Surveillance du statut d'un transfert de fichiers](#oracle-s3-integration.using.task-status)
## Exigences et limites relatives aux transferts de fichiers
Avant de transférer des fichiers entre votre instance de base de données et un compartiment Amazon S3, notez les points suivants :
+ Le package `rdsadmin_s3_tasks` transfère des fichiers situés dans un répertoire unique. Vous ne pouvez pas inclure de sous-répertoires dans un transfert.
+ La taille maximale d'un objet dans un compartiment Amazon S3 est de 5 To.
+ Les tâches créées par `rdsadmin_s3_tasks` s’exécutent de manière asynchrone.
+ Vous pouvez charger des fichiers à partir du répertoire Data Pump, par exemple `DATA_PUMP_DIR`, ou de n’importe quel répertoire créé par l’utilisateur. Vous ne pouvez pas charger de fichiers à partir d’un répertoire utilisé par les processus d’arrière-plan Oracle, tel que les répertoires `adump`, `bdump` ou `trace`.
+ La limite de téléchargement est de 2 000 fichiers par appel de procédure pour `download_from_s3`. Si vous devez télécharger plus de 2 000 fichiers d'Amazon S3, divisez votre téléchargement en actions distinctes, avec un maximum de 2 000 fichiers par appel de procédure.
+ Si un fichier existe dans votre dossier de téléchargement et que vous tentez de télécharger un fichier portant le même nom, `download_from_s3` ignore le téléchargement. Pour supprimer un fichier du répertoire de téléchargement, utilisez la PL/SQL procédure [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF).
## Chargement de fichiers depuis votre instance de base de données RDS for Oracle vers un compartiment Amazon S3
Pour charger les fichiers de votre instance de base de données vers un compartiment Amazon S3, utilisez la procédure `rdsadmin.rdsadmin_s3_tasks.upload_to_s3`. Par exemple, vous pouvez charger les fichiers de sauvegarde Oracle Recovery Manager (RMAN) ou les fichiers Oracle Data Pump. Pour plus d'informations sur l'utilisation des objets, consultez le [Guide de l'utilisateur Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html). Pour plus d’informations sur les sauvegardes RMAN, consultez [Exécution des tâches RMAN courantes pour les instances de base de données Oracle](Appendix.Oracle.CommonDBATasks.RMAN.md).
La procédure `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` possède les paramètres suivants.
****
| Nom du paramètre | Type de données | Par défaut | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | obligatoire | Nom du compartiment Amazon S3 dans lequel charger les fichiers. |
| `p_directory_name` | VARCHAR2 | – | obligatoire | Nom de l'objet de répertoire Oracle à partir duquel les fichiers doivent être chargés. Le répertoire peut être n’importe quel objet de répertoire créé par l’utilisateur ou répertoire Data Pump, par exemple `DATA_PUMP_DIR`. Vous ne pouvez pas charger de fichiers à partir d’un répertoire utilisé par les processus d’arrière-plan, comme `adump`, `bdump` et `trace`. Vous pouvez uniquement charger les fichiers à partir du répertoire spécifié. Vous ne pouvez pas charger les fichiers des sous-répertoires dans le répertoire spécifié. |
| `p_s3_prefix` | VARCHAR2 | – | obligatoire | Préfixe de nom de fichier Amazon S3 en fonction duquel les fichiers sont chargés. Un préfixe vide charge tous les fichiers au niveau supérieur dans le compartiment Amazon S3 spécifié et n'ajoute pas de préfixe aux noms de fichier. Par exemple, si le préfixe est `folder_1/oradb`, les fichiers sont chargés dans `folder_1`. Dans ce cas, le préfixe `oradb` est ajouté à chaque fichier. |
| `p_prefix` | VARCHAR2 | – | obligatoire | Préfixe de nom de fichier que les noms de fichier doivent contenir pour être chargés. Un préfixe vide charge tous les fichiers du répertoire spécifié. |
| `p_compression_level` | NOMBRE | `0` | facultatif | Niveau de compression GZIP. La plage des valeurs valides est comprise entre `0` et `9` : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | facultatif | Paramètre de contrôle d'accès pour le compartiment. Les seules valeurs valides sont null ou `FULL_CONTROL`. Ce paramètre est requis uniquement si vous chargez des fichiers depuis un compte (compte A) dans un compartiment appartenant à un autre compte (compte B). Le compte B doit avoir un contrôle total des fichiers. |
La valeur renvoyée pour la procédure `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` est un ID de tâche.
L'exemple suivant télécharge tous les fichiers d'un répertoire `DATA_PUMP_DIR` dans le compartiment Amazon S3 nommé *amzn-s3-demo-bucket*. Les fichiers ne sont pas compressés.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
L’exemple suivant charge tous les fichiers ayant le préfixe `db` dans le répertoire`DATA_PUMP_DIR` du compartiment Amazon S3 nommé `amzn-s3-demo-bucket`. Amazon RDS applique le plus haut niveau de compression GZIP aux fichiers.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => 'db',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR',
p_compression_level => 9)
AS TASK_ID FROM DUAL;
```
L’exemple suivant charge tous les fichiers du répertoire `DATA_PUMP_DIR` dans le compartiment Amazon S3 nommé `amzn-s3-demo-bucket`. Les fichiers sont chargés dans un dossier `dbfiles`. Dans cet exemple, le niveau de compression GZIP est *1* le niveau de compression le plus rapide.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => 'dbfiles/',
p_directory_name => 'DATA_PUMP_DIR',
p_compression_level => 1)
AS TASK_ID FROM DUAL;
```
L’exemple suivant charge tous les fichiers du répertoire `DATA_PUMP_DIR` dans le compartiment Amazon S3 nommé `amzn-s3-demo-bucket`. Les fichiers sont chargés dans un dossier `dbfiles` et `ora` est ajouté au début de chaque nom de fichier. Aucune compression n'est appliquée.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => 'dbfiles/ora',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
L'exemple suivant suppose que la commande est exécutée dans le compte A, mais le compte B exige un contrôle total du contenu du compartiment. La commande `rdsadmin_s3_tasks.upload_to_s3` transfère tous les fichiers dans le répertoire `DATA_PUMP_DIR` du compartiment nommé `s3bucketOwnedByAccountB`. Le contrôle d'accès est défini sur `FULL_CONTROL` afin que le compte B puisse accéder aux fichiers du compartiment. Le niveau de compression GZIP est de*6*, qui équilibre la vitesse et la taille du fichier.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 's3bucketOwnedByAccountB',
p_prefix => '',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR',
p_bucket_owner_full_control => 'FULL_CONTROL',
p_compression_level => 6)
AS TASK_ID FROM DUAL;
```
Dans chaque exemple, l’instruction `SELECT` renvoie l’ID de la tâche dans un type de données `VARCHAR2`.
Vous pouvez afficher le résultat en affichant le fichier de sortie de la tâche.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Remplacez *`task-id`* par l'ID de tâche renvoyé par la procédure.
**Note**
Les tâches sont exécutées de manière asynchrone.
## Téléchargement des fichiers d'un compartiment Amazon S3 vers une instance de base de données Oracle
Pour télécharger les fichiers d'un compartiment Amazon S3 vers une instance RDS for Oracle, utilisez la procédure Amazon RDS `rdsadmin.rdsadmin_s3_tasks.download_from_s3`.
La procédure `download_from_s3` possède les paramètres suivants.
****
| Nom du paramètre | Type de données | Par défaut | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | Obligatoire | Nom du compartiment Amazon S3 à partir duquel télécharger les fichiers. |
| `p_directory_name` | VARCHAR2 | – | Obligatoire | Nom de l'objet de répertoire Oracle vers lequel les fichiers doivent être téléchargés. Le répertoire peut être n'importe quel objet de répertoire créé par l'utilisateur ou répertoire Data Pump, par exemple `DATA_PUMP_DIR`. |
| `p_error_on_zero_downloads` | VARCHAR2 | FALSE | Facultatif | Un indicateur qui détermine si la tâche génère une erreur quand aucun objet du compartiment Amazon S3 ne correspond au préfixe. Si ce paramètre n'est pas défini ou s'il est défini sur FALSE (par défaut), la tâche affiche un message indiquant qu'aucun objet n'a été trouvé, mais ne déclenche pas d'exception ni n'échoue. Si ce paramètre a pour valeur TRUE, la tâche lève une exception et échoue. Les exemples de spécifications de préfixe qui peuvent échouer aux tests de correspondance sont les espaces dans les préfixes, comme dans `' import/test9.log'`, et les différences de casse, comme dans `test9.log` et `test9.LOG`. |
| `p_s3_prefix` | VARCHAR2 | – | Obligatoire | Préfixe de nom de fichier que les noms de fichier doivent contenir pour être téléchargés. Un préfixe vide télécharge tous les fichiers au niveau le plus haut dans le compartiment Amazon S3 spécifié, mais pas les dossiers dans le compartiment. La procédure télécharge les objets Amazon S3 du dossier de premier niveau correspondant au préfixe. Les structures de répertoire imbriquées correspondant au préfixe spécifié ne sont pas téléchargées. Par exemple, supposons qu'un compartiment Amazon S3 ait la structure de dossiers `folder_1/folder_2/folder_3`. Vous spécifiez le préfixe `'folder_1/folder_2/'`. Dans ce cas, seuls les fichiers de `folder_2` sont téléchargés, et non ceux de `folder_1` ou `folder_3`. Si à la place vous spécifiez le préfixe `'folder_1/folder_2'`, tous les fichiers dans `folder_1` qui correspondent au préfixe `'folder_2'` sont téléchargés et aucun fichier dans `folder_2` n'est téléchargé. |
| `p_decompression_format` | VARCHAR2 | – | Facultatif | Format de décompression. Les valeurs valides sont `NONE` (pas de décompression) et `GZIP` (décompression). |
La valeur renvoyée pour la procédure `rdsadmin.rdsadmin_s3_tasks.download_from_s3` est un ID de tâche.
L'exemple suivant télécharge tous les fichiers du compartiment Amazon S3 nommé `amzn-s3-demo-bucket` vers le répertoire `DATA_PUMP_DIR`. Les fichiers n'étant pas compressés, aucune décompression n'est appliquée.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
L'exemple suivant télécharge tous les fichiers ayant le préfixe `db` dans le compartiment Amazon S3 nommé `amzn-s3-demo-bucket` du répertoire `DATA_PUMP_DIR`. Les fichiers étant compressés avec GZIP, la décompression est appliquée. Le paramètre `p_error_on_zero_downloads` active la vérification des erreurs de préfixe. Ainsi, si le préfixe ne correspond à aucun fichier du compartiment, la tâche lève une exception et échoue.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'db',
p_directory_name => 'DATA_PUMP_DIR',
p_decompression_format => 'GZIP',
p_error_on_zero_downloads => 'TRUE')
AS TASK_ID FROM DUAL;
```
L'exemple suivant télécharge tous les fichiers du dossier `myfolder/` du compartiment Amazon S3 nommé `amzn-s3-demo-bucket` vers le répertoire `DATA_PUMP_DIR`. Utilisez le paramètre `p_s3_prefix` pour spécifier le dossier Amazon S3. Les fichiers chargés sont compressés avec GZIP, mais ils ne sont pas décompressés pendant le téléchargement.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'myfolder/',
p_directory_name => 'DATA_PUMP_DIR',
p_decompression_format => 'NONE')
AS TASK_ID FROM DUAL;
```
L'exemple suivant télécharge le fichier `mydumpfile.dmp` du compartiment Amazon S3 nommé `amzn-s3-demo-bucket` dans le répertoire `DATA_PUMP_DIR`. Aucune décompression n'est appliquée.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'mydumpfile.dmp',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
Dans chaque exemple, l’instruction `SELECT` renvoie l’ID de la tâche dans un type de données `VARCHAR2`.
Vous pouvez afficher le résultat en affichant le fichier de sortie de la tâche.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Remplacez *`task-id`* par l'ID de tâche renvoyé par la procédure.
**Note**
Les tâches sont exécutées de manière asynchrone.
Vous pouvez utiliser la procédure Oracle `UTL_FILE.FREMOVE` pour supprimer les fichiers d'un répertoire. Pour plus d’informations, consultez [FREMOVE Procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) dans la documentation Oracle.
## Surveillance du statut d'un transfert de fichiers
Les tâches de transfert de fichiers publient des événements Amazon RDS lorsqu'elles démarrent et lorsqu'elles se terminent. Le message d'événement contient l'ID de tâche pour le transfert de fichiers. Pour plus d’informations sur l’affichage des événements, consultez [Affichage d’événements Amazon RDS](USER_ListEvents.md).
Vous pouvez consulter le statut d'une tâche en cours dans un fichier bdump. Les fichiers bdump se trouvent dans le répertoire `/rdsdbdata/log/trace`. Chaque nom de fichier bdump a le format suivant.
```
dbtask-task-id.log
```
Remplacez `task-id` par l'ID de la tâche que vous souhaitez surveiller.
**Note**
Les tâches sont exécutées de manière asynchrone.
Vous pouvez utiliser la procédure stockée `rdsadmin.rds_file_util.read_text_file` pour afficher le contenu des fichiers bdump. Par exemple, la requête suivante renvoie le contenu du fichier bdump `dbtask-1234567890123-1234.log`.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));
```
L'exemple suivant montre le fichier journal correspondant à un transfert ayant échoué.
```
TASK_ID
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1234567890123-1234
TEXT
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2023-04-17 18:21:33.993 UTC [INFO ] File #1: Uploading the file /rdsdbdata/datapump/A123B4CDEF567890G1234567890H1234/sample.dmp to Amazon S3 with bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.188 UTC [ERROR] RDS doesn't have permission to write to Amazon S3 bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.189 UTC [INFO ] The task failed.
```