Documentation Oracle Cloud Infrastructure

Opérations en masse pour des fichiers dans le cloud

Le package PL/SQL DBMS_CLOUD offre une prise en charge de l'exécution en parallèle pour les activités de téléchargement, de téléchargement, de copie et de transfert de fichiers en masse, ce qui rationalise l'expérience utilisateur et offre des performances optimales pour les opérations de fichiers en masse.

Le package DBMS_CLOUD prend en charge le chargement et le déchargement de fichiers dans les services cloud suivants :

  • Oracle Cloud Infrastructure Object Storage

  • Stockage Azure Blob ou stockage Azure Data Lake

  • Amazon S3

  • Compatible avec Amazon S3, y compris Wasabi Hot Cloud Storage

  • Google Cloud Storage

Pour plus d'informations, reportez-vous à DBMS_CLOUD Package File URI Formats.

Rubrique parent : Déplacement de fichiers

A propos des opérations de fichiers en masse

DBMS_CLOUD Les opérations de fichier en masse prennent en charge le téléchargement et le téléchargement de fichiers sur une base de données Autonomous AI, y compris la prise en charge de la copie, du déplacement et de la suppression de fichiers dans les banques d'objets cloud, soit au sein du même fournisseur de banque d'objets, soit entre les fournisseurs de banque d'objets.

Les opérations de fichier en masse prennent en charge le parallélisme et offrent des performances optimales pour le téléchargement, le téléchargement, la copie et le déplacement de fichiers. Le parallélisme pour les opérations de fichier en masse est géré en indiquant une priorité pour une opération. Les priorités soutenues sont les suivantes :

  • HIGH : utilisez le nombre de calcul d'UC d'instance de base de données Autonomous AI pour déterminer le nombre de fichiers parallèles traités.
  • MEDIUM : utilisez la limite de simultanéité pour le service moyen afin de déterminer le parallélisme.
  • LOW : traite les fichiers dans l'ordre série (pas de simultanéité).

L'exécution d'opérations en masse avec une priorité plus élevée utilise davantage de ressources de base de données et les opérations sont terminées plus rapidement lorsque le parallélisme peut accélérer l'opération. Une priorité inférieure consomme moins de ressources de base de données et les opérations prennent plus de temps à se terminer lorsque le parallélisme peut accélérer l'opération. Lorsque les opérations en masse impliquent un petit nombre de fichiers qui contiennent peu de données, la spécification d'une priorité plus élevée peut ne pas modifier les performances.

Afin d'augmenter le parallélisme pour les opérations de fichiers en masse, utilisez la priorité HIGH et augmentez le nombre d'UC affectées à votre instance de base de données Autonomous AI. Le nombre maximal d'opérations de fichier simultané prises en charge est limité à 64 pour les opérations de fichier en masse.

La priorité par défaut est MEDIUM, qui indique que les opérations de fichier en masse utilisent la limite de simultanéité définie pour le groupe de consommateurs de ressources MEDIUM. Pour plus d'informations, reportez-vous à Gestion de la simultanéité et des priorités sur la base de données d'IA autonome.

Pour plus d'informations sur l'utilisation du paramètre format afin de spécifier priority avec des opérations de fichier en masse, reportez-vous à DBMS_CLOUD pour la gestion de fichiers en masse.

Copier des fichiers en masse dans Cloud Object Storage

Utilisez la procédure DBMS_CLOUD.BULK_COPY pour copier en masse des fichiers d'un bucket ou dossier de banque d'objets vers un autre bucket ou dossier.

  1. Créez un objet d'informations d'identification pour accéder à l'emplacement source.

    Par défaut, le nom des informations d'identification source, tel qu'indiqué avec le paramètre source_credential_name, est également utilisé comme informations d'identification pour l'emplacement cible.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

  2. Lorsque la source et la cible se trouvent dans des banques d'objets distinctes ou ont des comptes différents avec le même fournisseur cloud, créez des informations d'identification pour accéder à l'emplacement cible et inclure le paramètre target_credential_name.
  3. Exécutez la procédure DBMS_CLOUD.BULK_COPY pour copier des fichiers en parallèle d'un bucket ou d'un dossier de banque d'objets vers un autre bucket ou dossier qui peut se trouver entre les fournisseurs cloud, les comptes et les buckets. Pour exécuter la procédure, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur DBMS_CLOUD. 
    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;
/

    Cet exemple copie en masse des fichiers d'un bucket Oracle Cloud Infrastructure Object Storage vers un autre.

    Pour plus d'informations, reportez-vous à Procédure BULK_COPY.

    Pour plus d'informations, reportez-vous à la section DBMS_CLOUD URI Formats.

Par exemple, utilisez DBMS_CLOUD.BULK_COPY pour copier des fichiers d'Amazon S3 vers Oracle Cloud Infrastructure Object Storage. 

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;
/

Déplacement en masse de fichiers dans Cloud Object Storage

Utilisez la procédure DBMS_CLOUD.BULK_MOVE pour déplacer en masse des fichiers d'un emplacement Cloud Object Storage vers un autre.

La première étape du déplacement des fichiers consiste à les copier vers l'emplacement cible. Une fois les fichiers copiés, ils sont supprimés de l'emplacement source.

Les fichiers sont renommés plutôt que copiés si la banque d'objets permet de renommer les opérations entre les emplacements source et cible.

  1. Créez un objet d'informations d'identification pour accéder à l'emplacement source.

    Par défaut, le nom des informations d'identification source, tel qu'indiqué avec le paramètre source_credential_name, est également utilisé comme informations d'identification pour l'emplacement cible.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

  2. Lorsque la source et la cible se trouvent dans des banques d'objets distinctes ou ont des comptes différents avec le même fournisseur cloud, créez des informations d'identification pour accéder à l'emplacement cible et inclure le paramètre target_credential_name.
  3. Exécutez la procédure DBMS_CLOUD.BULK_MOVE pour déplacer en masse des fichiers d'un emplacement Cloud Object Storage vers un autre. Pour exécuter la procédure, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur DBMS_CLOUD. 
    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;
/

    Cet exemple montre comment déplacer en masse des fichiers d'un emplacement Oracle Cloud Infrastructure Object Storage vers un autre.

    Pour plus d'informations, reportez-vous à Procédure BULK_MOVE.

    Pour plus d'informations, reportez-vous à la section DBMS_CLOUD URI Formats.

Par exemple, utilisez DBMS_CLOUD.BULK_MOVE pour déplacer des fichiers d'Amazon S3 vers Oracle Cloud Infrastructure Object Storage. 

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;
/

Téléchargement en masse de fichiers à partir de Cloud Object Storage

Utilisez la procédure DBMS_CLOUD.BULK_DOWNLOAD pour télécharger en masse des fichiers à partir de l'emplacement de la banque d'objets cloud vers l'objet de répertoire dans une base de données Autonomous AI.

  1. Créez des informations d'identification pour accéder au stockage d'objet cloud.

    Le nom des informations d'identification est indiqué avec le paramètre credential_name.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

  2. Exécutez la procédure DBMS_CLOUD.BULK_DOWNLOAD pour télécharger des fichiers dans un répertoire Autonomous Database à partir de Cloud Object Storage. Pour exécuter la procédure, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur DBMS_CLOUD. 
    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;
/

    Cet exemple télécharge en masse des fichiers à partir de l'URI d'emplacement de la banque d'objets Oracle Cloud Infrastructure vers l'objet de répertoire dans une base de données Autonomous AI.

    Remarque

    Pour écrire les fichiers dans l'objet de répertoire cible, vous devez disposer du privilège WRITE sur l'objet de répertoire.

    Pour plus d'informations, reportez-vous à Procédure BULK_DOWNLOAD.

    Pour plus d'informations, reportez-vous à la section DBMS_CLOUD URI Formats.

Téléchargement en masse de fichiers vers Cloud Object Storage

Utilisez la procédure DBMS_CLOUD.BULK_UPLOAD pour télécharger en masse des fichiers d'un objet de répertoire dans la base de données vers un emplacement de banque d'objets cloud.

  1. Créez des informations d'identification pour accéder au stockage d'objet cloud.

    Le nom des informations d'identification est indiqué avec le paramètre credential_name.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

  2. Exécutez la procédure DBMS_CLOUD.BULK_UPLOAD pour copier des fichiers dans Cloud Object Storage à partir d'un répertoire de base de données sur votre instance de base de données Autonomous AI. Pour exécuter la procédure, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur DBMS_CLOUD. 
    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;
/

    Cet exemple télécharge en masse des fichiers à partir d'un objet de répertoire, comme indiqué avec le paramètre directory_name vers l'URI d'emplacement de la banque d'objets Oracle Cloud Infrastructure.

    Remarque

    Pour lire les fichiers source dans l'objet répertoire, vous devez disposer du privilège READ sur l'objet répertoire.

    Pour plus d'informations, reportez-vous à Procédure BULK_UPLOAD.

Suppression en masse de fichiers dans Cloud Object Storage

Utilisez la procédure DBMS_CLOUD.BULK_DELETE pour supprimer en masse des fichiers de Cloud Object Storage.

  1. Créez des informations d'identification pour accéder au stockage d'objet cloud.

    Le nom des informations d'identification est indiqué avec le paramètre credential_name.

    credential_name peut être NULL pour un URI de bucket public, pré-authentifié ou pré-signé.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

  2. Exécutez la procédure DBMS_CLOUD.BULK_DELETE pour supprimer des fichiers de la banque d'objets cloud. Pour exécuter la procédure, vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur DBMS_CLOUD. 
    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;
/

    Cet exemple supprime en masse des fichiers de la banque d'objets Oracle Cloud Infrastructure.

    Pour plus d'informations, reportez-vous à Procédure BULK_DELETE.

    Pour plus d'informations, reportez-vous à la section DBMS_CLOUD URI Formats.

Surveiller et dépanner les chargements de fichiers en masse

Toutes les opérations de chargement de données DBMS_CLOUD sont journalisées dans les vues dba_load_operations et user_load_operations.

Vous pouvez utiliser les vues suivantes pour surveiller et dépanner les chargements de fichiers en masse :

  • dba_load_operations affiche toutes les opérations de chargement.

  • user_load_operations affiche les opérations de chargement dans votre schéma.

Interrogez ces vues pour afficher des informations sur les opérations de fichier en masse en cours et terminées. Par exemple, l'instruction SELECT suivante avec un prédicat de clause WHERE sur TYPE affiche les opérations DOWNLOAD : 


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

La colonne STATUS_TABLE indique le nom de la table que vous pouvez interroger pour consulter les informations de journalisation détaillées de l'opération de téléchargement en masse. Par exemple : 

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

Le tableau des statuts indique le nom de chaque fichier et son statut pour l'opération en masse.

Le numéro d'erreur et le message appropriés sont enregistrés dans la table des statuts en cas d'échec d'une opération sur un fichier spécifique.

Pour les opérations terminées, le temps nécessaire à chaque opération peut être calculé à l'aide des temps START_TIME et END_TIME signalés.

La colonne d'opération de fichier STATUS peut avoir l'une des valeurs suivantes :

Statut du fichier Description

COMPLETED

L'opération de fichier est terminée.

FAILED

Echec de l'opération de fichier. Une nouvelle tentative peut être tentée deux fois.

PENDING

L'opération de fichier n'a pas encore démarré.

RUNNING

L'opération de fichier est en cours.

SKIPPED

Opération de fichier ignorée.

Si une opération de fichier échoue après deux tentatives, l'opération en masse est marquée comme ayant échoué et une erreur est générée. Par exemple :

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

Lorsque vous utilisez une opération de fichier en masse DBMS_CLOUD, des options de paramètre format contrôlent les tables de statut :

  • logretention : indique une valeur entière qui détermine la durée en jours pendant laquelle la table de statut est conservée. La valeur par défaut est de 2 jours.

  • logprefix : indique une valeur de chaîne qui détermine le préfixe de nom de la table de statut d'opération en masse.

    Chaque opération en masse possède sa propre valeur par défaut pour l'option logprefix :

    Procédure Valeur par défaut pour 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

Pour plus d'informations sur l'effacement de la table user_load_operations, reportez-vous à Procédure DELETE_ALL_OPERATIONS.

Notes pour les opérations de fichier en masse

Fournit des notes sur les informations d'identification que vous utilisez avec les opérations de fichier en masse.

  • Vous pouvez indiquer des principaux en tant que paramètre credential_name, source_credential_name ou target_credential_name pour accéder aux ressources cloud en toute sécurité sans stocker les informations d'identification utilisateur. Les principaux pris en charge sont :

    • Principaux de ressource Oracle Cloud Infrastructure
    • Noms de ressource AWS Amazon (ARN)
    • Principal de service Azure
    • Compte de service Google

    Pour plus d'informations, reportez-vous à Configuration de stratégies et de rôles pour accéder aux ressources.

  • credential_name, source_credential_name ou target_credential_name peut être NULL pour l'URI de bucket public, pré-authentifié ou pré-signé.