使用客戶管理的公事包進行外部通話

當您的自治式 AI 資料庫需要透過 HTTP/HTTPS 存取網際網路上的資料時，您可以使用 UTL_HTTP 套裝程式。UTL_HTTP 套裝程式可讓您直接從 SQL 和 PL/SQL 進行 HTTP 對外呼叫。

如果您正在呼叫 HTTPS 端點，則必須設定 Oracle Wallet 。自治式 AI 資料庫需要一個公事包，其中包含資料庫所連線之任何 HTTPS 端點的信任根憑證和中介憑證。UTL_HTTP 套裝程式會使用此公事包來建立安全的 SSL/TLS 連線。您可以使用 orapki 公用程式建立及管理公事包。

注意：純 HTTP (非 HTTPS) 要求不需要 Oracle Wallet。

以下各節說明如何設定及使用客戶管理的公事包，以使用自治式 AI 資料庫上的 UTL_HTTP 套裝程式進行輸出 HTTPS 呼叫。

使用客戶管理的公事包與外部通話的先決條件

開始前，請確定您有：

使用可執行 PL/SQL 並設定 UTL_HTTP 的帳戶來存取自治式 AI 資料庫。
存取目標 HTTPS 端點及其完整憑證鏈 (根 + 中繼憑證)。
您可以執行 orapki 來建立及驗證 Oracle Wallet 的工作站。您必須安裝 Oracle Database 才能取得 orapki 公用程式。請參閱安裝 Oracle Database 瞭解詳細資訊。

準備客戶管理的公事包

在此步驟中，您將先在您的工作站上建立並驗證公事包，再將其上傳至自治式 AI 資料庫。

取得或建立客戶管理的公事包

使用 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) 物件儲存中的位置。

使用含有 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 資料庫中建立目錄。

取得絕對目錄路徑：

呼叫 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 - 重新下載完整憑證鏈，然後重新建立公事包。

公事包路徑錯誤

ORA-28759: Failure to open file

SET_WALLET 中的公事包路徑不正確。
遺漏 file: 前置碼。
上傳的公事包檔案不在目錄中。

交握式確認錯誤

ORA-24263 / ORA-29005

TLS 協定不符。
錯誤的或已過期的憑證。
端點強制實行 TLS > 1.2

使用客戶管理的公事包傳送排程器電子郵件通知 (SMTP)

本節顯示如何設定 Scheduler 電子郵件通知，以使用 SMTP 伺服器 (STARTTLS) 搭配客戶管理的公事包。

開始之前，請確定您已準備好由客戶管理的公事包 (在本機建立、驗證公事包並將其上傳至物件儲存)。如需詳細資訊，請參閱準備客戶管理的公事包。

若要在排程器電子郵件伺服器使用客戶管理的公事包：

建立物件儲存存取的證明資料：

您可以使用 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 資料庫中建立目錄。

取得絕對目錄路徑：

呼叫 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'
 );

這些指令會執行下列作業：

設定 Scheduler SMTP 端點 (EMAIL_SERVER)
儲存 EMAIL_CRED 中的 SMTP 登入詳細資料，並將 Scheduler 指向
使用 STARTTLS 啟用 TLS 加密

請參閱 SET_SCHEDULER_ATTRIBUTE Procedure 以瞭解詳細資訊。

建立公事包密碼的證明資料：

建立證明資料以儲存客戶管理公事包的密碼。

 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