API REST de DBMS_CLOUD

This section covers the DBMS_CLOUD REST APIs provided with Autonomous AI Database on Dedicated Exadata Infrastructure.

Rubriques connexes

Conditions requises

En tant que développeur, vous pouvez utiliser des procédures DBMS_CLOUD avec les bases de données autonomes d'IA déployées sur Oracle Public Cloud, Multicloud ou Exadata Cloud@Customer.

Selon le choix de déploiement, les préalables suivants doivent être satisfaits pour utiliser les API REST DBMS_CLOUD avec les fournisseurs de services Amazon S3, Azure Blob Storage et Google Cloud Storage.

Une connectivité sortante doit avoir été configurée à l'aide d'une passerelle NAT par l'administrateur de votre parc, comme décrit ci-dessous :
  • Créez une passerelle NAT dans le réseau en nuage virtuel (VCN) où résident vos ressources de base de données d'intelligence artificielle autonome en suivant les instructions sous Créer une passerelle NAT dans la documentation sur Oracle Cloud Infrastructure.
  • Après avoir créé la passerelle NAT, ajoutez une règle de routage et une règle de sécurité sortante à chaque sous-réseau (dans le VCN) où résident les ressources du service Base de données d'intelligence artificielle autonome afin que ces ressources puissent utiliser la passerelle pour obtenir une clé publique de votre instance Azure AD :
    1. Allez à la page Détails du sous-réseau correspondante.
    2. Dans l'onglet Informations sur le sous-réseau, cliquez sur le nom de la table de routage du sous-réseau pour afficher la page Détails de la table de routage.
    3. Dans la table des règles de routage existantes, vérifiez s'il existe déjà une règle présentant les caractéristiques suivantes :
      • Destination : 0.0.0.0/0
      • Type de cible : Passerelle NAT
      • Target : Nom de la passerelle NAT que vous venez de créer dans le VCN

      Si une telle règle n'existe pas, cliquez sur Ajouter des règles de routage et ajoutez une règle de routage avec ces caractéristiques.

    4. Retournez à la page Détails du sous-réseau.
    5. Dans la table Listes de sécurité du sous-réseau, cliquez sur le nom de la liste de sécurité du sous-réseau pour afficher la page Détails de la liste de sécurité.
    6. Dans le menu latéral, sous Ressources, cliquez sur Règles de trafic sortant.
    7. Dans la table des règles de trafic sortant existantes, vérifiez s'il existe déjà une règle présentant les caractéristiques suivantes :
      • Type de destination : CIDR
      • Destination : 0.0.0.0/0
      • Protocole IP : TCP
      • Intervalle de ports sources : 443
      • Intervalle de ports de destination : Tout

      Si une telle règle n'existe pas, cliquez sur Ajouter des règles de trafic sortant et ajoutez une règle de trafic sortant avec ces caractéristiques.

Les paramètres de mandataire HTTP de votre environnement doivent permettre à la base de données d'accéder au fournisseur de services en nuage.

Ces paramètres sont définis par l'administrateur de votre parc lors de la création de l'infrastructure Exadata Cloud@Customer, comme décrit dans Utilisation de la console pour provisionner le service Exadata Database sur Cloud@Customer.

Note :

La configuration réseau, y compris le mandataire HTTP, ne peut être modifiée que jusqu'à ce que l'infrastructure Exadata ait l'état Activation requise. Une fois activé, vous ne pouvez pas modifier ces paramètres.

La configuration d'un mandataire HTTP pour une infrastructure Exadata déjà provisionnée nécessite une demande de service dans My Oracle Support. Pour plus de détails, voir Créer une demande de service dans My Oracle Support.

API REST de DBMS_CLOUD

Cette section présente les API REST DBMS_CLOUD fournies avec la base de données autonome d'IA.

API REST Description

Fonction GET_RESPONSE_HEADERS

 Cette fonction retourne les en-têtes de réponse HTTP en tant que données JSON dans un objet JSON dans Autonomous AI Database.

Fonction GET_RESPONSE_TEXT

 Cette fonction retourne la réponse HTTP au format TEXT (VARCHAR2 ou CLOB) dans Autonomous AI Database. Habituellement, la plupart des API REST en nuage retournent une réponse JSON au format texte. Cette fonction est utile si vous pensez que la réponse HTTP est au format texte.

Fonction GET_API_RESULT_CACHE_SIZE

Cette fonction retourne la taille configurée du cache de résultats.

Fonction et procédure SEND_REQUEST

 Cette fonction commence une demande HTTP, obtient la réponse et met fin à la réponse dans Autonomous AI Database. Cette fonction fournit un flux de travail pour envoyer une demande d'API REST en nuage avec des arguments, un code de réponse de retour et des données utiles.

Procédure SET_API_RESULT_CACHE_SIZE

Cette procédure définit la taille maximale du cache pour la session courante.

Aperçu des API REST de DBMS_CLOUD

Lorsque vous utilisez PL/SQL dans votre application et que vous devez appeler des API REST en nuage, vous pouvez utiliser DBMS_CLOUD.SEND_REQUEST pour envoyer les demandes d'API REST.

Les fonctions d'API REST de DBMS_CLOUD vous permettent d'effectuer des demandes HTTP à l'aide de DBMS_CLOUD.SEND_REQUEST, d'obtenir des résultats et de les enregistrer. Ces fonctions fournissent une API générique qui vous permet d'appeler une API REST avec les services en nuage pris en charge suivants :

Constantes des API REST de DBMS_CLOUD

Décrit les constantes de DBMS_CLOUD pour effectuer des demandes HTTP à l'aide de DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD prend en charge les méthodes HTTP GET, PUT, POST, HEAD et DELETE. La méthode d'API REST à utiliser pour une demande HTTP est généralement décrite dans la documentation sur les API REST en nuage.

Nom Type Valeur
METHOD_DELETE VARCHAR2(6) 'DELETE'
METHOD_GET VARCHAR2(3) 'GET'
METHOD_HEAD VARCHAR2(4) 'HEAD'
METHOD_POST VARCHAR2(4) 'POST'
METHOD_PUT VARCHAR2(3) 'PUT'

Cache de résultats des API REST de DBMS_CLOUD

Vous pouvez enregistrer les résultats des API REST de DBMS_CLOUD lorsque vous réglez le paramètre cache à True avec DBMS_CLOUD.SEND_REQUEST. La vue SESSION_CLOUD_API_RESULTS décrit les colonnes que vous pouvez utiliser lorsque les résultats des API REST sont enregistrés.

Par défaut, les appels d'API REST de DBMS_CLOUD n'enregistrent pas de résultats pour votre session. Dans ce cas, vous utilisez la fonction DBMS_CLOUD.SEND_REQUEST pour retourner les résultats.

Lorsque vous utilisez DBMS_CLOUD.SEND_REQUEST et réglez le paramètre cache à TRUE, les résultats sont enregistrés et vous pouvez voir les résultats précédents dans la vue SESSION_CLOUD_API_RESULTS. L'enregistrement et l'interrogation des résultats historiques des demandes d'API REST de DBMS_CLOUD peuvent vous aider lorsque vous avez besoin des résultats précédents dans vos applications.

Par exemple, pour interroger les résultats récents des API REST de DBMS_CLOUD, utilisez la vue SESSION_CLOUD_API_RESULTS : 

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Lorsque vous enregistrez les résultats des API REST de DBMS_CLOUD avec DBMS_CLOUD.SEND_REQUEST, les données enregistrées ne sont disponibles que dans la même session (connexion). Une fois la session terminée, les données enregistrées ne sont plus disponibles.

Utilisez DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE et DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE pour voir et définir la taille du cache des API REST de DBMS_CLOUD et pour désactiver la mise en cache.

Paramètre cache_scope des résultats des API REST de DBMS_CLOUD

Lorsque vous enregistrez les résultats des API REST de DBMS_CLOUD avec DBMS_CLOUD.SEND_REQUEST, l'accès aux résultats dans SESSION_CLOUD_API_RESULTS est accordé en fonction de la valeur de cache_scope.

Par défaut, cache_scope est réglé à 'PRIVATE' et seul l'utilisateur courant de la session peut accéder aux résultats. Si vous réglez cache_scope à 'PUBLIC', tous les utilisateurs de la session peuvent accéder aux résultats. La valeur par défaut de cache_scope indique que chaque utilisateur peut uniquement voir les résultats de l'API REST DBMS_CLOUD.SEND_REQUEST générés par les procédures qu'il appelle avec les droits d'appelant. Lorsque vous appelez DBMS_CLOUD.SEND_REQUEST dans une session, trois possibilités déterminent si l'utilisateur courant peut voir les résultats dans le cache, en fonction de la valeur cache_scope :

  • Vous exécutez directement DBMS_CLOUD.SEND_REQUEST en tant qu'énoncé de niveau supérieur et l'appel à DBMS_CLOUD.SEND_REQUEST ainsi que les résultats de l'API REST sont enregistrés avec le même nom d'utilisateur. Dans ce cas, vous avez accès à tous les résultats avec cache_scope réglé à la valeur par défaut, 'PRIVATE'.

  • Vous écrivez une procédure avec les droits d'appelant de l'encapsuleur et, en tant qu'utilisateur courant, votre appel de DBMS_CLOUD.SEND_REQUEST appelle la procédure et les résultats de l'API REST sont enregistrés avec le même nom d'utilisateur. Dans ce cas, vous avez accès à tous les résultats avec cache_scope réglé à la valeur par défaut, 'PRIVATE'.

  • Vous écrivez une procédure avec les droits de créateur de l'encapsuleur et un autre utilisateur est responsable de la procédure. Lorsque vous appelez DBMS_CLOUD.SEND_REQUEST dans la procédure, les résultats sont enregistrés avec le nom d'utilisateur du responsable de la procédure.

    Dans ce cas, l'utilisateur des droits d'un autre créateur appelle DBMS_CLOUD.SEND_REQUEST et les résultats de l'API REST sont enregistrés avec le responsable de cette procédure. Dans ce cas, par défaut, lorsque cache_scope est réglé à PRIVATE', la session de l'appelant ne peut pas voir les résultats.

    Si le responsable de la procédure du créateur veut rendre les résultats disponibles pour tout utilisateur de la session d'appel, il doit régler cache_scope à 'PUBLIC' dans DBMS_CLOUD.SEND_REQUEST.

Vue SESSION_CLOUD_API_RESULTS des API REST de DBMS_CLOUD

Vous pouvez enregistrer les résultats des API REST de DBMS_CLOUD lorsque vous réglez le paramètre cache à True avec DBMS_CLOUD.SEND_REQUEST. La vue SESSION_CLOUD_API_RESULTS décrit les colonnes que vous pouvez utiliser lorsque les résultats des API REST sont enregistrés.

La vue SESSION_CLOUD_API_RESULTS est la vue créée si vous mettez en cache les résultats avec DBMS_CLOUD.SEND_REQUEST. Vous pouvez interroger les résultats historiques appartenant à votre session d'utilisateur. Une fois la session terminée, les données de SESSION_CLOUD_API_RESULTS sont épurées.

Colonne Description
URI URL de demande d'API REST DBMS_CLOUD
TIMESTAMP Horodatage de réponse d'API REST DBMS_CLOUD
CLOUD_TYPE Type en nuage d'API REST DBMS_CLOUD, par exemple Oracle Cloud Infrastructure et AZURE_BLOB
REQUEST_METHOD Méthode de demande d'API REST DBMS_CLOUD, par exemple GET, PUT, HEAD
REQUEST_HEADERS En-têtes de demande d'API REST DBMS_CLOUD
REQUEST_BODY_TEXT Corps de demande d'API REST DBMS_CLOUD de type CLOB
RESPONSE_STATUS_CODE Code de statut de réponse d'API REST DBMS_CLOUD, par exemple 200(OK), 404(Not Found)
RESPONSE_HEADERS En-têtes de réponse d'API REST DBMS_CLOUD
RESPONSE_BODY_TEXT Corps de réponse d'API REST DBMS_CLOUD de type CLOB
SCOPE

Valeur de cache_scope définie par DBMS_CLOUD.SEND_REQUEST. Les valeurs valides sont PUBLIC ou PRIVATE.

Fonction GET_RESPONSE_HEADERS

Cette fonction retourne les en-têtes de réponse HTTP en tant que données JSON dans un objet JSON.

Syntaxe

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Paramètres

Paramètre Description
resp

Type de réponse HTTP retourné par DBMS_CLOUD.SEND_REQUEST.

Exceptions

Exception Error Description
invalid_response ORA-20025

Objet de type de réponse non valide transmis à DBMS_CLOUD.GET_RESPONSE_HEADERS.

Fonction GET_RESPONSE_TEXT

Cette fonction retourne la réponse HTTP au format TEXT (VARCHAR2 ou CLOB). En général, la plupart des API REST en nuage retournent une réponse JSON au format texte. Cette fonction est utile si vous pensez que la réponse HTTP est au format texte.

Syntaxe

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Paramètres

Paramètre Description
resp

Type de réponse HTTP retourné par DBMS_CLOUD.SEND_REQUEST.

Exceptions

Exception Error Description
invalid_response ORA-20025

Objet de type de réponse non valide transmis à DBMS_CLOUD.GET_RESPONSE_TEXT.

Fonction GET_API_RESULT_CACHE_SIZE

Cette fonction retourne la taille configurée du cache de résultats. La valeur de taille du cache s'applique uniquement à la session courante.

Syntaxe

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Fonction et procédure SEND_REQUEST

Cette fonction et procédure démarre lance une demande HTTP, obtient la réponse et met fin à la réponse. Cette fonction fournit un flux de travail pour l'envoi d'une demande d'API REST en nuage avec des arguments et retourne un code de réponse et des données utiles. Si vous utilisez la procédure, vous pouvez voir les résultats et les détails de la réponse dans les résultats enregistrés à l'aide de la vue SESSION_CLOUD_API_RESULTS.

Syntaxe

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Paramètres

Paramètre Description

credential_name

Nom des données d'identification pour l'authentification avec l'API en nuage native correspondante.
uri

URI HTTP pour effectuer la demande.
method

Méthode de demande HTTP : GET, PUT, POST, HEAD, DELETE. Utilisez la constante de l'ensemble DBMS_CLOUD pour spécifier la méthode.

Pour plus d'informations, voir Constantes des API REST de DBMS_CLOUD.

headers

En-têtes de demande HTTP pour l'API native en nuage correspondante au format JSON. Les en-têtes d'authentification sont définis automatiquement. Ne transmettez que les en-têtes personnalisés.

async_request_url

URL de demande asynchrone.

Pour obtenir l'URL, sélectionnez votre API de demande dans la liste des API (voir https://docs.cloud.oracle.com/en-us/iaas/api/). Ensuite, naviguez pour trouver l'API de votre demande dans le volet de gauche. Par exemple, API des services de base de données → Base de données Autonomous AI Database → StopAutonomousDatabase. Cette page présente le répertoire de base de l'API (et le point d'extrémité de base). Ajoutez ensuite le point d'extrémité de base avec le chemin relatif obtenu pour le lien WorkRequest de votre demande de travail.

wait_for_states

Il s'agit d'un statut de type : DBMS_CLOUD_TYPES.wait_for_states_t. Les valeurs suivantes sont valides pour les états attendus : 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

Plusieurs états sont autorisés pour wait_for_states. La valeur par défaut de wait_for_states est d'attendre l'un des états suivants : 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

timeout

Spécifie la temporisation, en secondes, pour les demandes asynchrones avec les paramètres async_request_url et wait_for_states.

La valeur par défaut est 0. Indique qu'il faut attendre l'achèvement de la demande sans temporisation.

cache

La valeur TRUE indique que la demande doit être mise en cache dans le cache de l'API REST de résultats.

La valeur par défaut est FALSE, ce qui signifie que les demandes d'API REST ne sont pas mises en cache.

cache_scope

Indique si tout le monde peut accéder à ce cache de résultats de demande. Les valeurs valides sont les suivantes : "PRIVATE" et "PUBLIC". La valeur par défaut est "PRIVATE".

body

Corps de demande HTTP pour les demandes PUT et POST.

Exceptions

Exception Error Description
invalid_req_method ORA-20023

La méthode de demande transmise à DBMS_CLOUD.SEND_REQUEST n'est pas valide.

invalid_req_header ORA-20024

Les en-têtes de demande transmis à DBMS_CLOUD.SEND_REQUEST ne sont pas dans un format JSON valide.

Notes d'utilisation

  • Si vous utilisez Oracle Cloud Infrastructure, vous devez utiliser une valeur de données d'identification basée sur une clé de signature pour credential_name. Pour plus d'informations, voir Procédure CREATE_CREDENTIAL.

  • Les paramètres facultatifs async_request_url, wait_for_states et timeout vous permettent de traiter les demandes de longue durée. Avec cette forme asynchrone de send_request, la fonction attend le statut d'achèvement spécifié dans wait_for_states avant de retourner un résultat. Avec ces paramètres dans la demande d'envoi, vous transmettez les états de retour attendus dans le paramètre wait_for_states et vous utilisez le paramètre async_request_url pour spécifier une demande de travail associée. La demande n'est pas retournée immédiatement. La demande sonde async_request_url jusqu'à ce que l'état de retour soit l'un des états attendus ou que la valeur de timeout soit dépassée (le paramètre timeout est facultatif). Si aucune valeur n'est spécifiée pour timeout, la demande attend l'un des états indiqués dans wait_for_states.

Procédure SET_API_RESULT_CACHE_SIZE

Cette procédure définit la taille maximale du cache pour la session courante. La valeur de taille du cache s'applique uniquement à la session courante.

Syntaxe

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Paramètres

Paramètre Description
cache_size

Règle la taille maximale du cache à la valeur de cache_size spécifiée. Si la nouvelle taille maximale du cache est inférieure à la taille courante, les enregistrements les plus anciens sont supprimés jusqu'à ce que le nombre de rangées soit égal à la taille maximale spécifiée. La valeur maximale est 10000.

Si la taille du cache est réglée à 0, la mise en cache est désactivée dans la session.

La taille du cache par défaut est 10.

Exceptions

Exception Error Description
invalid API result cache size ORA-20032

La valeur minimale est 0 et la valeur maximale est 100000. Cette exception s'affiche lorsque la valeur d'entrée est inférieure à 0 ou supérieure à 10000.

Exemple

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);