API REST DBMS_CLOUD

Cette section traite des API REST DBMS_CLOUD fournies avec Autonomous AI Database on Dedicated Exadata Infrastructure.

Prérequis

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érequis 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.

L'administrateur de parc doit avoir configuré une connectivité sortante à l'aide d'une passerelle NAT, comme décrit ci-dessous :

Créez une passerelle NAT dans le réseau cloud virtuel (VCN) où résident vos ressources de base de données Autonomous AI en suivant les instructions de la section Création d'une passerelle NAT dans la documentation 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 de base de données Autonomous AI afin que ces ressources puissent utiliser la passerelle pour obtenir une clé publique à partir de votre instance Azure AD :
1. Accédez à la page Détails du sous-réseau correspondante.
2. Dans l'onglet Information sur le sous-réseau, cliquez sur le nom de la table de acheminement du sous‑réseau pour afficher la page Détails de la table de acheminement correspondante.
3. Dans la table des règles de acheminement existantes, vérifiez s'il existe déjà une règle avec les caractéristiques suivantes :
  - Destination : 0.0.0.0/0
  - Type de cible : passerelle NAT
  - Cible : 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 possédant ces caractéristiques.
4. Revenez à la page Détails du sous-réseau du sous-réseau.
5. Dans la table Listes de sécurité du sous‑réseau, cliquez sur le nom de la liste des sécurité du sous-réseau pour afficher sa page Détails de la liste.
6. Dans le menu latéral, sous Ressources, cliquez sur Règles sortantes.
7. Dans la table des règles sortantes existantes, vérifiez s'il existe déjà une règle avec les caractéristiques suivantes :
  - Type de destination : CIDR
  - Destination :0.0.0.0/0
  - Protocole IP : TCP
  - Plage de ports source:443
  - Plage de ports de Destination : Tout
  Si une telle règle n'existe pas, cliquez sur Ajouter des règles sortantes et ajoutez une règle possédant ces caractéristiques.

Les paramètres de proxy HTTP de votre environnement doivent autoriser la base de données à accéder au fournisseur de service cloud.

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

Remarque : la configuration réseau, y compris le proxy HTTP, ne peut être modifiée que jusqu'à ce que l'infrastructure Exadata présente l'état Activation requise. Une fois activé, vous ne pouvez plus modifier ces paramètres.

La configuration d'un proxy HTTP pour une infrastructure Exadata déjà provisionnée nécessite une demande de service dans My Oracle Support. Pour plus de détails, reportez-vous à Création d'une demande d'assistance dans My Oracle Support.

Récapitulatif API REST DBMS_CLOUD

Cette section traite des API REST DBMS_CLOUD fournies avec Autonomous AI Database.

API REST	Description
Fonction GET_RESPONSE_HEADERS	Cette fonction renvoie les en-têtes de réponse HTTP en tant que données JSON dans un objet JSON dans la base de données Autonomous AI.
Fonction GET_RESPONSE_TEXT	Cette fonction renvoie la réponse HTTP au format TEXT (`VARCHAR2` ou `CLOB`) dans la base de données Autonomous AI. Habituellement, la plupart des API REST cloud renvoient une réponse JSON au format texte. Cette fonction est utile si vous prévoyez que la réponse HTTP est au format texte.
Fonction GET_API_RESULT_CACHE_SIZE	Cette fonction renvoie la taille de 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 Autonomous AI. Cette fonction fournit un workflow pour l'envoi d'une demande d'API REST cloud avec des arguments et un code de réponse de retour et une charge utile.
Procédure SET_API_RESULT_CACHE_SIZE	Cette procédure définit la taille maximale du cache pour la session en cours.

Présentation de l'API REST DBMS_CLOUD

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

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

Oracle Cloud Infrastructure

Pour plus d'informations sur les API REST Oracle Cloud Infrastructure, reportez-vous à Adresses et référence d'API.
Cloud Azure

Pour plus d'informations sur les API REST Azure, reportez-vous à Référence d'API REST Azure.

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 de l'API REST cloud.

Nom	Type	Value
`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 de l'API REST DBMS_CLOUD

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

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

Lorsque vous utilisez DBMS_CLOUD.SEND_REQUEST et définissez le paramètre cache sur TRUE, les résultats sont enregistrés et vous pouvez visualiser 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 avez besoin d'utiliser les 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 visualiser et définir la taille de cache de l'API REST DBMS_CLOUD, et pour désactiver la mise en 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 en cours de la session peut accéder aux résultats. Si vous définissez cache_scope sur 'PUBLIC', tous les utilisateurs de session peuvent accéder aux résultats. La valeur par défaut de cache_scope indique 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, trois possibilités déterminent si l'utilisateur en cours 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'instruction de niveau supérieur. Les résultats de l'appel vers DBMS_CLOUD.SEND_REQUEST et de l'API REST sont enregistrés avec le même nom utilisateur. Dans ce cas, vous avez accès à tous les résultats avec la valeur par défaut, 'PRIVATE', définie pour cache_scope.
Vous écrivez la procédure avec droits d'un appelant wrapper. En tant qu'utilisateur en cours, votre appel avec DBMS_CLOUD.SEND_REQUEST appelle la procédure et les résultats de l'API REST sont enregistrés avec le même nom utilisateur. Dans ce cas, et vous avez accès à tous les résultats avec la valeur par défaut, 'PRIVATE', définie pour cache_scope.
Vous écrivez la procédure de droits d'un créateur de wrapper et celle-ci appartient à un autre utilisateur. Lorsque vous appelez DBMS_CLOUD.SEND_REQUEST au sein de la procédure, les résultats sont enregistrés avec le nom utilisateur du propriétaire de la procédure.

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

Si le propriétaire de la procédure du créateur veut que les résultats soient disponibles pour tout utilisateur de session appelant, il doit définir cache_scope sur 'PUBLIC' dans DBMS_CLOUD.SEND_REQUEST.

Vue API REST DBMS_CLOUD - SESSION_CLOUD_API_RESULTS

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 qui appartiennent à votre session utilisateur. Lorsque la session se termine, les données dans SESSION_CLOUD_API_RESULTS sont purgé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 de cloud d'API REST `DBMS_CLOUD`, tel qu'Oracle Cloud Infrastructure et AZURE_BLOB
`REQUEST_METHOD`	Méthode de demande d'API REST `DBMS_CLOUD`, telle que `GET`, `PUT` et `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`, tel que `200(OK)` et `404(Not Found)`
`RESPONSE_HEADERS`	En-têtes de réponse d'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 renvoie 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 renvoyé par `DBMS_CLOUD.SEND_REQUEST`.

Exceptions

Exception	Erreur	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 renvoie la réponse HTTP au format TEXT (VARCHAR2 ou CLOB). Habituellement, la plupart des API REST cloud renvoient une réponse JSON au format texte. Cette fonction est utile si vous prévoyez 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 renvoyé par `DBMS_CLOUD.SEND_REQUEST`.

Exceptions

Exception	Erreur	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 renvoie la taille de cache des résultats configurée. La valeur de taille de cache s'applique uniquement à 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 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. Si vous utilisez la procédure, vous pouvez afficher les résultats et les détails de 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 informations d'identification pour l'authentification auprès de l'API native cloud correspondante.
`uri`	URI HTTP pour effectuer la demande.
`method`	Méthode de demande HTTP : `GET`, `PUT`, `POST`, `HEAD`, `DELETE`. Utilisez la constante de package `DBMS_CLOUD` pour spécifier la méthode. Pour plus d'informations, reportez-vous à Constantes d'API REST DBMS_CLOUD.
`headers`	En-têtes de demande HTTP pour l'API native cloud 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 l'API de demande dans la liste des API (reportez-vous à https://docs.cloud.oracle.com/en-us/iaas/api/). Accédez ensuite à l'API de votre demande dans le panneau de gauche. Par exemple, API des services de base de données -> Base de données Autonomous AI -> StopAutonomousDatabase. Cette page affiche le répertoire de base de l'API (et l'adresse de base). Ensuite, ajoutez le chemin relatif obtenu pour le lien WorkRequest de votre demande de travail à l'adresse de base.
`wait_for_states`	Le statut Attendre pour 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` et `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`	Indique le délai d'expiration, en secondes, des 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 la fin de la demande sans délai d'attente.
`cache`	Si `TRUE` indique que la demande doit être mise en cache dans le cache d'API de résultat REST. 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. 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	Erreur	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 au format JSON valide.

Remarques sur l'utilisation

Si vous utilisez Oracle Cloud Infrastructure, vous devez utiliser une valeur d'informations d'identification basée sur une clé de signature pour credential_name. Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.
Les paramètres facultatifs async_request_url, wait_for_states et timeout vous permettent de gérer les demandes à longue durée d'exécution. A l'aide de ce formulaire asynchrone de send_request, la fonction attend le statut de fin indiqué dans wait_for_states avant de renvoyer. 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 indiquer une demande de travail associée, la demande ne revient pas immédiatement. Au lieu de cela, la demande sonde async_request_url jusqu'à ce que l'état de retour soit l'un des états attendus ou que timeout soit dépassé (timeout est facultatif). Si aucune valeur timeout n'est indiquée, la demande attend qu'un état trouvé dans wait_for_states se produise.

Procédure SET_API_RESULT_CACHE_SIZE

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

Syntaxe

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Paramètres

Paramètre Description

Paramètre	Description
`cache_size`	Définissez la taille maximale du cache sur la valeur indiquée `cache_size`. Si la nouvelle taille de cache maximale est inférieure à la taille de cache actuelle, les enregistrements plus anciens sont supprimés jusqu'à ce que le nombre de lignes soit égal à la taille de cache maximale indiquée. La valeur maximale est `10000`. Si la taille du cache est définie sur `0`, la mise en cache est désactivée dans la session. La taille de cache par défaut est `10`.

cache_size

Définissez la taille maximale du cache sur la valeur indiquée cache_size. Si la nouvelle taille de cache maximale est inférieure à la taille de cache actuelle, les enregistrements plus anciens sont supprimés jusqu'à ce que le nombre de lignes soit égal à la taille de cache maximale indiquée. La valeur maximale est 10000.

Si la taille du cache est définie sur 0, la mise en cache est désactivée dans la session.

La taille de cache par défaut est 10.

Exceptions

Exception	Erreur	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);

API REST DBMS_CLOUD

Prérequis

Récapitulatif API REST DBMS_CLOUD

Présentation de l'API REST DBMS_CLOUD

Constantes d'API REST DBMS_CLOUD

Cache de résultats de l'API REST DBMS_CLOUD

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

Vue API REST DBMS_CLOUD - SESSION_CLOUD_API_RESULTS

Fonction GET_RESPONSE_HEADERS

Syntaxe

Paramètres

Exceptions

Fonction GET_RESPONSE_TEXT

Syntaxe

Paramètres

Exceptions

Fonction GET_API_RESULT_CACHE_SIZE

Syntaxe

Fonction et procédure SEND_REQUEST

Syntaxe

Paramètres

Exceptions

Remarques sur l'utilisation

Procédure SET_API_RESULT_CACHE_SIZE

Syntaxe

Paramètres

Exceptions

Exemple

Contenu connexe