Utiliser des services Web avec Oracle APEX

Il existe plusieurs exigences pour soumettre une demande HTTP à un hôte privé à partir d'Oracle APEX dans votre instance de base de données autonome avec intelligence artificielle.

Pour soumettre une demande à un hôte cible sur un point d'extrémité privé ou derrière des pare-feu sur place, l'hôte cible doit être accessible à partir du VCN Oracle Cloud Infrastructure de la base de données source :

1. Assurez-vous que le point d'extrémité remplit les conditions requises pour soumettre une demande HTTP, comme décrit ici : Soumettre une demande HTTP à un hôte privé avec UTL_HTTP.

2. Ajoutez la liste de contrôle d'accès suivante pour l'hôte souhaité en tant qu'administrateur (notez le paramètre private_target) :

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
       host => 'www.example.com',
       ace => XS$ACE_TYPE(
         privilege_list => XS$NAME_LIST('http'),
         principal_name => APEX_APPLICATION.g_flow_schema_owner,
         principal_type => XS_ACL.ptype_db),
       private_target => true);
   END;
   /

Oracle APEX sur Autonomous AI Database est préconfiguré avec une solution Oracle Wallet qui fonctionnera avec la plupart des points d'extrémité HTTPS. Si vous voulez utiliser des API REST à partir de serveurs qui utilisent des certificats SSL moins courants ou auto-signés, vous pouvez configurer un portefeuille géré par le client.

Oracle APEX sur Autonomous AI Database est préconfiguré avec un Oracle Wallet qui contient plus de 90 certificats SSL racine et intermédiaire de confiance les plus courants. L'ensemble APEX_WEB_SERVICE tire automatiquement parti d'Oracle Wallet sans configuration supplémentaire de la part des développeurs d'applications.

Si vous voulez utiliser des API REST à partir de serveurs qui utilisent des certificats SSL moins courants ou auto-signés, vous pouvez configurer un portefeuille géré par le client. Tout d'abord, suivez les instructions de configuration et de déploiement sous Préalables à l'utilisation d'un portefeuille géré par le client avec des appels externes. Une fois le portefeuille déployé dans votre base de données d'intelligence artificielle autonome, accordez READ sur l'objet de répertoire contenant le portefeuille au schéma de plate-forme APEX en tant que ADMIN :

BEGIN
  execute immediate 'grant READ on directory WALLET_DIR to ' ||
    APEX_APPLICATION.g_flow_schema_owner;
END;

Ensuite, lorsque vous référencez le portefeuille dans les appels d'API APEX_WEB_SERVICE, veillez à utiliser le préfixe DIR: au lieu du préfixe FILE: habituel. Exemple :

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url         => 'https://www.example.com/',
  p_http_method => 'GET',
  p_wallet_path => 'DIR:WALLET_DIR'
);

Vous pouvez également configurer ce portefeuille comme valeur par défaut pour l'ensemble de l'instance Oracle APEX dans Services d'administration APEX en sélectionnant Manage Instance → Instance Settings → Wallet → Wallet Path, ou en définissant le paramètre d'instance WALLET_PATH.

Pour revenir au portefeuille préconfiguré, réglez WALLET_PATH à une valeur vide.

Pour plus d'informations, voir Accéder aux services d'administration d'Oracle APEX.

Votre instance Oracle APEX ne nécessite pas de mandataire Web sortant pour effectuer des appels d'API REST externes. Les bases de données autonomes d'IA configurées avec un point d'extrémité privé peuvent utiliser un mandataire Web déployé dans votre VCN, au besoin.

Pour utiliser un mandataire Web, définissez la liste de contrôle d'accès suivante comme ADMIN :

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host           => 'www-proxy.example.com',
    lower_port     => 80,
    ace => XS$ACE_TYPE( 
      privilege_list => XS$NAME_LIST('HTTP_PROXY'),
      principal_name => APEX_APPLICATION.g_flow_schema_owner,
      principal_type => XS_ACL.ptype_db),
    private_target => true);
END;
/

Vous pouvez ensuite utiliser le mandataire Web dans les appels d'API APEX_WEB_SERVICE :

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url            => 'https://www.example.com/',
  p_http_method    => 'GET',
  p_proxy_override => 'www-proxy.example.com:80'
);

Vous pouvez également configurer un mandataire Web au niveau de l'application en définissant la propriété Serveur mandataire dans la page Composants partagés → Définition de l'application → Propriétés, ou au niveau de l'instance dans Services d'administration APEX à partir de Gérer l'instance → Sécurité → Mandataire de l'instance.

Si vous tentez d'utiliser un mandataire Web lorsque votre base de données IA autonome est configurée avec un point d'extrémité public, une erreur est retournée :

ORA-01031: insufficient privileges

Voir Soumettre une demande HTTP à un hôte privé avec UTL_HTTP pour plus d'informations sur les mandataires lors de l'utilisation de l'API UTL_HTTP.

Pour plus d'informations, voir Accéder aux services d'administration d'Oracle APEX.

Fournit des notes sur l'utilisation des services Web dans Oracle APEX à partir d'une instance de base de données autonome avec intelligence artificielle.

Notez ce qui suit lorsque vous utilisez des services Web dans Oracle APEX :

• Tous les services Web doivent être sécurisés. Seuls les services HTTPS sont pris en charge sur le port par défaut (443). Les connexions au moyen d'adresses IP ne sont pas autorisées.

• Chaque instance de base de données Autonomous AI Database est préconfigurée avec une liste de contrôle d'accès au réseau (ACL) pour permettre les appels de service Web sortants d'Oracle APEX vers des points d'extrémité publics.

• Les demandes APEX_WEB_SERVICE ne respectent pas le portefeuille personnalisé que vous avez défini avec les appels d'API UTL_HTTP.SET_WALLET.

• Il y a une limite par défaut de 1 000 demandes de service Web sortantes par espace de travail APEX sur une période continue de 24 heures (cela s'applique aux nouvelles bases de données, certaines bases de données plus anciennes peuvent avoir une limite plus élevée). Si la limite des appels de service Web sortants est atteinte, l'exception SQL suivante est générée lors de la demande suivante et la demande est bloquée :

  ORA-20001: You have exceeded the maximum number of web service requests per workspace. Please contact your administrator.

  Vous pouvez augmenter ou supprimer la limite par défaut des demandes de service Web sortantes en définissant une valeur pour le paramètre d'instance MAX_WEBSERVICE_REQUESTS ou en mettant à jour l'attribut Nombre maximal de demandes de service Web dans les services d'administration APEX. Par exemple, pour modifier la limite à 250 000, connectez-vous à votre base de données en tant qu'administrateur ADMIN à l'aide d'un client SQL et exécutez les opérations suivantes :

  BEGIN
    APEX_INSTANCE_ADMIN.SET_PARAMETER('MAX_WEBSERVICE_REQUESTS', '250000');
    COMMIT;
  END;
  /

Pour en savoir plus, voir :

• APEX_WEB_SERVICE dans Informations de référence sur les API Oracle APEX

• Gestion des sources de données REST dans le guide de l'utilisateur du générateur d'applications Oracle APEX