Utilizzare le credenziali del servizio cloud memorizzate per accedere al servizio cloud per il caricamento dei dati, per eseguire query sui dati esterni che risiedono nel cloud o per altri casi quando si utilizzano le procedure DBMS_CLOUD con un parametro credential_name. Questa procedura è sovraccaricata:

• Utilizzare i parametri relativi a Oracle Cloud Infrastructure, tra cui user_ocid, tenancy_ocid, private_key e fingerprint solo quando si utilizza l'autenticazione delle chiavi di firma di Oracle Cloud Infrastructure.

• Utilizzare il parametro params per uno dei seguenti:

  • Credenziali Amazon Resource Names (ARNs)

  • Google Analytics o Google BigQuery credenziali

  • Credenziali del segreto vault da utilizzare con un vault supportato:

    • Oracle Cloud Infrastructure Vault
    • Vault delle chiavi di Azure
    • AWS Secrets Manager
    • Gestore segreti GCP

Sintassi

DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      username          IN VARCHAR2,
      password          IN VARCHAR2 DEFAULT NULL,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      user_ocid         IN VARCHAR2,
      tenancy_ocid      IN VARCHAR2,
      private_key       IN VARCHAR2,
      fingerprint       IN VARCHAR2,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name  IN VARCHAR2,
      params           IN CLOB DEFAULT);

Parametri

Note per uso

• Questa operazione memorizza le credenziali nel database in formato cifrato.

• È possibile visualizzare le credenziali nello schema eseguendo una query sulla tabella user_credentials.

• È possibile visualizzare i commenti delle credenziali nello schema eseguendo una query sulla tabella user_credentials. Ad esempio:

  SELECT comments FROM user_credentials
          WHERE credential_name = 'MY_CRED';

• L'utente ADMIN può visualizzare tutte le credenziali eseguendo una query sulla tabella dba_credentials.

• È necessario creare le credenziali una sola volta a meno che le credenziali del servizio cloud non vengano modificate. Dopo aver memorizzato le credenziali, è possibile utilizzare lo stesso nome di credenziale per le procedure DBMS_CLOUD che richiedono un parametro credential_name.

• Questa procedura è sovraccaricata. Se si fornisce uno degli attributi di autenticazione basati su chiave, user_ocid, tenancy_ocid, private_key o fingerprint, si presume che la chiamata sia una credenziale basata su chiave di firma di Oracle Cloud Infrastructure.

• È possibile elencare le credenziali dalla vista ALL_CREDENTIALS. Ad esempio, eseguire il comando seguente per visualizzare le credenziali:

  SELECT credential_name, username, comments FROM all_credentials;

Credenziali Oracle Cloud Infrastructure (token di autorizzazione)

Per Oracle Cloud Infrastructure, username è il nome utente di Oracle Cloud Infrastructure. password è il token di autenticazione di Oracle Cloud Infrastructure. Vedere Utilizzo dei token di autenticazione.

Ad esempio:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'adb_user@example.com',
    password => 'password' );
END;
/

Usare le credenziali basate su token di autenticazione quando si autenticano le chiamate a OCI Object Storage. Per le chiamate a qualsiasi altro tipo di servizio cloud Oracle Cloud Infrastructure, utilizza le credenziali basate sulla chiave di firma di Oracle Cloud Infrastructure.

Per lo storage degli oggetti OCI, il valore del parametro username deve includere il dominio di Identity e il nome utente del profilo. Puoi trovare il dominio di Identity associato a un utente nella console di Oracle Cloud Infrastructure.

Ad esempio:

oracleidentitycloudservice/adb_user@example.com

Con il dominio di Identity predefinito non è necessario includere il nome di dominio Default. Ad esempio:

adb_user@example.com

Credenziali basate su chiave di firma Oracle Cloud Infrastructure

Utilizzare i parametri correlati alla chiave di firma di Oracle Cloud Infrastructure, tra cui user_ocid, tenancy_ocid, private_key e fingerprint con l'autenticazione delle chiavi di firma di Oracle Cloud Infrastructure.

Ad esempio:

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => ‘OCI_KEY_CRED’,
       user_ocid       => ‘ocid1.user.oc1..aaaaaaaauq54mi7zdyfhw33ozkwuontjceel7fok5nq3bf2vwetkpqsoa’,
       tenancy_ocid    => ‘ocid1.tenancy.oc1..aabbbbbbaafcue47pqmrf4vigneebgbcmmoy5r7xvoypicjqqge32ewnrcyx2a’,
       private_key     => ‘MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=’,
       fingerprint     => ‘f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27’);
END;
/

Le chiavi private generate con una password non sono supportate. È necessario generare la chiave privata senza una passphrase. Per ulteriori informazioni, vedere Come generare una chiave di firma API.

Credenziali Oracle Cloud Infrastructure Object Storage Classic

Se i file di origine risiedono in Oracle Cloud Infrastructure Object Storage Classic, username è il nome utente Oracle Cloud Infrastructure Classic e password è la password Oracle Cloud Infrastructure Classic.

Credenziali Amazon Web Services (AWS)

Se i file di origine risiedono in Amazon S3 o si sta chiamando un'API AWS, username è l'ID della chiave di accesso AWS e password è la chiave di accesso segreta AWS. Vedere AWS Identity and Access Management.

Credenziali Microsoft Azure

Se i file di origine risiedono in Azure Blob Storage o in Azure Data Lake Storage o si sta chiamando un'API di Azure, username è il nome dell'account di memorizzazione di Azure e password è una chiave di accesso dell'account di memorizzazione di Azure. Vedere Informazioni sugli account di memorizzazione di Azure.

Credenziali compatibili con Amazon S3

Credenziali AWS Amazon Resource Names (ARN)

Se i file di origine risiedono in Amazon S3 o si sta chiamando un'API AWS, utilizzare params per specificare i parametri per i nomi delle risorse Amazon (ARN).

Ad esempio:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name      => 'MY_CRED',
        params               => JSON_OBJECT(
               'aws_role_arn'      value 'arn:aws:iam::123456:role/AWS_ROLE_ARN',
               'external_id_type'  value 'database_ocid'));
END;
/

GitHub Token di accesso personale

Se i file di origine risiedono in un repository GitHub o si sta chiamando un'interfaccia API GitHub, username è l'indirizzo di posta elettronica GitHub e password è il token di accesso personale GitHub. Per ulteriori informazioni, vedere Creazione di un token di accesso personale.

Ad esempio:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'MY_GITHUB_CRED',
    username => 'user@example.com',
    password => 'your_personal_access_token' );
END;
/

Credenziali Google Analytics o Google BigQuery

Se si accede a Google Analytics o Google BigQuery, utilizzare il parametro params per specificare i parametri delle credenziali OAuth 2.0 di Google.

Ad esempio:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
      credential_name => 'GOOGLE_BIGQUERY_CRED',
      params => JSON_OBJECT('gcp_oauth2' value 
                                  JSON_OBJECT(
                                       'client_id'     value 'client_id',
                                       'client_secret' value 'client_secret',
                                       'refresh_token' value 'refresh_token' )));
END;
/

Credenziali del segreto vault con Oracle Cloud Infrastructure Vault

Per creare le credenziali del segreto vault con Oracle Cloud Infrastructure Vault, utilizzare il parametro params per specificare i parametri necessari:

• username: specifica il nome utente di qualsiasi tipo di credenziale nome utente/password, ad esempio il nome utente della password di OCI Swift. Ad esempio, se si dispone di una credenziale Swift con nome utente "scott" e password "password", specificare "scott" come parametro username.

• secret_id: è l'ID del segreto vault. Specificare il valore secret_id come OCID segreto vault. Per ulteriori informazioni, vedere Panoramica del vault.

• region: è un parametro facoltativo che specifica l'identificativo dell'area cloud oracle. L'area, se specificata, indica la posizione in cui si trova il segreto di Oracle Cloud Infrastructure Vault.

  Per impostazione predefinita, CREATE_CREDENTIAL utilizza il file region mappato dalla chiave area in secret_id. Un esempio di area è us-ashburn-1.

  Per un elenco completo delle aree, consulta la sezione relativa alle aree e ai domini di disponibilità.

Ad esempio:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_SECRET_CRED',
    params => JSON_OBJECT( 
                'username'   value 'scott',
                'region'     value 'us-ashburn-1',
                'secret_id'  value 'ocid1.vaultsecret.co1.ap-mumbai-1.example..aaaaaaaauq5ok5nq3bf2vwetkpqsoa'));
END;
/

Note per l'uso di un segreto di Oracle Cloud Infrastructure Vault per memorizzare i segreti del vault:

• Quando si utilizza Oracle Cloud Infrastructure Vault, nell'istanza di Autonomous Database è necessario abilitare l'autenticazione del principal con DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL.

• In Oracle Cloud Infrastructure è necessario specificare un criterio per il principal risorsa per accedere al segreto.

Per creare una credenziale segreta del vault, è necessario disporre del privilegio EXECUTE nel package DBMS_CLOUD.

Credenziali del segreto vault con Azure Key Vault

Per creare le credenziali di Key Vault di Azure, utilizzare il parametro params per specificare i parametri richiesti:

• username: specifica il nome utente associato alla chiave.

• secret_id: specifica il nome del segreto.

• azure_vault_name: specifica il nome del vault in cui si trova il segreto.

Per ulteriori informazioni, vedere Creare un vault di chiavi.

Per creare una credenziale segreta del vault, è necessario disporre del privilegio EXECUTE nel package DBMS_CLOUD.

Credenziali segrete del vault con AWS Secrets Manager

Per creare le credenziali segrete del vault con AWS Secrets Manager, utilizzare il parametro params per specificare i parametri richiesti:

• username: specifica la chiave di accesso di AWS Secrets Manager.

• secret_id: AWS Secrets Manager è AWS ARN.

• region: (facoltativo) specifica l'area di servizio AWS in cui si trovano il vault e il segreto. Un esempio della regione AWS è "noi-est-2". Il valore predefinito region è l'area specificata con l'ARN nel parametro secret_id.

  Per ulteriori informazioni, vedere Gestione delle aree AWS.

  Per creare una credenziale segreta del vault, è necessario disporre del privilegio EXECUTE nel package DBMS_CLOUD.

Credenziali del segreto vault con GCP Secret Manager

Per creare le credenziali di GCP Secret Manager, utilizzare il parametro params per specificare i parametri richiesti:

• username: specifica il nome utente associato al segreto.

• secret_id: è il nome segreto.

• gcp_project_id: specifica l'ID del progetto in cui si trova il segreto.

Per ulteriori informazioni, vedere Gestione segreta.

Per creare una credenziale segreta del vault, è necessario disporre del privilegio EXECUTE nel package DBMS_CLOUD.

Sintassi

DBMS_CLOUD.DROP_CREDENTIAL (
   credential_name     IN VARCHAR2);

Parametri

Questa procedura consente di aggiornare immediatamente il segreto vault di una credenziale segreta del vault per ottenere la versione più recente del segreto vault per il file credential_name specificato.

Sintassi

DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL (
    credential_name   IN VARCHAR2);

Parametri

Note per uso

• L'utente ADMIN può visualizzare tutte le credenziali eseguendo una query sulla tabella dba_credentials.

• È possibile elencare le credenziali dalla vista ALL_CREDENTIALS. Ad esempio, eseguire il comando seguente per visualizzare le credenziali:

  SELECT credential_name, username, comments FROM all_credentials;

Esempio

BEGIN
  DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL(
     credential_name => 'AZURE_SECRET_CRED'); 
END;
/

Utilizzare le credenziali memorizzate per il caricamento dei dati, per eseguire query sui dati esterni che risiedono nel cloud o ovunque si utilizzino le procedure DBMS_CLOUD con un parametro credential_name.

Sintassi

DBMS_CLOUD.UPDATE_CREDENTIAL (
    credential_name   IN VARCHAR2,
    attribute         IN VARCHAR2,
    value             IN VARCHAR2);

Parametri

Note per uso

• Il valore del nome utente distingue tra casi. Non può contenere virgolette o spazi.

• L'utente ADMIN può visualizzare tutte le credenziali eseguendo una query su dba_credentials.

• È necessario creare le credenziali una sola volta a meno che le credenziali del servizio cloud non vengano modificate. Dopo aver memorizzato le credenziali, è possibile utilizzare lo stesso nome di credenziale per le procedure DBMS_CLOUD che richiedono un parametro credential_name.

• È possibile elencare le credenziali dalla vista ALL_CREDENTIALS. Ad esempio, eseguire il comando seguente per visualizzare le credenziali:

  SELECT credential_name, username, comments FROM all_credentials;

Esempi

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'OBJ_STORE_CRED',
     attribute => 'PASSWORD',
     value => 'password'); 
END;
/

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'ARN_CRED',
     attribute => 'aws_role_arn',
     value => 'NEW_AWS_ARN'); 
END;
/

Sintassi

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Esempio

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'  
            );
END;
/

Sintassi

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2,
    field_list        IN CLOB,
    format            IN CLOB);

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB DEFAULT NULL,
    schema_name       IN VARCHAR2 DEFAULT NULL,
    field_list        IN CLOB DEFAULT NULL,
    format            IN CLOB DEFAULT NULL
    operation_id      OUT NOCOPY NUMBER);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Nota per l'uso

Il delimitatore di record predefinito è detected newline. Con detected newline, DBMS_CLOUD tenta di trovare automaticamente il carattere di nuova riga corretto da utilizzare come delimitatore di record. DBMS_CLOUD cerca innanzitutto il carattere di nuova riga di Windows \r\n. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se un carattere di nuova riga di Windows non viene trovato, DBMS_CLOUD cerca il carattere di nuova riga UNIX/Linux \n e, se ne trova uno, utilizza \n come delimitatore di record per tutti i file della procedura. Se i file di origine utilizzano una combinazione di diversi delimitatori di record, potrebbe verificarsi un errore, ad esempio "KUP-04020: found record longer than buffer size supported". In questo caso, è necessario modificare i file di origine per utilizzare lo stesso delimitatore di record oppure specificare solo i file di origine che utilizzano lo stesso delimitatore di record.

Per informazioni sull'opzione di formato recorddelmiter, vedere DBMS_CLOUD Package Format Options.

Esempi

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );
END;
/

BEGIN
 DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
    format => json_object('delimiter' value ',')
 );
END;
/

BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

Sintassi

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2 DEFAULT,
    field_list        IN CLOB DEFAULT,
    format            IN CLOB DEFAULT);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Note per uso

• Come per altri file di dati, i caricamenti dei dati Avro, ORC e Parquet generano log visualizzabili nelle tabelle dba_load_operations e user_load_operations. Ogni operazione di caricamento aggiunge un record a dba[utente]_load_operations che indica la tabella contenente i log.

  La tabella di log fornisce informazioni di riepilogo sul caricamento.

• Per Avro, ORC o Parquet, quando il parametro format type è impostato sul valore avro, orc o parquet, la tabella BADFILE_TABLE è sempre vuota.

  • Per i file Parquet, gli errori di vincolo PRIMARY KEY restituiscono un errore ORA.

  • Se i dati di una colonna riscontrano un errore di conversione, ad esempio la colonna di destinazione non è sufficientemente grande da contenere il valore convertito, il valore della colonna viene impostato su NULL. Questo non produce un record rifiutato.

Il bucket o la cartella di origine e destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un altro provider.

Quando l'origine e la destinazione si trovano in aree di memorizzazione degli oggetti distinte o hanno account diversi con lo stesso provider cloud, è possibile assegnare nomi di credenziali separati per le posizioni di origine e destinazione.

Il nome della credenziale di origine viene utilizzato per impostazione predefinita anche dalla posizione di destinazione quando non viene fornito il nome della credenziale di destinazione.

Sintassi

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Parametri

Esempio

BEGIN 
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Sintassi

DBMS_CLOUD.CREATE_CLOUD_TABLE (
    table_name       IN VARCHAR2,
    column_list      IN CLOB,
    params           IN CLOB);

Parametri

Note per uso

• Attributi DEFAULT: la clausola column_list può includere la clausola DEFAULT, che funziona come la clausola DEFAULT in un normale CREATE TABLE. Per informazioni sul funzionamento della clausola DEFAULT, vedere CREATE TABLE.

• Utilizzare DROP TABLE per eliminare una tabella cloud. Le tabelle cloud non supportano il cestino.

  Ad esempio:

  DROP TABLE CLOUD_TAB1; 

• È possibile concedere i privilegi SELECT, INSERT e UPDATE per una tabella cloud. Non è possibile concedere altri privilegi a una tabella cloud.

  Per ulteriori informazioni, vedere Configurazione dell'autorizzazione di privilegi e ruoli.

Esempi

EXEC DBMS_CLOUD.CREATE_CLOUD_TABLE( 'CLOUD_TAB1', 'I INTEGER, J INTEGER' );

BEGIN
  DBMS_CLOUD.CREATE_CLOUD_TABLE(
   table_name  => 'CLOUD_TABLE_WITH_DEFAULT',
   column_list => 'I INTEGER,
                   A VARCHAR2(32) DEFAULT ''ABC''' );
END;
/

Sintassi

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);


DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    file_uri_list        IN VARCHAR2,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Note per uso

• Non è possibile richiamare questa procedura con i parametri partitioning_clause e file_uri_list.

• La specifica del parametro column_list è facoltativa con i file di dati strutturati, inclusi i file di dati Avro, Parquet o ORC. Se column_list non viene specificato, l'opzione partition_columns del parametro format deve includere sia name che type.

• Il parametro column_list è obbligatorio con file di dati non strutturati, ad esempio file di testo CSV.

• La procedura DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE supporta i file partizionati esterni nei servizi di storage degli oggetti cloud supportati, tra cui:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage o Azure Data Lake Storage

  • Amazon S3

  • Compatibile con Amazon S3, tra cui Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repository

  Vedere DBMS_CLOUD Formati URI per ulteriori informazioni.

• La procedura DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE supporta file partizionati esterni nelle directory (file system locale o di rete).

• Quando si chiama DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE con il parametro file_uri_list, i tipi per le colonne specificate nel nome file dell'area di memorizzazione degli oggetti cloud devono essere uno dei seguenti:

  VARCHAR2(n)
  NUMBER(n)
  NUMBER(p,s)
  NUMBER
  DATE
  TIMESTAMP(9)

• Il delimitatore di record predefinito è detected newline. Con detected newline, DBMS_CLOUD tenta di trovare automaticamente il carattere di nuova riga corretto da utilizzare come delimitatore di record. DBMS_CLOUD cerca innanzitutto il carattere di nuova riga di Windows \r\n. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se un carattere di nuova riga di Windows non viene trovato, DBMS_CLOUD cerca il carattere di nuova riga UNIX/Linux \n e, se ne trova uno, utilizza \n come delimitatore di record per tutti i file della procedura. Se i file di origine utilizzano una combinazione di diversi delimitatori di record, potrebbe verificarsi un errore, ad esempio "KUP-04020: found record longer than buffer size supported". In questo caso, è necessario modificare i file di origine per utilizzare lo stesso delimitatore di record oppure specificare solo i file di origine che utilizzano lo stesso delimitatore di record.

  Per informazioni sull'opzione di formato recorddelmiter, vedere DBMS_CLOUD Package Format Options.

• Le tabelle partizionate esterne create con DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE includono due colonne invisibili file$path e file$name. Queste colonne consentono di identificare il file da cui proviene un record.

  • file$path: specifica il testo del percorso del file fino all'inizio del nome dell'oggetto.

  • file$name: specifica il nome dell'oggetto, incluso tutto il testo che segue il nome del bucket.

Esempi

Esempio di utilizzo del parametro partitioning_clause:

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',  
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location 
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/  


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR 
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );                       
END;                     
/

Esempio di utilizzo dei parametri file_uri_list e column_list con file di dati non strutturati:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv', 
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)', 
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/ 

Esempio di utilizzo del parametro file_uri_list senza il parametro column_list con file di dati strutturati:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          => 
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value 
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

Sintassi

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Note per uso

• La procedura DBMS_CLOUD.CREATE_EXTERNAL_TABLE supporta i file partizionati esterni nelle origini di storage degli oggetti cloud supportate, tra cui:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage o Azure Data Lake Storage

  • Amazon S3

  • Compatibile con Amazon S3, tra cui Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repository

  • Oracle Cloud Infrastructure Object Storage con URL collegamento ipertestuale tabella

  La credenziale è una proprietà a livello di tabella, pertanto i file esterni devono trovarsi nella stessa area di memorizzazione degli oggetti.

  Vedere DBMS_CLOUD Formati URI per ulteriori informazioni.

• Il delimitatore di record predefinito è detected newline. Con detected newline, DBMS_CLOUD tenta di trovare automaticamente il carattere di nuova riga corretto da utilizzare come delimitatore di record. DBMS_CLOUD cerca innanzitutto il carattere di nuova riga di Windows \r\n. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se un carattere di nuova riga di Windows non viene trovato, DBMS_CLOUD cerca il carattere di nuova riga UNIX/Linux \n e, se ne trova uno, utilizza \n come delimitatore di record per tutti i file della procedura. Se i file di origine utilizzano una combinazione di diversi delimitatori di record, potrebbe verificarsi un errore, ad esempio "KUP-04020: found record longer than buffer size supported". In questo caso, è necessario modificare i file di origine per utilizzare lo stesso delimitatore di record oppure specificare solo i file di origine che utilizzano lo stesso delimitatore di record.

  Per informazioni sull'opzione di formato recorddelimiter, vedere DBMS_CLOUD Package Format Options.

Esempio

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(   
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',   
      credential_name =>'OBJ_STORE_CRED',   
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),   
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',                   
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,                 
                     ACTUAL_MIN_TEMP,                 
                     ACTUAL_MAX_TEMP,                 
                     AVERAGE_MIN_TEMP,                    
                     AVERAGE_MAX_TEMP,     
                     AVERAGE_PRECIPITATION',   
      column_list => 'REPORT_DATE DATE,   
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,  
                     ACTUAL_MIN_TEMP NUMBER,  
                     ACTUAL_MAX_TEMP NUMBER,  
                     AVERAGE_MIN_TEMP NUMBER,   
                     AVERAGE_MAX_TEMP NUMBER,                  
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/ 

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where         
   actual_mean_temp > 69 and actual_mean_temp < 74

Per una descrizione delle configurazioni supportate, vedere Informazioni sull'esecuzione di query sulle tabelle di Apache Iceberg.

Sintassi

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB DEFAULT NULL,
    field_list       IN CLOB DEFAULT NULL,
    format           IN CLOB DEFAULT NULL
);

Parametri

Esempio di tabelle AWS Iceberg che utilizzano il catalogo AWS Glue

Il parametro format quando si creano tabelle su una tabella AWS Iceberg utilizzando un catalogo AWS Glue è il seguente:

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg',
                   'protocol_config' value
                    json_object('iceberg_catalog_type' value 'aws_glue',
                                'iceberg_glue_region'  value 'glue region',
                                'iceberg_table_path'   value 'database_name.table_name'))); 

Esempio di tabella AWS Iceberg che utilizza un URI di file di metadati

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

Esempio di tabella Iceberg OCI che utilizza il catalogo HadoopCatalog

format => json_object('access_protocol' value
       json_object('protocol_type'   value 'iceberg',
                   'protocol_config' value
                   json_object('iceberg_catalog_type'  value 'hadoop',
                               'iceberg_warehouse'     value '<OCI folder URI>',
                               'iceberg_table_path'    value 'database_name.table_name')));

Esempio di tabella Iceberg OCI che utilizza l'URI del file di metadati

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

Sintassi

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Parametri

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.parquet'

Esempi ORC

Esempi Avro

Esempi Parquet

Mapping dei nomi delle colonne Avro, ORC o Parquet ai nomi delle colonne Oracle

Per informazioni sul mapping dei nomi di colonna e sull'uso della conversione dei nomi di colonna in Oracle SQL, vedere DBMS_CLOUD Package Avro, ORC e Parquet to Oracle Column Name Mapping.

La procedura CREATE_EXTERNAL_TEXT_INDEX crea un indice di testo nei file di storage degli oggetti specificati nella posizione location_uri. L'indice viene aggiornato a intervalli regolari, per eventuali nuove aggiunte o eliminazioni effettuate con i file sull'URI della posizione.

Sintassi

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

Parametri

Esempio

BEGIN 
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

Sintassi

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Parametri

partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
				    ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.txt''),….

Note per uso

• La procedura DBMS_CLOUD.CREATE_HYBRID_PART_TABLE supporta i file partizionati esterni nei servizi di storage degli oggetti cloud supportati, tra cui:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage o Azure Data Lake Storage

  • Amazon S3

  • Compatibile con Amazon S3, tra cui Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repository

  La credenziale è una proprietà a livello di tabella, pertanto i file esterni devono trovarsi nella stessa area di memorizzazione degli oggetti.

  Vedere DBMS_CLOUD Formati URI per ulteriori informazioni.

• La procedura DBMS_CLOUD.CREATE_HYBRID_PART_TABLE supporta i file di partizionamento ibridi contenuti nelle directory, sia in un file system locale che in un file system di rete.

• Le tabelle partizionate esterne create con DBMS_CLOUD.CREATE_HYBRID_PART_TABLE includono due colonne invisibili file$path e file$name. Queste colonne consentono di identificare il file da cui proviene un record.

  • file$path: specifica il testo del percorso del file fino all'inizio del nome dell'oggetto.

  • file$name: specifica il nome dell'oggetto, incluso tutto il testo che segue il nome del bucket.

Esempi

BEGIN  
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',  
      credential_name =>'OBJ_STORE_CRED',  
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),  
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/ 


BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

Sintassi

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

Parametri

Note per uso

• Questa procedura non elimina le operazioni attualmente in esecuzione (operazioni con stato "In esecuzione").

• Questa procedura elimina tutte le tabelle di log e i file di log associati alle operazioni.

Sintassi

 DBMS_CLOUD.DELETE_FILE ( 
       directory_name     IN VARCHAR2,
       file_name          IN VARCHAR2,
       force              IN BOOLEAN DEFAULT FALSE); 

Parametri

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

Esempio

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/ 

Sintassi

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

Parametri

Esempio

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp' );
   END;
/ 

Sintassi

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

Parametri

Nota per l'uso

• Questa procedura elimina tutte le tabelle di log e i file di log associati all'ID operazione specificato nell'input.

Esempio

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

La procedura DROP_EXTERNAL_TEXT_INDEX elimina l'indice specificato creato con la procedura CREATE_EXTERNAL_TEXT_INDEX.

Sintassi

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

Parametri

Esempio

BEGIN 
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

Sintassi

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

Parametri

Note per l'uso

• Il valore del parametro query fornito può essere una query avanzata, se necessario, ad esempio una query che include join o subquery.

• A seconda del parametro di formato specificato, DBMS_CLOUD.EXPORT_DATA restituisce i risultati della query specificata nell'area di memorizzazione degli oggetti cloud o in una posizione di directory in uno dei seguenti formati:

  • File CSV, JSON, Parquet o XML.

    Per ulteriori informazioni sull'utilizzo di DBMS_CLOUD.EXPORT_DATA con file di output CSV, JSON, Parquet o XML, vedere Esporta dati nell'area di memorizzazione degli oggetti come testo e Esporta dati in una directory.

  • Utilizzo del driver di accesso ORACLE_DATAPUMP per scrivere i dati in un file di dump.

• Per l'output CSV, JSON o XML, per impostazione predefinita quando un file generato contiene 10 MB di dati, viene creato un nuovo file di output. Tuttavia, se hai meno di 10 MB di dati dei risultati, potresti avere più file di output, a seconda del servizio di database e del numero di ECPU (OCPU se il tuo database utilizza OCPU) per l'istanza di Autonomous Database.

  Per ulteriori informazioni, vedere Denominazione dei file per l'output di testo (CSV, JSON, Parquet o XML).

  La dimensione predefinita del chunk del file di output è 10 MB per CSV, JSON o XML. È possibile modificare questo valore con l'opzione maxfilesize del parametro format. Per ulteriori informazioni, vedere DBMS_CLOUD Opzioni formato pacchetto per EXPORT_DATA.

• Per l'output Parquet, ogni file generato è inferiore a 128 MB ed è possibile generare più file di output. Tuttavia, se hai meno di 128 MB di dati dei risultati, potresti avere più file di output a seconda del servizio di database e del numero di ECPU (OCPU se il tuo database utilizza OCPU) per l'istanza di Autonomous Database.

  Per ulteriori informazioni, vedere Denominazione dei file per l'output di testo (CSV, JSON, Parquet o XML).

Note di utilizzo per l'output ORACLE_DATAPUMP (DBMS_CLOUD.EXPORT_DATA con il parametro format, opzione type, datapump):

• EXPORT_DATA utilizza DATA_PUMP_DIR come directory di log predefinita. Pertanto, il privilegio di scrittura su DATA_PUMP_DIR è necessario quando si utilizza l'output ORACLE_DATAPUMP.

• L'esportazione di Autonomous Database mediante DBMS_CLOUD.EXPORT_DATA con il parametro format type, opzione datapump, supporta solo le aree di memorizzazione degli oggetti Oracle Cloud Infrastructure Object Storage, Oracle Cloud Infrastructure Object Storage Classic o l'output della directory.

• Quando si specifica DBMS_CLOUD.EXPORT_DATA con il parametro format type, opzione datapump, il valore del parametro credential_name non può essere un principal risorsa OCI.

• Oracle Data Pump divide ogni parte del file di dump in chunk più piccoli per caricamenti più veloci. La console di Oracle Cloud Infrastructure Object Storage mostra più file per ogni parte del file di dump esportata. La dimensione dei file di dump effettivi verrà visualizzata come zero (0) e i relativi blocchi di file correlati come 10 MB o meno. Ad esempio:

  exp01.dmp
  exp01.dmp_aaaaaa
  exp02.dmp
  exp02.dmp_aaaaaa

  Il download del file di dump a zero byte dalla console di Oracle Cloud Infrastructure o l'utilizzo dell'interfaccia CLI di Oracle Cloud Infrastructure non fornirà i file di dump completi. Per scaricare i file di dump completi dall'area di memorizzazione degli oggetti, utilizzare uno strumento che supporti Swift come curl e fornire il login utente e il token di autenticazione Swift.

  curl -O -v -X GET -u 'user1@example.com:auth_token' \
     https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/namespace-string/bucketname/exp01.dmp

  Se si importa un file con le procedure DBMS_CLOUD che supportano il parametro format type con il valore 'datapump', è necessario solo fornire il nome del file primario. Le procedure che supportano il tipo di formato 'datapump' individuano e scaricano automaticamente i blocchi.

  Quando si utilizza DBMS_CLOUD.DELETE_OBJECT, la procedura individua ed elimina automaticamente i chunk quando la procedura elimina il file primario.

• La procedura DBMS_CLOUD.EXPORT_DATA crea i file di dump dai valori file_uri_list specificati, come indicato di seguito.

  • Poiché sono necessari altri file, la procedura crea altri file dal file file_uri_list.

  • La procedura non sovrascrive i file. Se esiste un file di dump in file_uri_list, DBMS_CLOUD.EXPORT_DATA segnala un errore.

  • DBMS_CLOUD.EXPORT_DATA non crea bucket.

• Il numero di file di dump generati da DBMS_CLOUD.EXPORT_DATA viene determinato all'esecuzione della procedura. Il numero di file di dump generati dipende dal numero di nomi file forniti nel parametro file_uri_list, nonché dal numero di OCPU di Autonomous Database disponibili per l'istanza, dal livello di servizio e dalla dimensione dei dati.

  Ad esempio, se si utilizza un'istanza di Autonomous Database da 1 OCPU o il servizio low, viene esportato un singolo file di dump senza parallelismo, anche se si forniscono più nomi di file. Se si utilizza un'istanza di Autonomous Database da 4 OCPU con il servizio medium o high, i job possono essere eseguiti in parallelo e i file di dump multipli vengono esportati se si forniscono più nomi di file.

• I file di dump creati con DBMS_CLOUD.EXPORT_DATA non possono essere importati utilizzando Oracle Data Pump impdp. A seconda del database, è possibile utilizzare i file indicati di seguito.

  • In un Autonomous Database, è possibile utilizzare i file di dump con le procedure DBMS_CLOUD che supportano il parametro format type con il valore 'datapump'. È possibile importare i file di dump utilizzando DBMS_CLOUD.COPY_DATA oppure chiamare DBMS_CLOUD.CREATE_EXTERNAL_TABLE per creare una tabella esterna.

  • In qualsiasi altro Oracle Database, ad esempio Oracle Database 19c in locale, è possibile importare i file di dump creati con la procedura DBMS_CLOUD.EXPORT_DATA utilizzando il driver di accesso ORACLE_DATAPUMP. Per ulteriori informazioni, vedere Scaricamento e caricamento dei dati con il driver di accesso ORACLE_DATAPUMP.

• Il valore del parametro query fornito può essere una query avanzata, se necessario, ad esempio una query che include join o subquery.

Note di utilizzo per DBMS_CLOUD.EXPORT_DATA con output in una directory

• La directory fornita deve esistere ed è necessario eseguire il login come utente ADMIN o disporre dell'accesso WRITE alla directory.

• DBMS_CLOUD.EXPORT_DATA non crea directory.

• La procedura non sovrascrive i file. Ad esempio, se esiste un file di dump in file_uri_list, DBMS_CLOUD.EXPORT_DATA segnala un errore simile al seguente:

  ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
  ORA-27038: created file already exists

Esempi

L'esempio seguente mostra DBMS_CLOUD.EXPORT_DATA con il parametro formato type con il valore datapump:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp',
      format => json_object('type' value 'datapump', 'compression' value 'basic', 'version' value 'latest'),
      query => 'SELECT warehouse_id, quantity FROM inventories'
     );
   END;
/  

In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

L'esempio seguente mostra DBMS_CLOUD.EXPORT_DATA con il parametro formato type con il valore json:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.json', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'json', 'compression' value 'gzip'));
     );
   END;
/  

L'esempio seguente mostra DBMS_CLOUD.EXPORT_DATA con il parametro formato type con il valore xml:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.xml', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'xml', 'compression' value 'gzip'));
     );
   END;
/

L'esempio seguente mostra DBMS_CLOUD.EXPORT_DATA con il parametro formato type con il valore csv:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true, 'encryption' value ('user_defined_function' value 'ADMIN.decryption_callback')));
     );
   END;
/  

L'esempio seguente mostra DBMS_CLOUD.EXPORT_DATA che esporta i dati in una posizione di directory con il parametro type con il valore datapump:

BEGIN
 DBMS_CLOUD.EXPORT_DATA(
    file_uri_list => 'export_dir:sales.dmp',
    format        => json_object('type' value 'datapump'),
    query         => 'SELECT * FROM sales'
 );
END;
/

Sintassi

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

Parametri

^{Nota a piè di pagina 1}

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

Valori restituiti

Il form funzione viene letto dall'area di memorizzazione degli oggetti e DBMS_CLOUD.GET_OBJECT restituisce un valore BLOB.

Esempi

BEGIN 
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR'); 
END;
/

Per leggere i dati dei caratteri da un file nell'area di memorizzazione degli oggetti:

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

Per aggiungere un'immagine memorizzata nell'area di memorizzazione degli oggetti in un file BLOB nel database, procedere come segue.

DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

Sintassi

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

Parametri

Note per uso

• Per eseguire DBMS_CLOUD.LIST_FILES con un utente diverso da ADMIN, è necessario concedere privilegi di lettura sulla directory a tale utente. Ad esempio, eseguire il comando seguente come ADMIN per concedere i privilegi di lettura a adb_user:

  GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

• Questa è una funzione tabella con pipeline con tipo restituito DBMS_CLOUD_TYPES.list_object_ret_t.

• DBMS_CLOUD.LIST_FILES non ottiene il valore di checksum e restituisce NULL per questo campo.

Esempio

Questa è una funzione con pipeline che restituisce una riga per ogni file. Ad esempio, utilizzare la seguente query per utilizzare questa funzione:

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');

OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

Sintassi

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

Parametri

Note per uso

• A seconda delle capacità dell'area di memorizzazione degli oggetti, DBMS_CLOUD.LIST_OBJECTS non restituisce valori per determinati attributi e il valore restituito per il campo è NULL in questo caso.

  Tutti gli archivi oggetti supportati restituiscono valori per i campi OBJECT_NAME, BYTES e CHECKSUM.

  La tabella riportata di seguito mostra il supporto per i campi CREATED e LAST_MODIFIED per area di memorizzazione degli oggetti.

  Area di memorizzazione degli oggetti	CREATED	LAST_MODIFIED
  Oracle Cloud Infrastructure Native	Indicatore orario resi	Indicatore orario resi
  Oracle Cloud Infrastructure Swift	Restituisce NULL	Indicatore orario resi
  Oracle Cloud Infrastructure Classic	Restituisce NULL	Indicatore orario resi
  Amazon S3	Restituisce NULL	Indicatore orario resi
  Amazon S3 - Compatibile	Restituisce NULL	Indicatore orario resi
  Azure	Indicatore orario resi	Indicatore orario resi
  GitHub Repository

• Il valore di checksum è il checksum MD5. Si tratta di un numero esadecimale di 32 caratteri calcolato sul contenuto dell'oggetto. Si prevede che abbia un valore di checksum diverso se si utilizza la credenziale OCI$RESOURCE_PRINCIPAL.

• Questa è una funzione tabella con pipeline con tipo restituito DBMS_CLOUD_TYPES.list_object_ret_t.

Esempio

Questa è una funzione con pipeline che restituisce una riga per ogni oggetto. Ad esempio, utilizzare la seguente query per utilizzare questa funzione:

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED', 
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');


OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z          

In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

Il bucket o la cartella di origine e destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un altro provider.

Quando l'origine e la destinazione si trovano in aree di memorizzazione degli oggetti distinte o hanno account diversi con lo stesso provider cloud, è possibile assegnare nomi di credenziali separati per le posizioni di origine e destinazione.

Il nome della credenziale di origine viene utilizzato per impostazione predefinita anche dalla posizione di destinazione quando non viene fornito il nome della credenziale di destinazione.

Sintassi

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Parametri

Esempio

BEGIN 
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Sintassi

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

Parametri

^{Nota a piè di pagina 2}

GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

Esempio

Per gestire i dati BLOB dopo l'elaborazione nel database e quindi memorizzarli direttamente in un file nell'area di memorizzazione degli oggetti, effettuare le operazioni riportate di seguito.

DECLARE
      my_blob_data BLOB;
BEGIN 
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data)); 
END;
/

Note per uso

A seconda dello storage degli oggetti cloud, le dimensioni dell'oggetto trasferito sono limitate come indicato di seguito.

L'area di memorizzazione degli oggetti Oracle Cloud Infrastructure non consente la scrittura di file in un bucket pubblico senza fornire credenziali (Oracle Cloud Infrastructure consente agli utenti di scaricare oggetti dai bucket pubblici). Pertanto, devi fornire un nome di credenziale con credenziali valide per memorizzare un oggetto in un bucket pubblico di Oracle Cloud Infrastructure utilizzando PUT_OBJECT.

Vedere DBMS_CLOUD Formati URI per ulteriori informazioni.

Sintassi

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

Parametri

Sintassi

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Parametri

Sintassi

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,		
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,		
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

Parametri

Note per uso

• DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE funziona sia con tabelle esterne partizionate che con tabelle ibride partizionate. Questa operazione consente di leggere i dati di tutte le partizioni esterne fino al raggiungimento di rowcount o all'applicazione di stop_on_error. Non si dispone del controllo su quale partizione, o parti di una partizione, viene letta in quale ordine.

Sintassi

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Parametri

È possibile filtrare la lista di file da eliminare utilizzando un pattern di espressione regolare compatibile con l'operatore REGEXP_LIKE.

Il bucket o la cartella di origine e destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un altro provider.

Quando l'origine e la destinazione si trovano in aree di memorizzazione degli oggetti distinte o hanno account diversi con lo stesso provider cloud, è possibile assegnare nomi di credenziali separati per le posizioni di origine e destinazione.

Il nome della credenziale di origine viene utilizzato per impostazione predefinita anche dalla posizione di destinazione.

Sintassi

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

Parametri

Note per uso

• Viene restituito un errore quando l'URI di origine e destinazione punta allo stesso bucket o cartella di storage degli oggetti.

Esempio

BEGIN 
DBMS_CLOUD.BULK_COPY (
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format       => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Sintassi

 DBMS_CLOUD.BULK_DELETE(
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DELETE (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parametri

Esempio

BEGIN
DBMS_CLOUD.BULK_DELETE (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKDEL')
);
END;
/

Sintassi

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parametri

Esempio

BEGIN
DBMS_CLOUD.BULK_DOWNLOAD (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
 );
END;
/

È possibile filtrare la lista di file da eliminare utilizzando un pattern di espressione regolare compatibile con l'operatore REGEXP_LIKE.

Il bucket o la cartella di origine e destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un altro provider.

Quando l'origine e la destinazione si trovano in aree di memorizzazione degli oggetti distinte o hanno account diversi con lo stesso provider cloud, è possibile assegnare nomi di credenziali separati per le posizioni di origine e destinazione.

Il nome della credenziale di origine viene utilizzato per impostazione predefinita anche dalla posizione di destinazione quando non viene fornito il nome della credenziale di destinazione.

Il primo passo per spostare i file è copiarli nella posizione di destinazione, quindi eliminare i file di origine, una volta copiati correttamente.

L'oggetto viene rinominato anziché spostato se l'area di memorizzazione degli oggetti consente di rinominare le operazioni tra le posizioni di origine e di destinazione.

Sintassi

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

Parametri

Esempio

BEGIN 
DBMS_CLOUD.BULK_MOVE (    
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKMOVE')
);
END;
/

Sintassi

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parametri

Esempio

BEGIN
DBMS_CLOUD.BULK_UPLOAD ( 
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKUPLOAD')
 );
END;
/

DBMS_CLOUD supporta i metodi GET, PUT, POST, HEAD e DELETE HTTP. Il metodo API REST da utilizzare per una richiesta HTTP è in genere documentato nella documentazione dell'API REST cloud.

Per impostazione predefinita, le chiamate API REST DBMS_CLOUD non salvano i risultati per la sessione. In questo caso si utilizza la funzione DBMS_CLOUD.SEND_REQUEST per restituire i risultati.

Quando si utilizza DBMS_CLOUD.SEND_REQUEST e si imposta il parametro cache su TRUE, i risultati vengono salvati ed è possibile visualizzare i risultati passati nella vista SESSION_CLOUD_API_RESULTS. Il salvataggio e l'esecuzione di query sui risultati cronologici delle richieste API REST DBMS_CLOUD possono essere utili quando è necessario utilizzare i risultati precedenti nelle applicazioni.

Ad esempio, per eseguire una query sui risultati recenti dell'API REST DBMS_CLOUD, utilizzare la vista SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Quando si salvano i risultati dell'interfaccia API REST DBMS_CLOUD con DBMS_CLOUD.SEND_REQUEST, i dati salvati sono disponibili solo all'interno della stessa sessione (connessione). Al termine della sessione, i dati salvati non sono più disponibili.

Utilizzare DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE e DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE per visualizzare e impostare la dimensione della cache dell'API REST DBMS_CLOUD e per disabilitare l'inserimento nella cache.

Sintassi

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Parametri

Eccezioni

Sintassi

DBMS_CLOUD.GET_RESPONSE_RAW(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN BLOB;

Parametri

Eccezioni

Sintassi

DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN PLS_INTEGER;

Parametri

Eccezioni

Sintassi

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Parametri

Eccezioni

Sintassi

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Sintassi

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Parametri

Eccezioni

Note per l'uso

• Se si utilizza Oracle Cloud Infrastructure, è necessario utilizzare un valore di credenziale basato su chiave di firma per credential_name. Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedura.

• I parametri facoltativi async_request_url, wait_for_states e timeout consentono di gestire le richieste con tempi di esecuzione lunghi. Utilizzando questo formato asincrono di send_request, la funzione attende lo stato di completamento specificato in wait_for_states prima di tornare. Con questi parametri nella richiesta di invio, si superano gli stati di restituzione previsti nel parametro wait_for_states e si utilizza il parametro async_request_url per specificare una richiesta di lavoro associata, la richiesta non viene restituita immediatamente. Invece, la richiesta esamina async_request_url fino a quando lo stato restituito non è uno degli stati previsti o viene superato timeout (timeout è facoltativo). Se non viene specificato alcun valore timeout, la richiesta attende che si verifichi uno stato trovato in wait_for_states.

Sintassi

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parametri

Eccezioni

Esempio

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

Crea esempio di bucket

Mostra un esempio che utilizza DBMS_CLOUD.SEND_REQUEST con il metodo HTTP POST per creare un bucket dell'area di memorizzazione degli oggetti denominato bucketname.

Per i dettagli sull'API di Oracle Cloud Infrastructure Object Storage Service, vedere CreateBucket per questo esempio.

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/',
            method => DBMS_CLOUD.METHOD_POST,
            body => UTL_RAW.cast_to_raw(
                        JSON_OBJECT('name' value 'bucketname',
                                    'compartmentId' value 'compartment_OCID'))
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

Note:

• In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

• Dove: region è un'area di endpoint. Per ulteriori informazioni, consulta il riferimento all'API di storage degli oggetti in Riferimento ed endpoint API. Ad esempio, dove region è: us-phoenix-1.

Esempio di eliminazione del bucket

Mostra un esempio che utilizza il metodo DBMS_CLOUD.SEND_REQUEST con HTTP DELETE per eliminare un bucket dell'area di memorizzazione degli oggetti denominato bucketname.

Per i dettagli sull'API di Oracle Cloud Infrastructure Object Storage Service, vedere DeleteBucket per questo esempio.

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucketname',
            method => DBMS_CLOUD.METHOD_DELETE
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

Note:

• In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

• Dove: region è un'area di endpoint. Per ulteriori informazioni, consulta il riferimento all'API di storage degli oggetti in Riferimento ed endpoint API. Ad esempio, dove region è: us-phoenix-1.

Esempio di lista di compartimenti

Mostra un esempio utilizzando il metodo DBMS_CLOUD.SEND_REQUEST con il metodo HTTP GET per elencare tutti i compartimenti nella tenancy (compartimento radice). In questo esempio viene illustrato come passare le intestazioni delle richieste in DBMS_CLOUD.SEND_REQUEST.

Per i dettagli sull'API di Oracle Cloud Infrastructure Identity and Access Management Service, vedere ListCompartments per questo esempio.

--
-- List compartments
--
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
  root_compartment_ocid VARCHAR2(512) := '&1';
BEGIN
  -- Send request
  dbms_output.put_line('Send Request');
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://identity.region.oraclecloud.com/20160918/compartments?compartmentId=' || root_compartment_ocid,
            method => DBMS_CLOUD.METHOD_GET,
            headers => JSON_OBJECT('opc-request-id' value 'list-compartments')
          );
  dbms_output.put_line('Body: ' || '------------' || CHR(10) || DBMS_CLOUD.get_response_text(resp) || CHR(10));
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_status_code(resp));
  dbms_output.put_line(CHR(10));
END;
/

Dove: region è un'area di endpoint. Per ulteriori informazioni, consulta il riferimento all'API IAM (Identity and Access Management) in Riferimento e endpoint API. Ad esempio, dove region è: uk-london-1.

Esempio di richiesta asincrona

Mostra un esempio che utilizza DBMS_CLOUD.SEND_REQUEST con il metodo HTTP POST per eseguire l'operazione di arresto di Autonomous Database e attendere lo stato. Questo esempio mostra come utilizzare DBMS_CLOUD.SEND_REQUEST con i parametri async_request_url, wait_for_states e timeout.

--
-- Sent Work Request Autonomous Database Stop Request with Wait for Status
DECLARE
    l_resp DBMS_CLOUD_TYPES.resp;
    l_resp_json JSON_OBJECT_T;
    l_key_shape JSON_OBJECT_T;
    l_body JSON_OBJECT_T;
    status_array DBMS_CLOUD_TYPES.wait_for_states_t;
BEGIN
  status_array := DBMS_CLOUD_TYPES.wait_for_states_t('SUCCEEDED');
  l_body := JSON_OBJECT_T('{}');
  l_body.put('autonomousDatabaseId', 'ocid');
-- Send request
  dbms_output.put_line(l_body.to_clob);
  dbms_output.put_line('Send Request');
  l_resp := DBMS_CLOUD.send_request(
                       credential_name    => 'NATIVE_CRED_OCI',
                       uri                => 'https://database.region.oraclecloud.com/20160918/autonomousDatabases/ocid/actions/stop',
                       method             => DBMS_CLOUD.METHOD_POST,
                       body               => UTL_RAW.cast_to_raw(l_body.to_clob),
                       async_request_url  => 'https://iaas.region.oraclecloud.com/20160918/workRequests',
                       wait_for_states    => status_array,
                       timeout            => 600
                  );
   dbms_output.put_line('resp body: '||DBMS_CLOUD.get_response_text(l_resp));
   dbms_output.put_line('resp headers: '||DBMS_CLOUD.get_response_headers(l_resp).to_clob);
END;
/

Dove: region è un'area di endpoint. Per ulteriori informazioni, consulta il riferimento all'API IAM (Identity and Access Management) in Riferimento e endpoint API. Ad esempio, dove region è: uk-london-1.

L'ocid è l'identificativo della risorsa Oracle Cloud Infrastructure. Per ulteriori informazioni, vedere Identificativi risorsa.