API REST de DBMS

Conditions requises

En tant que développeur, vous pouvez utiliser des procédures DBMS_CLOUD avec des bases de données Autonomous Database 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.

Oracle Public Cloud ou multinuage
Exadata Cloud@Customer

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 Autonomous Database 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é de trafic sortant à chaque sous-réseau (dans le VCN) où résident des ressources Autonomous Database 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 décrit les API REST DBMS_CLOUD fournies avec Autonomous 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.
Fonction GET_RESPONSE_TEXT	Cette fonction retourne la réponse HTTP au format TEXT (`VARCHAR2` ou `CLOB`) dans la base de données autonome. 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.
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 lance une demande HTTP, obtient la réponse et met fin à la réponse dans la base de données autonome. Cette fonction fournit un flux de travail pour l'envoi d'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 :

Oracle Cloud Infrastructure
Voir Informations de référence sur les API et points d'extrémité d'API pour plus d'informations sur les API REST d'Oracle Cloud Infrastructure.
^{Note de bas de page 1} Azure Cloud
Voir Informations de référence sur les API REST Azure pour plus d'informations sur les API REST Azure.

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 sélectionner l'URL de l'API de votre demande dans la liste des API (voir https://docs.cloud.oracle.com/en-us/iaas/api/). Vous trouverez ensuite l'API de votre demande dans le volet de gauche. Par exemple, API des services de base de données → Base de données autonome → StopAutonomousDatabase. Cette page affiche 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`	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

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`.

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