Appeler des services Web à partir d'une base de données autonome basée sur l'IA

Fournit des détails sur l'utilisation de UTL_HTTP pour soumettre une demande HTTP sur un hôte public.

Par exemple, pour soumettre une demande HTTP pour un hôte public www.example.com, créez une liste de contrôle d'accès pour l'hôte :

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'www.example.com',
         ace =>  xs$ace_type( privilege_list => xs$name_list('http'),
                              principal_name => 'ADMIN',
                              principal_type => xs_acl.ptype_db));
END;

Soumettez ensuite la demande HTTP :

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Voir Notes de l'ensemble PL/SQL pour Autonomous AI Database pour plus d'informations sur les restrictions pour UTL_HTTP pour Autonomous AI Database.

Décrit les étapes à suivre pour utiliser UTL_HTTP pour soumettre une demande HTTP sur un hôte privé.

Pour soumettre une demande à un hôte cible sur un point d'extrémité privé, l'hôte cible doit être accessible à partir du VCN Oracle Cloud Infrastructure de la base de données source. Par exemple, vous pouvez vous connecter à l'hôte cible lorsque :

• La base de données source et l'hôte cible se trouvent tous les deux dans le même VCN Oracle Cloud Infrastructure.

• La base de données source et l'hôte cible se trouvent dans différents réseaux en nuage virtuels Oracle Cloud Infrastructure qui sont appariés.

• L'hôte cible est un réseau sur place connecté au VCN Oracle Cloud Infrastructure de la base de données source à l'aide de FastConnect ou d'un RPV.

Vous pouvez également effectuer des appels UTL_HTTP avec un portefeuille géré par le client lorsque votre base de données Autonomous AI Database se trouve sur un point d'extrémité privé. Pour plus d'informations, voir Appels externes à l'aide d'un portefeuille géré par le client.

Pour effectuer une demande UTL_HTTP à une cible sur un point d'extrémité privé :

1. Créez une liste de contrôle d'accès pour l'hôte.

   Exemple :

   BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
            host => 'www.example.com',
            ace => xs$ace_type( privilege_list => xs$name_list('http'),
                                principal_name => 'ADMIN',
                                principal_type => xs_acl.ptype_db),
                                private_target => TRUE);
   END;
   /

   Comme illustré dans cet exemple, lorsque vous créez une liste de contrôle d'accès pour l'hôte, spécifiez le paramètre private_target avec la valeur TRUE.

   Note
   
   Si vous réglez la propriété de base de données ROUTE_OUTBOUND_CONNECTIONS, le paramètre private_target à TRUE n'est pas requis dans cette API. Pour plus d'informations, voir Sécurité améliorée pour les connexions sortantes à l'aide de points d'extrémité privés.

2. Soumettez la demande HTTP :

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Voir Notes de l'ensemble PL/SQL pour Autonomous AI Database pour plus d'informations sur les restrictions pour UTL_HTTP pour Autonomous AI Database.

Lorsque votre instance de base de données IA autonome se trouve sur un point d'extrémité privé, vous pouvez utiliser un mandataire pour soumettre des demandes HTTP avec UTL_HTTP.

1. Définissez la liste de contrôle d'accès HTTP_PROXY sur le serveur mandataire.

   Exemple :

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   Comme illustré dans cet exemple, lorsque vous créez une liste de contrôle d'accès pour le serveur mandataire, spécifiez le paramètre private_target avec la valeur TRUE.

   Note
   
   Si vous réglez la propriété de base de données ROUTE_OUTBOUND_CONNECTIONS, le paramètre private_target à TRUE n'est pas requis dans cette API. Pour plus d'informations, voir Sécurité améliorée pour les connexions sortantes à l'aide de points d'extrémité privés.
2. Définissez la liste de contrôle d'accès HTTP sur le serveur Web distant.

   Exemple :

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
           host =>'example.com',
           ace => xs$ace_type( privilege_list => xs$name_list('HTTP'),
                               principal_name => 'APPUSER1',
                               principal_type => xs_acl.ptype_db)
   END;
   /

3. Définissez le portefeuille et le mandataire pour UTL_HTTP.

   Exemple :

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. Soumettre une demande HTTP :

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

Décrit comment transmettre des objets de données d'identification à la procédure UTL_HTTP.SET_CREDENTIAL.

La procédure UTL_HTTP.SET_CREDENTIAL définit les informations d'authentification HTTP dans l'en-tête de la demande HTTP. Le serveur Web a besoin de ces informations pour autoriser la demande.

La procédure UTL_HTTP.SET_CREDENTIAL vous permet de transmettre des objets de données d'identification pour définir l'authentification HTTP. Les objets de données d'identification sont des objets de schéma. Par conséquent, ils ne sont accessibles que par des utilisateurs dotés de privilèges et vous permettent de configurer des privilèges au niveau du schéma pour contrôler les données d'identification. La transmission d'objets de données d'identification est un moyen approprié et sécurisé de stocker et de gérer le nom d'utilisateur/mot de passe/clés à utiliser pour l'authentification.

La procédure UTL_HTTP.SET_CREDENTIAL est une alternative sûre et pratique à la procédure UTL_HTTP.SET_AUTHENTICATION.

Exemple

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

Comme indiqué dans l'exemple ci-dessus, lorsque vous appelez la procédure SET_AUTHENTICATION, vous devez transmettre le nom utilisateur/mot de passe en texte clair dans le cadre des paramètres formels PL/SQL. Vous devrez peut-être intégrer le nom utilisateur/mot de passe dans divers scripts d'automatisation PL/SQL ou cron. La transmission de mots de passe en texte clair est un problème de conformité qui est traité dans la procédure UTL_HTTP.SET_CREDENTIAL.

Pour plus d'informations, voir Procédure SET_AUTHENTICATION et Procédure SET_AUTHENTICATION_FROM_WALLET.

Syntaxe UTL_HTTP.SET_CREDENTIAL

UTL_HTTP.SET_CREDENTIAL (
    r          IN OUT NOCOPY req,
    credential IN VARCHAR2,
    scheme     IN VARCHAR2 DEFAULT 'Basic',
    for_proxy  IN BOOLEAN  DEFAULT FALSE);

Exemple pour transmettre un objet de données d'identification dans la procédure SET_CREDENTIAL :

• Créez un objet de données d'identification :

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  Cela crée un objet de données d'identification qui crée une paire nom utilisateur/mot de passe stocké.

  Pour plus d'informations, voir ProcédureCREATE_CREDENTIAL.

  Pour plus d'informations, voir Spécification des données d'identification de la tâche du programmateur.

• Appelez la procédure UTL_HTTP.SET_CREDENTIAL :

  DECLARE
        l_http_request  UTL_HTTP.REQ;
      BEGIN 
        l_http_request := UTL_HTTP.BEGIN_REQUEST('https://www.example.com/v1/dwcsdev/NAME/dwcs_small_xt1.csv');
        UTL_HTTP.SET_CREDENTIAL (l_http_request, 'HTTP_CRED','BASIC');
        ...
  END;
  

  Cet exemple crée d'abord une demande en appelant la procédure BEGIN_REQUEST et définit les informations d'authentification HTTP dans l'en-tête de la demande HTTP en appelant la procédure SET_CREDENTIAL. Le serveur Web a besoin de ces informations pour autoriser la demande. La valeur l_http_request est la demande HTTP, HTTP_CRED est le nom des données d'identification et BASIC est le modèle d'authentification HTTP.

Pour plus d'informations, voir UTL_HTTP.

Voir Notes de l'ensemble PL/SQL pour Autonomous AI Database pour plus d'informations sur les restrictions pour UTL_HTTP pour Autonomous AI Database.

Lorsque vous utilisez les commandes SQL Oracle APEX ou la feuille de calcul SQL Database Actions pour exécuter plusieurs commandes SQL séquentielles, ces commandes peuvent être exécutées dans différentes sessions de base de données qui n'enregistrent pas l'état d'une instruction précédente. Ce comportement diffère des clients SQL de bureau tels que SQL*Plus et SQL Developer qui conservent une connexion persistante à la base de données.

Les commandes SQL d'Oracle APEX et les soumissions de feuille de calcul SQL Database Actions à une instance de base de données d'IA autonome sont sans état. Cela signifie que l'exécution d'instructions SQL et PL/SQL individuelles peut enregistrer l'état dans la mémoire de la base de données, par exemple lorsque vous soumettez une commande d'utilisation d'un "wallet", mais que l'état peut être effacé avant l'exécution de l'instruction suivante.

Consultez le tableau suivant pour connaître les étapes à suivre pour conserver l'état de mémoire de la base de données entre les exécutions d'énoncés pour les commandes SQL que vous soumettez à Autonomous AI Database.

Par exemple, utilisez le bloc de code suivant pour exécuter une commande utl_http.request() qui utilise un portefeuille géré par le client :

SELECT utl_http.request(url => 'https://api.example.com/', wallet_path => 'file:path_to_wallet', wallet_password => 'password' ) FROM DUAL";

Comparez cela à l'exécution avec deux énoncés consécutifs qui pourraient échouer si la commande utl_http.set_wallet() et l'énoncé utl_http.request() s'exécutent individuellement, plutôt qu'en tant que bloc de code unique :

EXEC utl_http.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
SELECT utl_http.request('https://api.example.com/') FROM DUAL;

Vous pouvez configurer votre base de données d'intelligence artificielle autonome pour envoyer des informations d'identité de base de données en tant qu'en-têtes HTTP personnalisés lors de la création de demandes HTTP sortantes.

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"DATABASE_OCID"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"TENANT_OCID",
"DATABASE_OCID",
"COMPARTMENT_OCID",
"CLOUD_DOMAIN",
"CLIENT_IP_ADDRESS"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = '*';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'objectstorage.oraclecloud.com';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'oraclecloud.com, example.com';

X-ADB-Source-Database=
  {"databaseName":"MYDATABASENAME",
   "region":"region_identifier",
   "tenantOcid":"tenant_ocid",
   "databaseOcid":"database_ocid",
   "compartmentOcid":"compartment_ocid",
   "clientIpAddress":"client_ip_address"}