Trasferimento dei file tra Amazon RDS for Oracle e un bucket Amazon S3

Puoi utilizzare il package Amazon RDS rdsadmin_s3_tasks per trasferire file tra un'istanza database RDS per Oracle e un bucket Amazon S3. È possibile comprimere i file con GZIP al momento del caricamento e decomprimerli al momento del download.

Requisiti e limitazioni per i trasferimenti di file

Prima di trasferire i file tra un’istanza database e un bucket Amazon S3, tieni presente quanto segue:

• Il pacchetto rdsadmin_s3_tasks trasferisce i file presenti in una singola directory. Non puoi includere sottodirectory in un trasferimento.

• La dimensione massima dell'oggetto in un bucket Amazon S3 è di 5 TB.

• Le attività create da rdsadmin_s3_tasks vengono eseguite in modo asincrono.

• Puoi caricare i file dalla directory Data Pump, ad esempio DATA_PUMP_DIR, o da qualsiasi directory creata dall’utente. Non puoi caricare file da una directory utilizzata dai processi in background di Oracle, ad esempio le directory adump, bdump o trace.

• Per download_from_s3, il limite di scaricamento è pari a 2000 file per ogni chiamata della procedura. Se devi scaricare più di 2000 file da Amazon S3, suddividi il processo di scaricamento in operazioni distinte contenenti non più di 2000 file per chiamata.

• Se esiste un file nella cartella di scaricamento e si tenta di scaricare un file con lo stesso nome, download_from_s3 ignora lo scaricamento del file in questione. Per rimuovere un file dalla directory di download, utilizza la procedura PL/SQL UTL_FILE.FREMOVE.

Caricamento di file da un'istanza database Oracle a un bucket Amazon S3

Per caricare i file da un'istanza database a un bucket Amazon S3, utilizza la procedura rdsadmin.rdsadmin_s3_tasks.upload_to_s3. Ad esempio, è possibile caricare i file di backup di Oracle Recovery Manager (RMAN) o i file di Oracle Data Pump. Per informazioni sull'utilizzo di oggetti, consulta Guida per l'utente di Amazon Simple Storage Service. Per ulteriori informazioni sull'esecuzione dei backup RMAN, consulta Esecuzione di attività RMAN comuni per le istanze database Oracle.

La procedura rdsadmin.rdsadmin_s3_tasks.upload_to_s3 include i seguenti parametri.

Nome del parametro	Tipo di dati	Default	Campo obbligatorio	Descrizione
p_bucket_name	VARCHAR2	–	obbligatorio	Il nome del bucket Amazon S3 in cui caricare i file.
p_directory_name	VARCHAR2	–	obbligatorio	Il nome dell'oggetto directory Oracle da cui caricare i file. La directory può essere un qualsiasi oggetto directory creato dall'utente o directory Data Pump, come DATA_PUMP_DIR. Non puoi caricare file da una directory utilizzata dai processi in background, ad esempio adump, bdump o trace. Nota È possibile solo caricare i file dalla directory specificata. NOn è possibile caricare i file nelle sottodirectory nella directory specificata.
p_s3_prefix	VARCHAR2	–	obbligatorio	Un prefisso del nome file Amazon S3 con cui vengono caricati i file. Un prefisso vuoto carica tutti i file al livello superiore nel bucket Amazon S3 specificato e non aggiunge un prefisso ai nomi file. Ad esempio, se il prefisso è folder_1/oradb, i file vengono caricati su folder_1. In questo caso, il prefisso oradb viene aggiunto a ogni file.
p_prefix	VARCHAR2	–	obbligatorio	Un prefisso nome file con cui i nomi file devono corrispondere per essere caricati. Un prefisso vuoto carica tutti i file nella directory specificata.
p_compression_level	NUMBER	0	facoltativo	Il livello di compressione GZIP. I valori validi sono compresi tra 0 e 9. 0: nessuna compressione 1: compressione più veloce 9: compressione massima
p_bucket_owner_full_control	VARCHAR2	–	facoltativo	L'impostazione di controllo degli accessi per il bucket. Gli unici valori validi sono null o FULL_CONTROL. Questa impostazione è necessaria solo se si caricano file da un account (account A) in un bucket di proprietà di un account diverso (account B) e l'account B ha bisogno del pieno controllo dei file.

Il valore restituito per la procedura rdsadmin.rdsadmin_s3_tasks.upload_to_s3 è un ID attività.

L’esempio seguente carica tutti i file nella directory DATA_PUMP_DIR nel bucket Amazon S3 denominato amzn-s3-demo-bucket. I file non vengono compressi.

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'esempio seguente carica tutti i file con prefisso db nella directory DATA_PUMP_DIR nel bucket Amazon S3 denominato amzn-s3-demo-bucket. Amazon RDS applica ai file il livello di compressione GZIP più alto.

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'esempio seguente carica tutti i file nella directory DATA_PUMP_DIR nel bucket Amazon S3 denominato amzn-s3-demo-bucket. I file vengono caricati in una cartella dbfiles. In questo esempio, il livello di compressione GZIP è 1, che è il livello di compressione più veloce.

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'esempio seguente carica tutti i file nella directory DATA_PUMP_DIR nel bucket Amazon S3 denominato amzn-s3-demo-bucket. I file vengono caricati in una cartella dbfiles e ora viene aggiunto all'inizio di ogni nome file. Non viene applicata alcuna compressione.

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'esempio seguente presuppone che il comando sia eseguito nell'account A, ma l'account B richiede il pieno controllo del contenuto del bucket. Il comando rdsadmin_s3_tasks.upload_to_s3 trasferisce tutti i file nella directory DATA_PUMP_DIR al bucket denominato s3bucketOwnedByAccountB. Il controllo degli accessi è impostato su FULL_CONTROL in modo che l'account B possa accedere ai file nel bucket. Il livello di compressione GZIP è 6, ovvero il giusto compromesso tra velocità e dimensioni dei file.

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;

In ogni esempio, l'istruzione SELECT restituisce l'ID dell'attività in un tipo di dati VARCHAR2.

È possibile visualizzare il risultato visualizzando il file di output dell'attività.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

Sostituire task-id con l'ID attività restituito dalla procedura.

Nota

Le attività vengono eseguite in modo asincrono.

Download di file da un bucket Amazon S3 a un'istanza database Oracle

Per scaricare i file da un bucket Amazon S3 a un'istanza database RDS per Oracle, utilizza la procedura Amazon RDS rdsadmin.rdsadmin_s3_tasks.download_from_s3.

La procedura download_from_s3 include i seguenti parametri.

Nome del parametro	Tipo di dati	Default	Campo obbligatorio	Descrizione
p_bucket_name	VARCHAR2	–	Campo obbligatorio	Il nome del bucket Amazon S3 da cui scaricare i file.
p_directory_name	VARCHAR2	–	Campo obbligatorio	Il nome dell'oggetto directory Oracle su cui scaricare i file. La directory può essere un qualsiasi oggetto directory creato dall'utente o directory Data Pump, come DATA_PUMP_DIR.
p_error_on_zero_downloads	VARCHAR2	FALSE	Facoltativo	Un flag che determina se l'attività genera un errore quando nessun oggetto nel bucket Amazon S3 corrisponde al prefisso. Se questo parametro non è impostato o è impostato su FALSE (impostazione predefinita), l'attività stampa un messaggio che indica che non è stato trovato alcun oggetto, ma non genera un'eccezione o un errore. Se questo parametro è TRUE, l'attività genera un'eccezione e non riesce. Esempi di specifiche dei prefissi che possono non riuscire nei test di corrispondenza sono gli spazi nei prefissi, come in ' import/test9.log', e le mancate corrispondenze tra maiuscole e minuscole, come in test9.log e test9.LOG.
p_s3_prefix	VARCHAR2	–	Campo obbligatorio	Un prefisso nome file con cui i nomi file devono corrispondere per essere scaricati. Un prefisso vuoto scarica tutti i file di livello superiore nel bucket Amazon S3 specificato, ma non i file nelle cartelle nel bucket. La procedura scarica gli oggetti Amazon S3 solo dalla cartella di primo livello che corrisponde al prefisso. Le strutture directory nidificate corrispondenti al prefisso specificato non vengono scaricate. Ad esempio, si supponga che un bucket Amazon S3 abbia la struttura della cartella folder_1/folder_2/folder_3. Specifica il prefisso 'folder_1/folder_2/'. In questo caso, vengono scaricati solo i file in folder_2, non i file in folder_1 o folder_3. Se, invece, viene specificato il prefisso 'folder_1/folder_2', tutti i file in folder_1 che corrispondono al prefisso 'folder_2' vengono scaricati, mentre i file in folder_2 non vengono scaricati.
p_decompression_format	VARCHAR2	–	Facoltativo	Il formato di decompressione. I valori validi sono NONE per non eseguire la decompressione e GZIP per eseguire la decompressione.

Il valore restituito per la procedura rdsadmin.rdsadmin_s3_tasks.download_from_s3 è un ID attività.

L'esempio seguente scarica tutti i file nel bucket Amazon S3 denominato amzn-s3-demo-bucket nella directory DATA_PUMP_DIR. I file non sono compressi, quindi non viene applicata alcuna decompressione.

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'esempio seguente scarica tutti i file con prefisso db nel bucket Amazon S3 denominato amzn-s3-demo-bucket nella directory DATA_PUMP_DIR. I file non sono compressi, quindi non viene applicata alcuna decompressione. Il parametro p_error_on_zero_downloads attiva il controllo degli errori dei prefissi, quindi se il prefisso non corrisponde a nessun file nel bucket, l'attività genera un'eccezione e non riesce.

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'esempio seguente scarica tutti i file nella cartella myfolder/ nel bucket Amazon S3 denominato amzn-s3-demo-bucket nella directory DATA_PUMP_DIR. Utilizzare il parametro p_s3_prefix per specificare la cartella Amazon S3. I file caricati vengono compressi con GZIP, ma non vengono decompressi durante il download.

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'esempio seguente scarica il file mydumpfile.dmp nel bucket Amazon S3 denominato amzn-s3-demo-bucket nella directory DATA_PUMP_DIR. Non viene applicata alcuna decompressione.

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;

In ogni esempio, l'istruzione SELECT restituisce l'ID dell'attività in un tipo di dati VARCHAR2.

È possibile visualizzare il risultato visualizzando il file di output dell'attività.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

Sostituire task-id con l'ID attività restituito dalla procedura.

Nota

Le attività vengono eseguite in modo asincrono.

Per rimuovere i file da una directory, è possibile utilizzare la procedura Oracle UTL_FILE.FREMOVE. Per ulteriori informazioni, consulta la sezione relativa alla Procedura FREMOVE nella documentazione di Oracle.

Monitoraggio dello stato di un file transfer

Le attività di file transfer pubblicano gli eventi Amazon RDS al loro inizio e al completamento. Il messaggio dell'evento contiene l'ID dell'attività per il trasferimento file. Per informazioni sulla visualizzazione degli eventi, consultare Visualizzazione di eventi Amazon RDS.

È possibile visualizzare lo stato di un'attività in corso in un file bdump. I file bdump si trovano nella directory /rdsdbdata/log/trace. Il nome del file bdump ha il formato che segue.

dbtask-task-id.log

Sostituire task-id con l'ID dell'attività da monitorare.

Nota

Le attività vengono eseguite in modo asincrono.

Puoi usare la procedura memorizzata in rdsadmin.rds_file_util.read_text_file per visualizzare i contenuti dei file bdump. Ad esempio, la query seguente restituisce i contenuti del file bdump dbtask-1234567890123-1234.log.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));

L'esempio seguente mostra il file di log di un trasferimento non riuscito.

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.