Oracle Cloud Infrastructure-Dokumentation

Bulkvorgänge für Dateien in der Cloud

Das PL/SQL-Package DBMS_CLOUD bietet Unterstützung für die parallele Ausführung von Bulk-Dateiupload-, -download-, -kopier- und -übertragungsaktivitäten, wodurch die Benutzererfahrung optimiert und eine optimale Performance für Massendateivorgänge bereitgestellt wird.

Das Package DBMS_CLOUD unterstützt das Laden und Entladen von Dateien in die folgenden Cloud-Services:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage oder Azure Data Lake Storage

  • Amazon S3

  • Amazon S3-kompatibel, einschließlich Wasabi Hot Cloud Storage

  • Google Cloud Storage

Weitere Informationen finden Sie unter DBMS_CLOUD Package File URI Formats.

Übergeordnetes Thema: Dateien verschieben

Informationen zu Massendateivorgängen

DBMS_CLOUD Bulk-Dateivorgänge unterstützen das Herunterladen und Hochladen von Dateien in einer autonomen KI-Datenbank, einschließlich der Unterstützung für das Kopieren, Verschieben und Löschen von Dateien über Cloud-Objektspeicher hinweg, entweder innerhalb desselben Objektspeicherproviders oder zwischen Objektspeicherprovidern.

Die Massendateivorgänge unterstützen Parallelität und bieten optimale Performance für das Hochladen, Herunterladen, Kopieren und Verschieben von Dateien. Parallelität für Bulk File-Vorgänge wird durch Angabe einer Priorität für einen Vorgang behandelt. Folgende Prioritäten werden unterstützt:

  • HIGH: Mit der CPU-Compute-Anzahl der Instanz der autonomen KI-Datenbank können Sie die Anzahl der verarbeiteten parallelen Dateien bestimmen.
  • MEDIUM: Verwenden Sie das Nebenläufigkeitslimit für den Medium-Service, um die Parallelität zu bestimmen.
  • LOW: Verarbeiten Sie Dateien in serieller Reihenfolge (keine Nebenläufigkeit).

Bei der Ausführung von Bulkvorgängen mit einer höheren Priorität werden mehr Datenbankressourcen und Vorgänge schneller abgeschlossen, wenn die Parallelisierung den Vorgang beschleunigen kann. Eine niedrigere Priorität verbraucht weniger Datenbankressourcen und die Ausführung von Vorgängen dauert länger, wenn die Parallelisierung den Vorgang beschleunigen kann. Wenn Bulk-Vorgänge eine geringe Anzahl von Dateien mit wenig Daten umfassen, kann die Angabe einer höheren Priorität die Performance nicht verändern.

Um die Parallelität für Massendateivorgänge zu erhöhen, verwenden Sie die Priorität HIGH, und erhöhen Sie die Anzahl der CPUs, die Ihrer autonomen KI-Datenbankinstanz zugewiesen sind. Die maximal unterstützten nebenläufigen Dateivorgänge sind für Massendateivorgänge auf 64 begrenzt.

Die Standardpriorität ist MEDIUM, mit der angegeben wird, dass Massendateivorgänge das für die MEDIUM-Nutzungsgruppe definierte Nebenläufigkeitslimit verwenden. Weitere Informationen finden Sie unter Nebenläufigkeit und Prioritäten in der autonomen KI-Datenbank verwalten.

Einzelheiten zur Verwendung des Parameters format zur Angabe der priority mit Bulkdateivorgängen finden Sie unter DBMS_CLOUD für Bulk File Management.

Dateien im Cloud-Objektspeicher per Bulkvorgang kopieren

Verwenden Sie die Prozedur DBMS_CLOUD.BULK_COPY, um Dateien aus einem Objektspeicher-Bucket oder -Ordner in einen anderen Bucket oder Ordner zu kopieren.

  1. Erstellen Sie ein Zugangsdatenobjekt, um auf den Quellspeicherort zuzugreifen.

    Der Name der Quellzugangsdaten, wie mit dem Parameter source_credential_name angegeben, wird standardmäßig auch als Zugangsdaten für den Zielspeicherort verwendet.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  2. Wenn sich Quelle und Ziel in unterschiedlichen Objektspeichern befinden oder unterschiedliche Accounts mit demselben Cloud-Provider haben, erstellen Sie Zugangsdaten für den Zugriff auf das Zielverzeichnis, und nehmen Sie den Parameter target_credential_name auf.
  3. Führen Sie die Prozedur DBMS_CLOUD.BULK_COPY aus, um Dateien parallel von einem Objektspeicher-Bucket oder -Ordner in einen anderen Bucket oder Ordner zu kopieren, der sich über Cloud-Provider, Accounts und Buckets hinweg befinden kann. Um die Prozedur auszuführen, müssen Sie als ADMIN-Benutzer angemeldet sein oder die Berechtigung EXECUTE für DBMS_CLOUD besitzen. 
    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;
/

    In diesem Beispiel werden Dateien von einem Oracle Cloud Infrastructure Object Storage-Bucket in einen anderen kopiert.

    Weitere Informationen finden Sie unter Prozedur BULK_COPY.

    Weitere Informationen finden Sie unter DBMS_CLOUD URI-Formate.

Beispiel: Verwenden Sie DBMS_CLOUD.BULK_COPY, um Dateien von Amazon S3 in Oracle Cloud Infrastructure Object Storage zu kopieren. 

BEGIN
DBMS_CLOUD.BULK_COPY(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      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;
/

Dateien im Cloud-Objektspeicher global verschieben

Mit der Prozedur DBMS_CLOUD.BULK_MOVE können Sie Dateien per Bulkvorgang von einem Cloud Object Storage-Speicherort in einen anderen verschieben.

Der erste Schritt beim Verschieben von Dateien besteht darin, sie in den Zielspeicherort zu kopieren. Nachdem die Dateien erfolgreich kopiert wurden, werden sie aus dem Quellspeicherort gelöscht.

Die Dateien werden umbenannt und nicht kopiert, wenn der Objektspeicher Umbenennungsvorgänge zwischen Quell- und Zielspeicherorten zulässt.

  1. Erstellen Sie ein Zugangsdatenobjekt, um auf den Quellspeicherort zuzugreifen.

    Der Name der Quellzugangsdaten, wie mit dem Parameter source_credential_name angegeben, wird standardmäßig auch als Zugangsdaten für den Zielspeicherort verwendet.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  2. Wenn sich Quelle und Ziel in unterschiedlichen Objektspeichern befinden oder unterschiedliche Accounts mit demselben Cloud-Provider haben, erstellen Sie Zugangsdaten für den Zugriff auf das Zielverzeichnis, und nehmen Sie den Parameter target_credential_name auf.
  3. Führen Sie die Prozedur DBMS_CLOUD.BULK_MOVE aus, um Dateien per Bulkvorgang von einem Cloud Object Storage-Speicherort in einen anderen zu verschieben. Um die Prozedur auszuführen, müssen Sie als ADMIN-Benutzer angemeldet sein oder die Berechtigung EXECUTE für DBMS_CLOUD besitzen. 
    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;
/

    In diesem Beispiel werden Dateien per Bulkvorgang von einem Oracle Cloud Infrastructure Object Storage-Speicherort in einen anderen verschoben.

    Weitere Informationen finden Sie unter Prozedur BULK_MOVE.

    Weitere Informationen finden Sie unter DBMS_CLOUD URI-Formate.

Beispiel: Verwenden Sie DBMS_CLOUD.BULK_MOVE, um Dateien von Amazon S3 in Oracle Cloud Infrastructure Object Storage zu verschieben. 

BEGIN
DBMS_CLOUD.BULK_MOVE(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      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;
/

Massendownload von Dateien aus Cloud Object Storage

Mit der Prozedur DBMS_CLOUD.BULK_DOWNLOAD können Sie Dateien im Bulkverfahren aus dem Cloud-Objektspeicherverzeichnis in das Verzeichnisobjekt in einer autonomen KI-Datenbank herunterladen.

  1. Erstellen Sie Zugangsdaten für den Zugriff auf Ihren Cloud-Objektspeicher.

    Der Zugangsdatenname wird mit dem Parameter credential_name angegeben.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  2. Führen Sie die Prozedur DBMS_CLOUD.BULK_DOWNLOAD aus, um Dateien aus Cloud Object Storage in ein Autonomous Database-Verzeichnis herunterzuladen. Um die Prozedur auszuführen, müssen Sie als ADMIN-Benutzer angemeldet sein oder die Berechtigung EXECUTE für DBMS_CLOUD besitzen. 
    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;
/

    In diesem Beispiel werden Dateien aus der Speicherort-URI des Oracle Cloud Infrastructure-Objektspeichers im Bulkverfahren in das Verzeichnisobjekt in einer autonomen KI-Datenbank heruntergeladen.

    Hinweis

    Um die Dateien in das Zielverzeichnisobjekt zu schreiben, benötigen Sie die Berechtigung WRITE für das Verzeichnisobjekt.

    Weitere Informationen finden Sie unter Prozedur BULK_DOWNLOAD.

    Weitere Informationen finden Sie unter DBMS_CLOUD URI-Formate.

Dateien im Cloud-Objektspeicher per Bulkvorgang hochladen

Verwenden Sie die Prozedur DBMS_CLOUD.BULK_UPLOAD, um Dateien aus einem Verzeichnisobjekt in der Datenbank im Bulkverfahren in einen Cloud-Objektspeicherort hochzuladen.

  1. Erstellen Sie Zugangsdaten für den Zugriff auf Ihren Cloud-Objektspeicher.

    Der Zugangsdatenname wird mit dem Parameter credential_name angegeben.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  2. Führen Sie die Prozedur DBMS_CLOUD.BULK_UPLOAD aus, um Dateien aus einem Datenbankverzeichnis in der autonomen KI-Datenbankinstanz in Cloud Object Storage zu kopieren. Um die Prozedur auszuführen, müssen Sie als ADMIN-Benutzer angemeldet sein oder die Berechtigung EXECUTE für DBMS_CLOUD besitzen. 
    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;
/

    In diesem Beispiel werden Dateien per Bulkvorgang aus einem Verzeichnisobjekt hochgeladen, wie mit dem Parameter directory_name angegeben, in die URI des Oracle Cloud Infrastructure-Objektspeichers.

    Hinweis

    Um die Quelldateien im Verzeichnisobjekt zu lesen, benötigen Sie die Berechtigung READ für das Verzeichnisobjekt.

    Weitere Informationen finden Sie unter Prozedur BULK_UPLOAD.

Dateien aus Cloud Object Storage per Bulkvorgang löschen

Verwenden Sie die Prozedur DBMS_CLOUD.BULK_DELETE, um Dateien aus Cloud Object Storage im Bulkverfahren zu löschen.

  1. Erstellen Sie Zugangsdaten für den Zugriff auf Ihren Cloud-Objektspeicher.

    Der Zugangsdatenname wird mit dem Parameter credential_name angegeben.

    Die credential_name kann NULL für eine öffentliche, vorab authentifizierte oder vorab signierte Bucket-URI sein.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

  2. Führen Sie die Prozedur DBMS_CLOUD.BULK_DELETE aus, um Dateien aus dem Cloud-Objektspeicher zu löschen. Um die Prozedur auszuführen, müssen Sie als ADMIN-Benutzer angemeldet sein oder die Berechtigung EXECUTE für DBMS_CLOUD besitzen. 
    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;
/

    In diesem Beispiel werden Dateien im Oracle Cloud Infrastructure-Objektspeicher im Bulkverfahren gelöscht.

    Weitere Informationen finden Sie unter Prozedur BULK_DELETE.

    Weitere Informationen finden Sie unter DBMS_CLOUD URI-Formate.

Massenladevorgänge von Dateien überwachen und Fehler beheben

Alle Dataload-Vorgänge von DBMS_CLOUD werden in den Ansichten dba_load_operations und user_load_operations protokolliert.

Mit den folgenden Ansichten können Sie das Laden von Massendateien überwachen und Fehler beheben:

  • dba_load_operations: Zeigt alle Ladevorgänge an.

  • user_load_operations: Zeigt die Ladevorgänge in Ihrem Schema an.

Fragen Sie diese Ansichten ab, um Informationen zu laufenden und abgeschlossenen Massendateivorgängen anzuzeigen. Beispiel: Die folgende SELECT-Anweisung mit einem Prädikat der WHERE-Klausel in der TYPE zeigt DOWNLOAD-Vorgänge an: 


SELECT owner_name, type, status, start_time, update_time, status_table, rows_loaded 
   FROM user_load_operations WHERE type = 'DOWNLOAD';

OWNER_NAME TYPE     STATUS    START_TIME               UPDATE_TIME              STATUS_TABLE ROWS_LOADED 
---------- -------- --------- ------------------------ ------------------------ ------------ ----------- 
"ADMIN"    DOWNLOAD COMPLETED 2022-10-17T20:42:19.498Z 2022-10-17T20:42:21.054Z DWN$2_STATUS           4 
"ADMIN"    DOWNLOAD FAILED    2022-10-17T20:40:54.348Z 2022-10-17T20:40:55.679Z DWN$1_STATUS

In der Spalte STATUS_TABLE wird der Name der Tabelle angezeigt, die Sie abfragen können, um detaillierte Logginginformationen für den Bulkdownloadvorgang anzuzeigen. Beispiel: 

DESCRIBE DWN$2_STATUS
Name          Null?    Type                        
------------- -------- --------------------------- 
ID            NOT NULL NUMBER                      
NAME                   VARCHAR2(4000)              
BYTES                  NUMBER                      
CHECKSUM               VARCHAR2(128)               
LAST_MODIFIED          TIMESTAMP(6) WITH TIME ZONE 
STATUS                 VARCHAR2(30)                
ERROR_CODE             NUMBER                      
ERROR_MESSAGE          VARCHAR2(4000)              
START_TIME             TIMESTAMP(6) WITH TIME ZONE 
END_TIME               TIMESTAMP(6) WITH TIME ZONE 
SID                    NUMBER                      
SERIAL#                NUMBER                      
ROWS_LOADED            NUMBER                      

SELECT id, name, bytes, status, error_message, start_time, end_time FROM DWN$2_STATUS;
ID NAME       BYTES STATUS    ERROR_MESSAGE START_TIME               END_TIME                 
-- ---------- ----- --------- ------------- ------------------------ ------------------------ 
 1 trees.txt     58 COMPLETED               2022-10-17T20:42:19.998Z 2022-10-17T20:42:20.421Z 
 2 trees1.txt    58 COMPLETED               2022-10-17T20:42:20.425Z 2022-10-17T20:42:20.533Z 
 3 trees2.txt    58 COMPLETED               2022-10-17T20:42:20.535Z 2022-10-17T20:42:20.894Z 
 4 trees3.txt    58 COMPLETED               2022-10-17T20:42:20.896Z 2022-10-17T20:42:21.043Z

In der Statustabelle werden jeder Dateiname und sein Status für den Bulkvorgang angezeigt.

Die entsprechende Fehlernummer und Meldung werden in der Statustabelle aufgezeichnet, wenn ein Vorgang für eine bestimmte Datei fehlschlägt.

Bei abgeschlossenen Vorgängen kann die für jeden Vorgang benötigte Zeit mit der gemeldeten Zeit START_TIME und END_TIME berechnet werden.

Die Spalte STATUS des Dateivorgangs kann einen der folgenden Werte aufweisen:

Datei-Status Beschreibung

COMPLETED

Dateivorgang erfolgreich abgeschlossen.

FAILED

Dateivorgang nicht erfolgreich. Es kann zwei Mal versucht werden, den Vorgang zu wiederholen.

PENDING

Der Dateivorgang wurde noch nicht gestartet.

RUNNING

Dateivorgang wird derzeit ausgeführt.

SKIPPED

Dateivorgang übersprungen.

Wenn ein Dateivorgang nach zwei Wiederholungsversuchen nicht erfolgreich verläuft, wird der Bulkvorgang als nicht erfolgreich markiert, und ein Fehler wird ausgelöst. Beispiel:

ORA-20003: Operation failed, please query table DOWNLOAD$2_STATUS for error details

Wenn Sie einen Bulk-Dateivorgang DBMS_CLOUD verwenden, gibt es format-Parameteroptionen, die Statustabellen steuern:

  • logretention: Gibt einen Ganzzahlwert an, der die Dauer in Tagen festlegt, während der die Statustabelle beibehalten wird. Der Standardwert ist 2 Tage.

  • logprefix: Gibt einen Zeichenfolgenwert an, der das Namenspräfix der Statustabelle für Massenvorgänge bestimmt.

    Jeder Bulkvorgang hat einen eigenen Standardwert für die Option logprefix:

    Verfahren Standardwert für logprefix
    DBMS_CLOUD.BULK_COPY COPYOBJ
    DBMS_CLOUD.BULK_DELETE DELETE
    DBMS_CLOUD.BULK_DOWNLOAD DOWNLOAD
    DBMS_CLOUD.BULK_MOVE MOVE
    DBMS_CLOUD.BULK_UPLOAD UPLOAD

Informationen zum Löschen der Tabelle user_load_operations finden Sie unter DELETE_ALL_OPERATIONS-Prozedur.

Hinweise für Massendateivorgänge

Enthält Hinweise zu den Zugangsdaten, die Sie mit Massendateivorgängen verwenden.

  • Sie können Principals als Parameter credential_name, source_credential_name oder target_credential_name angeben, um sicher auf Cloud-Ressourcen zuzugreifen, ohne Benutzerzugangsdaten zu speichern. Folgende Principals werden unterstützt:

    • Oracle Cloud Infrastructure-Ressourcen-Principals
    • AWS-Amazon-Ressourcennamen (ARN)s
    • Azure-Service-Principal
    • Google-Serviceaccount

    Weitere Informationen finden Sie unter Policys und Rollen zum Zugriff auf Ressourcen konfigurieren.

  • Die Bucket-URI credential_name, source_credential_name oder target_credential_name kann NULL für öffentliche, vorab authentifizierte oder vorab signierte Bucket-URIs sein.