API REST DBMS

Prérequis

En tant que développeur, vous pouvez utiliser des procédures DBMS_CLOUD avec des instances Autonomous Database 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 API REST DBMS_CLOUD avec les fournisseurs de services Amazon S3, Azure Blob Storage et Google Cloud Storage.

Oracle Public Cloud ou multicloud
Exadata Cloud@Customer

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

Créez une passerelle NAT dans le réseau cloud virtuel (VCN) où résident vos ressources Autonomous Database en suivant les instructions fournies dans 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) dans lesquelles résident les ressources Autonomous Database 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.
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 correspondante.
3. Dans la table des règles de routage 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 possédant ces caractéristiques.
4. Revenez à 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é correspondante.
6. Dans le menu latéral, sous Resources, cliquez sur Egress Rules.
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 présentant ces caractéristiques.

Les paramètres de proxy HTTP de votre environnement doivent permettre à la base de données d'accéder au fournisseur de services 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.

Remarques :

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 (SR) dans My Oracle Support. Pour plus d'informations, reportez-vous à Création d'une demande d'assistance dans My Oracle Support.

API REST DBMS_CLOUD

Cette section traite des API REST DBMS_CLOUD fournies avec Autonomous 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 Autonomous Database.
Fonction GET_RESPONSE_TEXT	Cette fonction renvoie la réponse HTTP au format TEXT (`VARCHAR2` ou `CLOB`) dans Autonomous Database. En général, la plupart des API REST cloud renvoient 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 renvoie la taille du cache des résultats configuré.
Fonction et procédure SEND_REQUEST	Cette fonction lance une demande HTTP, obtient la réponse et y met fin dans Autonomous Database. Cette fonction fournit un workflow pour l'envoi d'une demande d'API REST cloud avec des arguments, et une charge utile et un code de réponse de renvoi.
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, et d'obtenir et d'enregistrer les résultats. Ces fonctions fournissent une API générique que vous pouvez appeler des API REST avec les services cloud pris en charge suivants :

Oracle Cloud Infrastructure
Reportez-vous à Adresses et référence d'API pour plus d'informations sur les API REST Oracle Cloud Infrastructure.
Azure Cloud ^{Note de bas de page 1}
Reportez-vous à Référence d'API REST Azure pour plus d'informations sur les API REST Azure.

Constantes d'API REST DBMS_CLOUD

Décrit les constantes DBMS_CLOUD permettant d'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 indiqué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 des résultats d'API REST DBMS_CLOUD

Vous pouvez enregistrer les résultats d'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 d'API REST sont enregistrés.

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

Lorsque vous utilisez DBMS_CLOUD.SEND_REQUEST et que vous 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 des résultats récents d'API REST DBMS_CLOUD, utilisez la vue SESSION_CLOUD_API_RESULTS :

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Lorsque vous enregistrez des résultats d'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 quitté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 afin de visualiser et de définir la taille du cache d'API REST DBMS_CLOUD, et de désactiver la mise en mémoire cache.

Paramètre cache_scope Résultats d'API REST DBMS_CLOUD

Lorsque vous enregistrez des résultats d'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 défini sur 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 la 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 appelées avec les droits de l'appelant. Lorsque vous appelez DBMS_CLOUD.SEND_REQUEST dans une session, vous disposez de trois options permettant de déterminer si l'utilisateur en cours peut voir les résultats dans le cache, en fonction de la valeur cache_scope :

Vous pouvez exécuter directement DBMS_CLOUD.SEND_REQUEST en tant qu'instruction de niveau supérieur, et l'appel à DBMS_CLOUD.SEND_REQUEST et les résultats d'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 pouvez écrire une procédure utilisant les droits de l'appelant de wrapper et, en tant qu'utilisateur en cours, votre appel avec DBMS_CLOUD.SEND_REQUEST appelle la procédure et les résultats d'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 pouvez écrire une procédure utilisant les droits du créateur de wrapper et cette procédure 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 des droits du créateur appelle DBMS_CLOUD.SEND_REQUEST et les résultats d'API REST sont enregistrés avec le propriétaire de la procédure du créateur. Dans ce cas, par défaut, lorsque cache_scope est défini sur 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 rendre les résultats disponibles pour les utilisateurs de la session effectuant un appel, il doit définir cache_scope sur PUBLIC dans DBMS_CLOUD.SEND_REQUEST.

Vue SESSION_CLOUD_API_RESULTS d'API REST DBMS_CLOUD

Vous pouvez enregistrer les résultats d'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 d'API REST sont enregistrés.

La vue SESSION_CLOUD_API_RESULTS est la vue créée si vous mettez les résultats en mémoire cache avec DBMS_CLOUD.SEND_REQUEST. Vous pouvez interroger les résultats historiques appartenant à votre session utilisateur. A la fin de la session, les données de SESSION_CLOUD_API_RESULTS sont purgées.

Colonne	Description
`URI`	URL de la demande d'API REST `DBMS_CLOUD`
`TIMESTAMP`	Horodatage de la réponse d'API REST `DBMS_CLOUD`
`CLOUD_TYPE`	Type cloud de l'API REST `DBMS_CLOUD`, par exemple, Oracle Cloud Infrastructure et AZURE_BLOB
`REQUEST_METHOD`	Méthode de la demande d'API REST `DBMS_CLOUD`, comme `GET`, `PUT`, `HEAD`
`REQUEST_HEADERS`	En-têtes de la demande d'API REST `DBMS_CLOUD`
`REQUEST_BODY_TEXT`	Corps de la demande d'API REST `DBMS_CLOUD` au format `CLOB`
`RESPONSE_STATUS_CODE`	Code de statut de la réponse d'API REST `DBMS_CLOUD`, comme `200(OK)`, `404(Not Found)`
`RESPONSE_HEADERS`	En-têtes de la réponse d'API REST `DBMS_CLOUD`
`RESPONSE_BODY_TEXT`	Corps de la réponse d'API REST `DBMS_CLOUD` au format `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é à partir de `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). En général, la plupart des API REST cloud renvoient 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 renvoyé à partir de `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 du cache des résultats configuré. La valeur de la taille du 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 procédure lance une demande HTTP, obtient la réponse et y met fin. Cette fonction fournit un workflow pour l'envoi d'une demande d'API REST cloud avec des arguments et renvoie une charge utile et un code de réponse. Si vous utilisez cette procédure, vous pouvez visualiser 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 informations d'identification pour l'authentification auprès de l'API native du cloud correspondante.
`uri`	URI HTTP permettant d'effectuer la demande.
`method`	Méthode de demande HTTP : `GET`, `PUT`, `POST`, `HEAD`, `DELETE`. Utilisez la constante de package `DBMS_CLOUD` pour indiquer 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 du cloud correspondante au format JSON. Les en-têtes d'authentification sont définis automatiquement, seuls les en-têtes personnalisés sont transmis.
`async_request_url`	URL de demande asynchrone. Pour obtenir l'URL, sélectionnez votre API de demande dans la liste des API (reportez-vous à https://docs.cloud.oracle.com/en-us/iaas/api/). Ensuite, recherchez l'API correspondant à votre demande dans le panneau de gauche. Par exemple, API du service Database → AutonomousDatabase → StopAutonomousDatabase. Cette page affiche l'accueil de l'API (et l'adresse de base). Ensuite, ajoutez le chemin relatif obtenu pour le lien WorkRequest de la demande de travail à la fin de l'adresse de base.
`wait_for_states`	Les états d'attente représentent 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` ou `SUCCEEDED`. Plusieurs états sont autorisés pour `wait_for_states`. La valeur par défaut de `wait_for_states` est l'attente de l'un des états attendus : `ACTIVE`, `CANCELED`, `COMPLETED`, `DELETED`, `FAILED` ou `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`. Elle traduit l'attente de la fin de la demande sans délai d'expiration.
`cache`	Si la valeur est `TRUE`, indique que la demande doit être mise en mémoire cache dans le cache des résultats d'API 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 tous les utilisateurs peuvent accéder à ce cache des 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ées sur la 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 cette forme asynchrone de send_request, la fonction attend le statut de fin indiqué dans wait_for_states avant d'effectuer un renvoi. 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 renvoie pas de résultat immédiatement. La demande sonde async_request_url jusqu'à ce que l'état de renvoi soit l'un des états attendus ou que la valeur timeout soit dépassée (timeout est facultatif). Si aucune valeur timeout n'est indiquée, la demande attend la survenue d'un état défini dans wait_for_states.

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 la taille du 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éfinit la taille maximale du cache sur la valeur `cache_size` indiquée. Si la nouvelle taille maximale du cache est inférieure à la taille du cache en cours, les anciens enregistrements sont supprimés jusqu'à ce que le nombre de lignes soit égal à la taille maximale du cache indiquée. La valeur maximale est `10000`. Si la taille du cache est définie sur `0`, la mise en mémoire cache est désactivée dans la session. Par défaut, la taille du cache est `10`.

cache_size

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

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

Par défaut, la taille du cache 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 est affichée lorsque la valeur d'entrée est inférieure à 0 ou supérieure à 10000.

Exemple

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);