顧客が管理するWalletを使用した外部コールの実行

自律型AIデータベースがHTTP/HTTPSを介してインターネット上のデータにアクセスする必要がある場合は、UTL_HTTPパッケージを使用できます。UTL_HTTPパッケージを使用すると、SQLおよびPL/SQLから直接HTTPコールアウトを作成できます。

HTTPSエンドポイントをコールする場合は、Oracle Walletを構成する必要があります。Autonomous AI Databaseには、データベースが接続するHTTPSエンドポイントの信頼できるルート証明書と中間証明書を含むウォレットが必要です。UTL_HTTPパッケージは、このウォレットを使用してセキュアなSSL/TLS接続を確立します。ウォレットは、orapkiユーティリティを使用して作成および管理できます。

ノート:プレーンHTTP (非HTTPS)リクエストでは、Oracle Walletは必要ありません。

次の各項では、顧客管理ウォレットを構成および使用して、Autonomous AI DatabaseでUTL_HTTPパッケージを使用してアウトバウンドHTTPSコールを行う方法について説明します。

外部コールで顧客管理Walletを使用するための前提条件

開始する前に、次のものがあることを確認してください。

PL/SQLを実行してUTL_HTTPを構成できるアカウントを使用して、Autonomous AI Databaseにアクセスします。
ターゲットHTTPSエンドポイントおよびその完全な証明書チェーン(ルート+中間証明書)へのアクセス。
orapkiを実行してOracle Walletを作成および検証できるワークステーション。orapkiユーティリティを取得するには、Oracle Databaseをインストールする必要があります。詳細は、「Oracle Databaseのインストール」を参照してください。

お客様が管理するWalletの準備

このステップでは、ワークステーション上のウォレットを作成および検証してから、Autonomous AI Databaseにアップロードします。

顧客管理ウォレットの取得または作成

orapkiを使用する例:

-- Create an SSL Wallet and load the Root CERTs using orapki utility
$ORACLE_HOME/bin/orapki wallet create -wallet /u01/web/wallet -pwd ********
$ORACLE_HOME/bin/orapki wallet add -wallet /u01/web/wallet -trusted_cert -cert MyWebServer.cer -pwd ********
-- Store the credentials in the SSL Wallet using mkstore utility
$ORACLE_HOME/bin/mkstore -wrl /u01/web/wallet -createCredential secret-from-the-wallet 'example@oracle.com'
********Enter wallet password: ********

ウォレットの検証

$ORACLE_HOME/bin/orapki wallet display -wallet /u01/web/wallet

インポートされたすべての証明書が表示されます。

ウォレットをアップロードします

顧客管理ウォレットの準備ができたら(必要な自己署名/ルート/中間証明書を含む)、ウォレット・ファイルをOracle Cloud Infrastructure (OCI) Object Storageの場所にアップロードします。

UTL_HTTPでの顧客管理ウォレットの使用

この項では、オブジェクト・ストレージからウォレットをダウンロードし、HTTPSエンドポイントへのネットワーク・アクセスを許可してから、UTL_HTTPパッケージを使用してHTTPSコールを行う方法を示します。

オブジェクト・ストレージ・アクセスの資格証明を作成します:
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
usernameおよびpasswordに指定する値は、使用しているクラウド・オブジェクト・ストレージ・サービスによって異なりますこれにより、顧客管理ウォレットが存在するクラウド・オブジェクト・ストレージへのアクセスに使用する資格証明が作成されます。
ウォレットのディレクトリ・オブジェクトを作成(または再利用)します。

既存のディレクトリを使用するか、ウォレット・ファイルの新しいディレクトリを作成してください。たとえば:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
ディレクトリの作成の詳細は、「Autonomous AI Databaseでのディレクトリの作成」を参照してください。
絶対ディレクトリ・パスを取得します。

UTL_HTTP.SET_WALLETをコールする場合は、絶対ディレクトリ・パスが必要です。
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
オブジェクト・ストレージから次のディレクトリにウォレット・ファイルをダウンロードします。

DBMS_CLOUD.GET_OBJECTを使用して、ウォレット・ファイルをディレクトリにコピーします。たとえば:
```
 BEGIN
 DBMS_CLOUD.GET_OBJECT(
 credential_name => 'DEF_CRED_NAME',
 object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
 directory_name => 'WALLET_DIR');
 END;
 /
```
この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

HTTPSエンドポイントへのアウトバウンド・ネットワーク・アクセス(ACL)を許可します。

データベース・ユーザー/スキーマがネットワーク経由でターゲット・ホストに到達することを許可する必要があります。

  BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
       host => 'api.example.com',
       ace  => xs$ace_type(
       privilege_list => xs$name_list('CONNECT','HTTP','RESOLVE'),
       principal_name => 'ADMIN',
       principal_type => xs_acl.ptype_db
   )
 );
 END;
 /

Exadata Cloud@Customerデプロイメントでは、次に示すようにプロキシも設定する必要があります。

 BEGIN
   UTL_HTTP.SET_PROXY('www-proxy.us.oracle.com:80', 'oracle.com');
 END;
 /

UTL_HTTPを使用してHTTPSコールを実行します。

単純なGETリクエスト:

 DECLARE
 l_http_req UTL_HTTP.req;
 l_http_resp UTL_HTTP.resp;
 l_response VARCHAR2(32767);

 BEGIN
    utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
    l_http_req := UTL_HTTP.BEGIN_REQUEST('https://api.example.com/status');
    l_http_resp := UTL_HTTP.GET_RESPONSE(l_http_req);
    LOOP UTL_HTTP.READ_LINE(l_http_resp, l_response, TRUE);
        DBMS_OUTPUT.PUT_LINE(l_response);
    END LOOP;
    UTL_HTTP.END_RESPONSE(l_http_resp);
 END;
 /

JSONペイロードを使用したPOSTリクエスト:

 DECLARE
   l_req UTL_HTTP.req;
   l_resp UTL_HTTP.resp;
   l_line VARCHAR2(32767);
 BEGIN
   utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
   l_req := UTL_HTTP.BEGIN_REQUEST( url => 'https://api.example.com/data', method => 'POST' );
   UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
   UTL_HTTP.WRITE_TEXT(l_req, '{"key":"value"}');
   l_resp := UTL_HTTP.GET_RESPONSE(l_req);
   LOOP UTL_HTTP.READ_LINE(l_resp, l_line, TRUE);
     DBMS_OUTPUT.PUT_LINE(l_line);
   END LOOP;
   UTL_HTTP.END_RESPONSE(l_resp);
  END;
  /

一般的なエラーのトラブルシューティング:

証明書チェーン・エラー

エラー: ORA-29024: Certificate validation failure

ルート証明書および中間証明書がない可能性があります。
ターゲット・エンドポイントが新しいCAを使用している可能性があります。完全な証明書チェーンを再ダウンロードし、ウォレットを再作成してください。

Walletパス・エラー

ORA-28759: Failure to open file

SET_WALLETのウォレット・パスが正しくありません。
file:接頭辞がありません。
アップロードされたウォレット・ファイルがディレクトリに存在しません。

ハンドシェイクの失敗

ORA-24263 / ORA-29005

TLSプロトコルが一致しません。
証明書が不正または期限切れです。
エンドポイントはTLS > 1.2を強制します

スケジューラの電子メール通知(SMTP)に顧客管理Walletを使用する

この項では、顧客管理ウォレットでTLS (STARTTLS)を介してSMTPサーバーを使用するようにスケジューラの電子メール通知を構成する方法を示します。

開始する前に、顧客管理ウォレット(ローカルに作成して検証し、Object Storageにアップロード)をすでに準備していることを確認してください。詳細は、顧客管理のWalletの準備を参照してください。

スケジューラEメール・サーバーで顧客管理ウォレットを使用するには:

オブジェクト・ストレージ・アクセスの資格証明を作成します:

DBMS_CLOUD.CREATE_CREDENTIALを使用して、クラウド・オブジェクト・ストレージにアクセスするための資格証明を作成できます。
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
usernameおよびpasswordに指定する値は、使用しているクラウド・オブジェクト・ストレージ・サービスによって異なりますこれにより、顧客管理ウォレットが存在するクラウド・オブジェクト・ストレージへのアクセスに使用する資格証明が作成されます。
ウォレットのディレクトリ・オブジェクトを作成(または再利用)します。

既存のディレクトリを使用するか、ウォレット・ファイルの新しいディレクトリを作成してください。たとえば:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
ディレクトリの作成の詳細は、「Autonomous AI Databaseでのディレクトリの作成」を参照してください。
絶対ディレクトリ・パスを取得します:

UTL_HTTP.SET_WALLETをコールする場合は、絶対ディレクトリ・パスが必要です。
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
オブジェクト・ストレージから次のディレクトリにウォレット・ファイルをダウンロードします。

DBMS_CLOUD.GET_OBJECTを使用して、ウォレット・ファイルをディレクトリにコピーします。たとえば:
```
 BEGIN
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'DEF_CRED_NAME',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
     directory_name => 'WALLET_DIR');
 END;
 /
```
この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。
スケジューラ電子メールの構成(SMTP + STARTTLS):

コマンドを実行して、スケジューラ・ジョブ通知用にSMTP電子メールを送信するようにスケジューラを設定します。
```
 EXEC DBMS_CLOUD.CREATE_CREDENTIAL('EMAIL_CRED', '<user_ocid>', '<password>');
 GRANT EXECUTE ON admin.EMAIL_CRED TO sys;
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
       'EMAIL_SERVER',
       'smtp.email.us-ashburn-1.oci.oraclecloud.com:587'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_CREDENTIAL',
         'EMAIL_CRED'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_ENCRYPTION',
         'STARTTLS'
 );
```
コマンドは次のことを行います。
- スケジューラSMTPエンドポイントを設定します(EMAIL_SERVER)
- SMTPログインの詳細をEMAIL_CREDに格納し、Schedulerをそれに指定します。
- STARTTLSを使用したTLS暗号化の有効化
詳細は、SET_SCHEDULER_ATTRIBUTEプロシージャを参照してください。
ウォレット・パスワードの資格証明を作成します。

顧客管理ウォレットのパスワードを格納するための資格証明を作成します。
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
これにより、次のステップで使用する資格証明が作成され、顧客管理ウォレットのパスワードが指定されます。

ウォレットの場所とロック解除方法をスケジューラに伝えます。

スケジューラのウォレット・ディレクトリとウォレット資格証明を設定します。

 BEGIN
   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_DIRECTORY',
     'WALLET_DIR'
   );

   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_CREDENTIAL',
     'ADMIN.WALLET_CRED'
   );
 END;
 /

スケジューラの電子メール構成を確認します。

DBA_SCHEDULER_GLOBAL_ATTRIBUTEビューを問い合せて、前のステップで設定した値を確認します。

 SELECT attribute_name, value
 FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE
 WHERE attribute_name LIKE 'EMAIL_SERVER%' ORDER BY 1, 2;

 ATTRIBUTE_NAME                 VALUE

 ------------------------------ -----------------------------------------------
 EMAIL_SERVER                   smtp.email.us-ashburn-1.oci.oraclecloud.com:587
 EMAIL_SERVER_CREDENTIAL        "ADMIN"."EMAIL_CRED"
 EMAIL_SERVER_ENCRYPTION        STARTTLS
 EMAIL_SERVER_WALLET_CREDENTIAL "ADMIN"."WALLET_CRED"
 EMAIL_SERVER_WALLET_DIRECTORY  "WALLET_DIR"

参照

orapkiの便利なコマンド:

orapki wallet display -wallet <path> orapki wallet add -wallet <path>
-trusted_cert -cert <cert-file> orapki wallet create -wallet <path> -auto_login

ウォレット・ディレクトリ構造の例:

cmw_wallet/
- ewallet.p12
- cwallet.sso