DBMS_CLOUD Subprogrammi e API REST

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

• Utilizzare i parametri correlati a Oracle Cloud Infrastructure, tra cui: user_ocid, tenancy_ocid, private_key e fingerprint solo quando si utilizza l'autenticazione Oracle Cloud Infrastructure Signing Keys.

• Utilizzare il parametro params per uno dei seguenti elementi:

  • Credenziali dei nomi delle risorse Amazon (ARN)

  • Credenziali Google Analytics o Google BigQuery

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

    • Oracle Cloud Infrastructure Vault
    • Vault di chiavi Azure
    • AWS Secrets Manager
    • GCP Secret Manager

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 sull'uso

• Questa operazione memorizza le credenziali nel database in un 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 solo una volta, a meno che le credenziali del servizio cloud non vengano modificate. Una volta memorizzate le credenziali, è possibile utilizzare lo stesso nome 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, la chiamata viene considerata una credenziale basata sulla chiave di firma di Oracle Cloud Infrastructure.

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

  SELECT credential_name, username, comments FROM all_credentials;

Credenziali di Oracle Cloud Infrastructure (token di autenticazione)

Per Oracle Cloud Infrastructure, username è il tuo nome utente 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;
/

Utilizzare le credenziali basate su token di autenticazione durante l'autenticazione delle chiamate allo storage degli oggetti OCI. Per le chiamate a qualsiasi altro tipo di servizio cloud Oracle Cloud Infrastructure, utilizza le credenziali basate su 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. È possibile 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 di Oracle Cloud Infrastructure

Utilizza i parametri correlati alle chiavi di firma di Oracle Cloud Infrastructure, tra cui: user_ocid, tenancy_ocid, private_key e fingerprint con l'autenticazione Oracle Cloud Infrastructure Signing Keys.

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 passphrase non sono supportate. È necessario generare la chiave privata senza una passphrase. Per ulteriori informazioni, vedere Come generare una chiave di firma API.

Credenziali di Oracle Cloud Infrastructure Object Storage Classic

Se i file di origine risiedono in Oracle Cloud Infrastructure Object Storage Classic, username è il nome utente di Oracle Cloud Infrastructure Classic e password è la password di 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 Azure Data Lake Storage o si sta chiamando un'API di Azure, username è il nome dell'account di storage di Azure e password è una chiave di accesso dell'account di storage di Azure. Vedere Informazioni sugli account di storage di Azure.

Credenziali compatibili con Amazon S3

Credenziali dei nomi delle risorse AWS Amazon (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;
/

Token di accesso personale GitHub

Se i file di origine risiedono in un repository GitHub o si sta chiamando un'API GitHub, username è l'e-mail 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 di Google OAuth 2.0.

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 segrete vault con Oracle Cloud Infrastructure Vault

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

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

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

• region: 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 region mappato dalla chiave area in secret_id. Un esempio di area è us-ashburn-1.

  Per un elenco completo delle aree, vedere Aree e 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 utilizzi un 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 sul pacchetto DBMS_CLOUD.

Credenziali segrete vault con Azure Key Vault

Per creare le credenziali di Azure Key Vault, 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 sul pacchetto DBMS_CLOUD.

Credenziali segrete 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 la regione di servizio AWS in cui si trovano il vault e il segreto. Un esempio dell'area AWS è "us-east-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 sul pacchetto DBMS_CLOUD.

Credenziali segrete 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 Secret Manager.

Per creare una credenziale segreta del vault, è necessario disporre del privilegio EXECUTE sul pacchetto 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 sull'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 elencare 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 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 sull'uso

• Il valore del nome utente fa distinzione tra maiuscole e minuscole. Non può contenere virgolette doppie o spazi.

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

• È necessario creare le credenziali solo una volta, a meno che le credenziali del servizio cloud non vengano modificate. Una volta memorizzate le credenziali, è possibile utilizzare lo stesso nome 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 elencare 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 prima il carattere \r\n della nuova riga di Windows. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se non viene trovato un carattere di nuova riga di Windows, 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 delimitatori di record diversi, è possibile che si verifichi 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 sull'uso

• Come per altri file di dati, i caricamenti di 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, se 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 rilevano 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 di destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un provider diverso.

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

Per impostazione predefinita, il nome della credenziale di origine viene utilizzato 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 sull'uso

• Attributi DEFAULT: 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 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 sull'uso

• Non è possibile chiamare 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.

  • Repository GitHub

  Per ulteriori informazioni, vedere DBMS_CLOUD Formati URI.

• La procedura DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE supporta i file partizionati esterni nelle directory, sia in un file system locale che in un file system di rete.

• Quando si chiama DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE con il parametro file_uri_list, i tipi di colonne specificati nel nome file dell'area di memorizzazione degli oggetti cloud devono essere uno dei tipi 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 prima il carattere \r\n della nuova riga di Windows. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se non viene trovato un carattere di nuova riga di Windows, 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 delimitatori di record diversi, è possibile che si verifichi 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 che utilizza il 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 sull'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.

  • Repository GitHub

  • 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.

  Per ulteriori informazioni, vedere DBMS_CLOUD Formati URI.

• 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 prima il carattere \r\n della nuova riga di Windows. Se trova il carattere di nuova riga di Windows, viene utilizzato come delimitatore di record per tutti i file della procedura. Se non viene trovato un carattere di nuova riga di Windows, 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 delimitatori di record diversi, è possibile che si verifichi 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

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

Parametro di formato di esempio per le tabelle AWS Iceberg che utilizzano un catalogo di colla AWS

Di seguito è riportato un parametro format di esempio durante la creazione di tabelle su una tabella AWS Iceberg utilizzando un catalogo di colla AWS.

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'))); 

Parametro di formato di esempio per la tabella AWS Iceberg che utilizza un URI di file di metadati

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

Parametro di formato di esempio per la tabella OCI Iceberg 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')));

Parametro di formato di esempio per la tabella OCI Iceberg 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 di ORC

Esempi Avro

Esempi Parquet

Mapping nome colonna Avro, ORC o Parquet a nomi colonna Oracle

Per informazioni sul mapping dei nomi delle colonne e sull'uso della conversione dei nomi delle colonne 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 eseguite con i file nell'URI 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 sull'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.

  • Repository GitHub

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

  Per ulteriori informazioni, vedere DBMS_CLOUD Formati URI.

• La procedura DBMS_CLOUD.CREATE_HYBRID_PART_TABLE supporta i file partizionati ibridi presenti 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 sull'uso

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

• Questa procedura elimina 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 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 sull'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'uso 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 ed Esporta dati in una directory.

  • Utilizzare il driver di accesso ORACLE_DATAPUMP per scrivere 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 database utilizza OCPU) per l'istanza di Autonomous Database.

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

  La dimensione chunk predefinita 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 Package Format Options for EXPORT_DATA.

• Per l'output Parquet, ogni file generato è inferiore a 128 MB e possono essere generati 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 database utilizza le OCPU) per l'istanza di Autonomous Database.

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

Note sull'uso per l'output ORACLE_DATAPUMP (DBMS_CLOUD.EXPORT_DATA con parametro format opzione type datapump):

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

• L'esportazione di Autonomous Database mediante DBMS_CLOUD.EXPORT_DATA con il parametro format, opzione type 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 l'opzione type del parametro format 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ù rapidi. 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 chunk di file correlati come 10mb 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 utilizzando l'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, ad esempio 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', è sufficiente fornire il nome del file primario. Le procedure che supportano il tipo di formato 'datapump' rilevano e scaricano automaticamente i chunk.

  Quando si utilizza DBMS_CLOUD.DELETE_OBJECT, la procedura rileva 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 più file, la procedura crea ulteriori file da 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 durante l'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, il livello di servizio e la dimensione dei dati.

  Ad esempio, se si utilizza un'istanza di Autonomous Database 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 con 4 OCPU con il servizio medium o high, i job possono essere eseguiti in parallelo e vengono esportati più file di dump se si forniscono più nomi 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 questi file come indicato di seguito.

  • In un'istanza di 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 on-premise, è 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 sull'uso 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 l'esportazione dei dati in DBMS_CLOUD.EXPORT_DATA 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 legge 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 BLOB nel database, effettuare le operazioni riportate di seguito.

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 sull'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 privilegi di lettura a adb_user:

  GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

• Questa è una funzione di tabella 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 pipelined 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 sull'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
  Compatibile con Amazon S3	Restituisce NULL	Indicatore orario resi
  Azure	Indicatore orario resi	Indicatore orario resi
  Repository GitHub

• Il valore di checksum è il checksum MD5. Si tratta di un numero esadecimale di 32 caratteri calcolato sul contenuto dell'oggetto. È previsto un valore di checksum diverso se viene utilizzata la credenziale OCI$RESOURCE_PRINCIPAL.

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

Esempio

Questa è una funzione a 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 di destinazione possono trovarsi nello stesso provider dell'area di memorizzazione degli oggetti cloud o in un provider diverso.

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

Per impostazione predefinita, il nome della credenziale di origine viene utilizzato 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, quindi memorizzare i dati direttamente in un file nell'area di memorizzazione degli oggetti:

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 sull'uso

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

L'area di memorizzazione degli oggetti di 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.

Per ulteriori informazioni, vedere DBMS_CLOUD Formati URI.

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 sull'uso

• DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE funziona sia con tabelle esterne partizionate che con tabelle partizionate ibride. Questo potenzialmente legge i dati da 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 dei file da eliminare utilizzando un pattern di espressione regolare compatibile con l'operatore REGEXP_LIKE.

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

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

Per impostazione predefinita, il nome della credenziale di origine viene utilizzato 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 sull'uso

• Viene restituito un errore quando l'URI di origine e di destinazione punta allo stesso bucket o alla stessa 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 dei file da eliminare utilizzando un pattern di espressione regolare compatibile con l'operatore REGEXP_LIKE.

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

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

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

Il primo passo nello spostamento dei file consiste nel 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 HTTP GET, PUT, POST, HEAD e DELETE. Il metodo API REST da utilizzare per una richiesta HTTP è in genere documentato nella documentazione relativa all'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'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 saranno 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 sull'uso

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

• I parametri facoltativi async_request_url, wait_for_states e timeout consentono di gestire le richieste con tempi di esecuzione lunghi. Utilizzando questo modulo 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 passano gli stati di ritorno 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. La richiesta analizza invece async_request_url finché lo stato restituito non è uno degli stati previsti oppure viene superato il valore 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 il metodo DBMS_CLOUD.SEND_REQUEST con 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 per questo esempio, consulta CreateBucket.

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 endpoint. Per ulteriori informazioni, vedere il riferimento all'API di storage degli oggetti in Riferimento API ed endpoint API. Ad esempio, dove region è: us-phoenix-1.

Esempio di eliminazione 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 per questo esempio, consulta DeleteBucket.

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 endpoint. Per ulteriori informazioni, vedere il riferimento all'API di storage degli oggetti in Riferimento API ed endpoint API. Ad esempio, dove region è: us-phoenix-1.

Esempio di compartimenti elenco

Mostra un esempio che utilizza il metodo DBMS_CLOUD.SEND_REQUEST con il metodo GET HTTP per elencare tutti i compartimenti nella tenancy (compartimento radice). Questo esempio mostra come passare le intestazioni delle richieste in DBMS_CLOUD.SEND_REQUEST.

Per i dettagli sull'API del servizio Oracle Cloud Infrastructure Identity and Access Management per questo esempio, consulta ListCompartments.

--
-- 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 endpoint. Per ulteriori informazioni, vedere il riferimento all'API IAM (Identity and Access Management) in Riferimento API e endpoint. 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 endpoint. Per ulteriori informazioni, vedere il riferimento all'API IAM (Identity and Access Management) in Riferimento API e endpoint. Ad esempio, dove region è: uk-london-1.

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