API REST de DBMS_CLOUD

Cette section décrit les API REST DBMS_CLOUD fournies avec une base de données d'IA autonome sur une infrastructure Exadata dédiée.

Conditions requises

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

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

Sommaire des API REST DBMS_CLOUD

Cette section décrit les API REST DBMS_CLOUD fournies avec Autonomous AI Database.

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 de la base de données autonome d'IA.
Fonction GET_RESPONSE_TEXT Cette fonction retourne la réponse HTTP au format TEXT (VARCHAR2 ou CLOB) dans la base de données d'IA autonome. 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 de mémoire cache des résultats configurée.
Fonction et procédure SEND_REQUEST Cette fonction démarre une demande HTTP, obtient la réponse et met fin à la réponse dans la base de données d'IA autonome. 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 en cours.

Aperçu de l'API REST 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 DBMS_CLOUD vous permettent de faire des demandes HTTP à l'aide de DBMS_CLOUD.SEND_REQUEST et d'obtenir et d'enregistrer des résultats. Ces fonctions fournissent une API générique qui vous permet d'appeler n'importe quelle API REST avec les services en nuage pris en charge suivants :

Constantes d'API REST DBMS_CLOUD

Décrit les constantes 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 documentée dans la documentation sur l'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'

Mémoire cache de résultats d'API REST DBMS_CLOUD

Vous pouvez enregistrer les résultats de l'API REST DBMS_CLOUD lorsque vous réglez le paramètre cache à Vrai avec DBMS_CLOUD.SEND_REQUEST. La vue SESSION_CLOUD_API_RESULTS décrit les colonnes que vous pouvez utiliser lors de l'enregistrement des résultats de l'API REST.

Par défaut, les appels d'API REST DBMS_CLOUD n'enregistrent pas les résultats de votre session. Dans ce cas, vous utilisez la fonction DBMS_CLOUD.SEND_REQUEST pour retourner des 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 passés dans la vue SESSION_CLOUD_API_RESULTS. L'enregistrement et l'interrogation des résultats historiques des demandes d'API REST DBMS_CLOUD peuvent vous aider lorsque vous devez utiliser vos résultats précédents dans vos applications.

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

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Lorsque vous enregistrez les résultats de l'API REST 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 de la mémoire cache de l'API REST DBMS_CLOUD et pour désactiver la mise en mémoire cache.

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

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

Par défaut, cache_scope est '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 session peuvent accéder aux résultats. La valeur par défaut de cache_scope spécifie que chaque utilisateur ne peut voir que 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 de l'appelant. Lorsque vous appelez DBMS_CLOUD.SEND_REQUEST dans une session, il existe trois possibilités qui déterminent si l'utilisateur courant peut voir les résultats dans le cache, en fonction de la valeur cache_scope :

DBMS_CLOUD API REST SESSION_CLOUD_API_RESULTS Voir

Vous pouvez enregistrer les résultats de l'API REST DBMS_CLOUD lorsque vous réglez le paramètre cache à Vrai avec DBMS_CLOUD.SEND_REQUEST. La vue SESSION_CLOUD_API_RESULTS décrit les colonnes que vous pouvez utiliser lors de l'enregistrement des résultats de l'API REST.

La vue SESSION_CLOUD_API_RESULTS est la vue créée si vous mettez en mémoire cache les résultats avec DBMS_CLOUD.SEND_REQUEST. Vous pouvez interroger les résultats historiques appartenant à votre session utilisateur. Lorsque la session se termine, les données dans SESSION_CLOUD_API_RESULTS sont épurées.

Colonne Description
URI URL de demande d'API REST DBMS_CLOUD
TIMESTAMP Horodatage de la réponse de l'API REST DBMS_CLOUD
CLOUD_TYPE Type d'API REST en nuage 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 la demande d'API REST DBMS_CLOUD dans CLOB
RESPONSE_STATUS_CODE Code de statut de réponse de l'API REST DBMS_CLOUD, par exemple 200(OK), 404(Not Found)
RESPONSE_HEADERS En-têtes de réponse de l'API REST DBMS_CLOUD
RESPONSE_BODY_TEXT Corps de réponse de l'API REST DBMS_CLOUD dans CLOB
SCOPE cache_scope défini 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). 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.

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 de mémoire cache des résultats configurée. La taille du cache ne s'applique qu'à la session en cours.

Syntaxe

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Fonction et procédure SEND_REQUEST

Cette fonction et cette procédure démarrent une demande HTTP, obtiennent la réponse et mettent fin à la réponse. Cette fonction fournit un flux de travail pour envoyer 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 à partir des résultats enregistrés avec 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 à l'aide de l'API native en nuage correspondante.
uri URI HTTP pour effectuer la demande.
method

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

Pour plus d'informations, voir Constantes d'API REST 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 et ne transmettent que des 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 IA autonome -> 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 au chemin relatif obtenu pour le lien WorkRequest de votre demande de travail.

wait_for_states

Le statut Attendre les états est 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 attendus : '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. Cela indique d'attendre la fin de la demande sans aucune temporisation.

cache

Si TRUE indique que la demande doit être mise en mémoire cache dans la mémoire cache de l'API de résultats REST.

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

cache_scope Indique si tout le monde peut accéder à cette mémoire cache de résultats de demande. Valeurs valides : "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 n'ont pas un format JSON valide.

Notes d'utilisation

Procédure SET_API_RESULT_CACHE_SIZE

Cette procédure définit la taille maximale du cache pour la session en cours. La taille du cache ne s'applique qu'à la session en cours.

Syntaxe

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Paramètres

Paramètre Description
cache_size

Réglez la taille maximale de la mémoire cache à la valeur spécifiée cache_size. Si la nouvelle taille maximale de la mémoire cache est inférieure à la taille actuelle, les anciens enregistrements sont supprimés jusqu'à ce que le nombre de lignes soit égal à la taille maximale spécifiée. La valeur maximale est 10000.

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

La taille de mémoire 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 10000. 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);

Contenu connexe