Appel de services Web à partir d'Autonomous Database

Décrit les options d'appel de services Web à partir d'Autonomous Database.

Plusieurs options permettent d'appeler des services Web à partir d'Autonomous Database, notamment :

  • Utiliser les API REST DBMS_CLOUD : la fonction DBMS_CLOUD.SEND_REQUEST démarre une demande HTTP, obtient la réponse et met fin à la réponse. Cette fonction fournit un workflow pour l'envoi d'une demande d'API REST cloud avec des arguments et la fonction renvoie un code de réponse et une charge utile. Pour plus d'informations, voir Fonction et procédure SEND_REQUEST.

  • Utilisation d'Oracle APEX : vous pouvez interagir avec les services Web de type SOAP et RESTful à partir d'APEX dans votre instance Autonomous Database. Pour plus d'informations, reportez-vous à Utilisation des services Web avec Oracle APEX.

  • Utilisez UTL_HTTP pour soumettre une demande à un site public. Pour plus d'informations, reportez-vous à Soumettre une demande HTTP à un hôte public.

  • Utilisez UTL_HTTP pour soumettre une demande à un site privé. Pour plus d'informations, reportez-vous à Soumettre une demande HTTP à un hôte privé.

    Lorsque votre instance Autonomous Database se trouve sur une adresse privée, vous pouvez utiliser un portefeuille géré par le client avec des procédures dans UTL_HTTP, DBMS_LDAP, UTL_SMTP ou UTL_TCP. Pour plus d'informations, reportez-vous à Création d'appels externes à l'aide d'un portefeuille géré par le client.

Pour plus d'informations sur les restrictions applicables à UTL_HTTP sur Autonomous Database, reportez-vous à Notes sur le package PL/SQL pour Autonomous Database.

Sujets

Soumettre une demande HTTP à un hôte public

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;

Ensuite, soumettez la demande HTTP :

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

Si votre instance Autonomous Database se trouve sur une adresse privée et que vous voulez que vos appels UTL_HTTP vers des hôtes publics soient soumis aux règles sortantes du VCN de votre adresse privée, définissez la propriété de base de données ROUTE_OUTBOUND_CONNECTIONS sur PRIVATE_ENDPOINT.

Pour plus d'informations, reportez-vous à Sécurité améliorée pour les connexions sortantes avec des adresses privées.

Pour plus d'informations sur les restrictions applicables à UTL_HTTP sur Autonomous Database, reportez-vous à Notes sur le package PL/SQL pour Autonomous Database.

Soumettre une demande HTTP à un hôte privé

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

Pour soumettre une demande à un hôte cible sur une adresse privée, 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 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 cloud virtuels Oracle Cloud Infrastructure couplés.

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

Vous pouvez également effectuer des appels UTL_HTTP avec un portefeuille géré par le client lorsque votre instance Autonomous Database se trouve sur une adresse privée. Pour plus d'informations, reportez-vous à Création d'appels externes à l'aide d'un portefeuille géré par le client.

Pour envoyer une demande UTL_HTTP à une cible sur une adresse privée, procédez comme suit :

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

    Par 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 indiqué dans cet exemple, lorsque vous créez une liste de contrôle d'accès pour l'hôte, indiquez le paramètre private_target avec la valeur TRUE.

    Remarque

    Si vous définissez ROUTE_OUTBOUND_CONNECTIONS sur PRIVATE_ENDPOINT, il n'est pas nécessaire de définir le paramètre private_target sur TRUE dans cette API. Pour plus d'informations, reportez-vous à Sécurité améliorée pour les connexions sortantes avec des adresses privées.
  2. Soumettez la demande HTTP :

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

Pour plus d'informations sur les restrictions applicables à UTL_HTTP sur Autonomous Database, reportez-vous à Notes sur le package PL/SQL pour Autonomous Database.

Soumettre une demande HTTP à un site privé avec un proxy

Lorsque votre instance Autonomous Database se trouve sur une adresse privée, vous pouvez utiliser un proxy pour soumettre des demandes HTTP avec UTL_HTTP.

Lorsque votre instance Autonomous Database se trouve sur une adresse privée, pour utiliser UTL_HTTP avec un proxy cible, le proxy cible doit être accessible à partir du VCN Oracle Cloud Infrastructure de la base de données source.

Par exemple, vous pouvez vous connecter à l'aide d'un proxy lorsque :

  • La base de données source et le serveur proxy se trouvent tous deux dans le même VCN Oracle Cloud Infrastructure.

  • La base de données source et le serveur proxy se trouvent dans différents réseaux cloud virtuels Oracle Cloud Infrastructure couplés.

  • Le serveur proxy est un réseau sur site connecté au réseau Oracle Cloud Infrastructure VCN de la base de données source à l'aide de FastConnect ou du VPN.

Vous pouvez également effectuer des appels UTL_HTTP à l'aide d'un portefeuille géré par le client. Pour plus d'informations, reportez-vous à Création d'appels externes à l'aide d'un portefeuille géré par le client.

Pour utiliser un serveur proxy avec UTL_HTTP, procédez comme suit :

  1. Définissez l'ACL HTTP_PROXY sur le serveur proxy.

    Par 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 indiqué dans cet exemple, lorsque vous créez une liste de contrôle d'accès pour le serveur proxy, indiquez le paramètre private_target avec la valeur TRUE.

    Remarque

    Si vous définissez ROUTE_OUTBOUND_CONNECTIONS sur PRIVATE_ENDPOINT, il n'est pas nécessaire de définir le paramètre private_target sur TRUE dans cette API. Pour plus d'informations, reportez-vous à Sécurité améliorée pour les connexions sortantes avec des adresses privées.
  2. Définissez l'ACL HTTP sur le serveur Web distant.

    Par 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 proxy pour UTL_HTTP.

    Par exemple :

    BEGIN
       UTL_HTTP.SET_WALLET('');
       UTL_HTTP.SET_PROXY('www-proxy-example:80');
    END;
    /
  4. Soumettez une demande HTTP :
    SELECT UTL_HTTP.REQUEST(    
                        url         => 'https://www.example.com/',
                        https_host  => 'www.example.com')
                 FROM dual;

Remarques concernant la définition d'un serveur proxy avec UTL_HTTP.SET_PROXY :

  • Les demandes DBMS_CLOUD ne respectent pas le serveur proxy que vous avez défini avec UTL_HTTP.SET_PROXY. Cela inclut DBMS_CLOUD.SEND_REQUEST et tous les accès au stockage d'objets pour les tables externes DBMS_CLOUD que vous définissez avec DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE ou DBMS_CLOUD.CREATE_HYBRID_PART_TABLE.

  • Les demandes APEX_WEB_SERVICE ne respectent pas le serveur proxy que vous avez défini avec UTL_HTTP.SET_PROXY.

Pour plus d'informations sur les restrictions applicables à UTL_HTTP sur Autonomous Database, reportez-vous à Notes sur le package PL/SQL pour Autonomous Database.

Utiliser des objets d'informations d'identification pour définir l'authentification HTTP

Explique comment transmettre des objets d'informations 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 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 d'informations d'identification pour définir l'authentification HTTP. Les objets d'informations d'identification sont des objets de schéma. Par conséquent, seuls les utilisateurs privilégiés peuvent y accéder et vous permettent de configurer des privilèges de niveau schéma pour accéder au contrôle des informations d'identification. La transmission d'objets d'informations d'identification est un moyen approprié et sécurisé de stocker et de gérer le nom utilisateur/mot de passe/clés à utiliser pour l'authentification.

La procédure UTL_HTTP.SET_CREDENTIAL est une alternative sécurisée 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 cron ou d'automatisation PL/SQL. La transmission de mots de passe en texte clair est un problème de conformité traité dans la procédure UTL_HTTP.SET_CREDENTIAL.

Pour plus d'informations, reportez-vous à 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 de transmission d'un objet d'informations d'identification dans la procédure SET_CREDENTIAL :

  • Créez un objet d'informations d'identification :

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

    Cette opération crée un objet d'informations d'identification qui crée une paire nom utilisateur/mot de passe stockée.

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

    Pour plus d'informations, reportez-vous à Spécification des informations d'identification de travail du planificateur.

  • 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 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 informations d'identification et BASIC est le modèle d'authentification HTTP.

Pour plus d'informations, reportez-vous à UTL_HTTP.

Pour plus d'informations sur les restrictions applicables à UTL_HTTP sur Autonomous Database, reportez-vous à Notes sur le package PL/SQL pour Autonomous Database.

Remarques concernant la soumission de demandes HTTP avec Oracle APEX ou Database Actions

Lorsque vous utilisez Oracle APEX SQL Commands ou Database Actions SQL Worksheet pour exécuter plusieurs commandes SQL séquentielles, les 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 maintiennent une connexion persistante à la base de données.

Les commandes SQL Oracle APEX et les soumissions de feuille de calcul SQL Database Actions à une instance Autonomous Database sont sans conservation de statut. 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 pour utiliser un "wallet", mais que l'état peut être effacé avant d'exécuter 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'instruction pour les commandes SQL que vous soumettez à Autonomous Database.

Outil de commande SQL Soumettre des instructions en tant que bloc
Feuille de calcul SQL Database Actions
  • Sélectionnez toutes les instructions et cliquez sur Exécuter l'instruction.
  • Ne sélectionnez rien et cliquez sur Exécuter en tant que script SQL.
Commandes SQL d'Oracle APEX

Les commandes SQL APEX prennent uniquement en charge l'exécution d'instructions individuelles. Pour exécuter plusieurs instructions, vous devez les encapsuler dans un seul bloc anonyme PL/SQL. Pour exécuter le bloc avec les commandes SQL APEX, cliquez sur Exécuter.

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 instructions consécutives qui pourraient échouer si la commande utl_http.set_wallet() et l'instruction utl_http.request() s'exécutaient 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;