使用 mTLS 連接 Python 應用程式

套用至：僅 Exadata Cloud@Customer

您可以使用 mTLS 將 Python 應用程式連線至您的自治式 AI 資料庫執行處理。

以 mTLS 連接 Python 應用程式可提供增強的認證與加密安全性，並使用用戶端憑證 (提供使用者名稱和密碼) 強制安全性。

python-oracledb 驅動程式的預設「精簡模式」會直接連線至 Oracle Database。該驅動程式可選擇性地使用 Oracle Client 程式庫「厚模式」來執行某些額外功能。Oracle Client 程式庫可以來自 Oracle Instant Client、完整的 Oracle Client 或來自 Oracle Database 安裝。

請依照下列步驟，使用 mTLS 將您的 Python 應用程式連線至自治式 AI 資料庫執行處理：

1. 啟動 Python 及 python-oracledb 驅動程式
2. 取得安全證明資料 (Oracle Wallet) 並啟用網路連線
3. 如果您只想以 Thin 模式連線，請執行此步驟：使用 python-oracledb Thin 模式 (mTLS) 執行 Python 應用程式
4. 若要以厚模式連線，請執行此步驟：使用 python-oracledb 厚模式 (mTLS) 執行 Python 應用程式

啟動 Python 及 python-oracledb 驅動程式

若要從 Python 應用程式連線至 Autonomous AI 資料庫，請安裝 Python 和 python-oracledb 驅動程式。

1. 安裝 Python 3 (如果尚未安裝的話)。

   您使用的 Python 版本取決於用戶端的作業系統和硬體。例如 Windows、Linux、macOS 及其他。

   注意：Oracle 建議您隨時更新 Python 和 python-oracledb 驅動程式版本。

2. 從 PyPI 安裝 python-oracledb 驅動程式。

   python-oracledb 驅動程式是 Python 程式設計語言擴充模組，可以讓 Python 程式連線至 Oracle Database。python-oracledb 驅動程式是重新命名的，它是熱門 cx_Oracle 驅動程式的新主要發行版本。

   支援的 python-oracledb 驅動程式版本：python-oracledb 1.0 (或更新版本)

   執行下列指令以升級 python：

    python -m pip install oracledb --upgrade
   

   您應該會看到類似以下的執行結果：

    Collecting oracledb
      Downloading oracledb-1.0.3-cp310-cp310-win_amd64.whl (1.0 MB)
   
         ---------------------------------------- 1.0/1.0 MB 1.8 MB/s eta 0:00:00
    Collecting cryptography>=3.4
      Downloading cryptography-37.0.4-cp36-abi3-win_amd64.whl (2.4 MB)
   
         ---------------------------------------- 2.4/2.4 MB 3.5 MB/s eta 0:00:00
    Collecting cffi>=1.12
      Downloading cffi-1.15.1-cp310-cp310-win_amd64.whl (179 kB)
   
         ---------------------------------------- 179.1/179.1 kB 5.4 MB/s eta 0:00:00
    Collecting pycparser
      Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
   
         ---------------------------------------- 118.7/118.7 kB 7.2 MB/s eta 0:00:00
    Installing collected packages: pycparser, cffi, cryptography, oracledb
    Successfully installed cffi-1.15.1 cryptography-37.0.4 oracledb-1.0.3 pycparser-2.21
   

   安裝 python-oracledb 的注意事項：

   • 如果您位於代理主機後方，請使用 --proxy 選項將代理主機伺服器新增至該指令。舉例而言：

     python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80
     

   • 如果您沒有寫入系統目錄的權限，請包含 --user 選項。舉例而言：

     python -m pip install oracledb --upgrade --user
     

   • 如果您的平台無法使用二進位套件，則執行 pip 將會改為下載來源套件。系統會編譯來源並安裝產生的二進位檔。

   如需其他選項和提示，請參閱 Installing python-oracledb 。

3. 如果您想在 Thick 模式中使用 python-oracledb 驅動程式，請安裝 Oracle Client 軟體。

   依照預設，python-oracledb 會以直接連線至 Oracle Database 的精簡模式執行。精簡模式不需要 Oracle Client 程式庫。但是，當 python-oracledb 以 Thick 模式執行時，會提供一些額外的功能。

   注意：請參閱 Oracle Database Features Supported by python-oracledb ，瞭解 python-oracledb Thin and Thick 模式中支援的功能。自治式 AI 資料庫並未提供此連結中顯示的所有功能。

   當您使用 Oracle Instant 從屬端程式庫或 Oracle Database 從屬端程式庫，且在 Python 程式碼中呼叫 oracledb.init_oracle_client() 時，Python-oracledb 會使用 Thick 模式。

   當您安裝 Oracle Client Software 時，mTLS 和 TLS 連線的最低版本需求有差異，如下所示：

   • 雙向 TLS (mTLS) 連線：

     • 如果您的資料庫位於遠端電腦上，請下載免費的 Oracle Instant Client 'Basic' 或 'Basic Light' 套件，以供您的作業系統架構使用。使用支援的版本：Oracle Instant Client ：18.19 (或更新的版本)、19.2 (或更新的版本) 或 21 (基本版本或更新的版本)。

     • 或者，您可以在系統上使用完整 Oracle Database 從屬端程式庫 (包括完整 Oracle Database 從屬端：Oracle Database 從屬端：18.19 (或更新的版本)、19.2 (或更新的版本) 或 21 (基本版本或更新的版本)。

   • TLS 連線：如果您使用下列從屬端版本，Oracle Call Interface (OCI) 從屬端便支援 TLS 認證：

     • Oracle Instant Client/Oracle Database Client 19.14 (或更新的版本) 和 21.5 (或更新的版本) - 所有平台

     • 或者，您可以在系統上使用完整 Oracle Database 從屬端程式庫，包括完整 Oracle Database 從屬端 19.14 (或更新版本) 和 21.5 (或更新版本)。

取得安全證明資料 (Oracle Wallet) 並啟用網路連線

取得從屬端安全證明資料，以連線至自治式 AI 資料庫執行處理。

1. 從自治式 AI 資料庫執行處理下載公事包檔案，以取得包含存取自治式 AI 資料庫執行處理所需之從屬端安全證明資料和網路組態設定值的壓縮檔。

   取得從屬端安全證明資料 (wallet.zip 檔案)：

   • ADMIN 使用者：在 Oracle Cloud Infrastructure 主控台上，按一下資料庫連線。請參閱下載用戶端憑證 (公事包) 。

   • 其他使用者 (非管理員)：請向管理員取得您自治式 AI 資料庫執行處理的 Oracle Wallet。

     注意：保護 wallet.zip 檔案及其內容，以防止未經授權的資料庫存取。

2. 解壓縮從屬端證明資料檔案 (wallet.zip)。

使用 python-oracledb 精簡模式 (mTLS) 執行 Python 應用程式

python-oracledb 預設會使用精簡模式直接連線至您的自治式 AI 資料庫實例。

在 Thin 模式中，只需要兩個來自公事包壓縮檔的檔案：

• tnsnames.ora：將用於應用程式連線字串的網路服務名稱對應至您的資料庫服務。

• ewallet.pem：以精簡模式啟用 SSL/TLS 連線。

以精簡模式連線：

1. 將 tnsnames.ora 和 ewallet.pem 檔案移至您系統上的位置。

   Linux

   例如，在 Linux：

    /opt/OracleCloud/MYDB
   

   Windows

   例如在 Windows 上：

    C:\opt\OracleCloud\MYDB
   

2. 在您的 Python 應用程式中，設定下列連線參數以連線至自治式 AI 資料庫實例：

   • config_dir：指定包含 tnsnames.ora 的目錄。

   • dsn：用來從 tnsnames.ora 檔案指定想要的網路別名。

   • password：指定資料庫使用者密碼。

   • user：指定資料庫使用者。

   • wallet_location：指定包含 PEM 檔案的目錄 (ewallet.pem)。

   • wallet_password：指定 PEM 檔案的密碼 (ewallet.pem)。您在下載 wallet.zip 檔案時設定此密碼。

   Linux

   例如，在 Linux 上，使用 oracledb.connect 與 db2024_low 網路服務名稱以 ADMIN 使用者身分連線 (服務名稱位於 tnsnames.ora 中)：

    connection=oracledb.connect(
         config_dir="/opt/OracleCloud/MYDB",
         user="admin",
         password=password,
         dsn="db2024_low",
         wallet_location="/opt/OracleCloud/MYDB",
         wallet_password=wallet_pw)
   

   Windows

   例如，在 Windows 上使用 oracledb.connect 與 db2024_low 網路服務名稱以 ADMIN 使用者身分連線 (服務名稱位於 tnsnames.ora 中)：

    connection=oracledb.connect(
         config_dir=r"C:\opt\OracleCloud\MYDB",
         user="admin",
         password=password,
         dsn="db2024_low",
         wallet_location=r"C:\opt\OracleCloud\MYDB",
         wallet_password=wallet_pw)
   

   使用 'raw' 字串 r"..." 表示將反斜線視為目錄分隔符號。

   如本範例所示，wallet_location 與 config_dir 設為相同的目錄 (且目錄包含 tnsnames.ora 與 ewallet.pem)。不需要為這些檔案指定相同的目錄。

如果您位於防火牆後方，即可使用連線描述區中的 HTTPS_PROXY 或設定連線屬性，透過代理主機通道 TLS/SSL 連線。成功的連線取決於特定的代理伺服器組態 。由於可能對效能造成影響，Oracle 不建議在生產環境中使用代理主機。請參閱 Oracle Database 19c Database Net Services Reference 中的 HTTPS_PROXY 或 Oracle Database 26ai Database Net Services Reference ，瞭解詳細資訊。

在 Thin 模式中，您可以新增 https_proxy 和 http_proxy_port 參數來指定代理主機。

例如，在 Linux 上：

connection=oracledb.connect(
     config_dir="/opt/OracleCloud/MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location="/opt/OracleCloud/MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

例如，在 Windows 系統上：

connection=oracledb.connect(
     config_dir=r"C:\opt\OracleCloud\MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location=r"C:\opt\OracleCloud\MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

使用 python-oracledb 粗細模式 (mTLS) 執行 Python 應用程式

依照預設，python-oracledb 會以直接連線至 Oracle Database 的精簡模式執行。當驅動程式以 Thick 模式執行時，可使用額外的 python-oracledb 功能。

注意：安裝 Python 的 Oracle Client 程式庫時，必須使用「粗細」模式。您還必須在 Python 程式碼中呼叫 oracledb.init_oracle_client()。

在「厚」模式中，需有公事包壓縮檔的下列三個檔案：

• tnsnames.ora：包含用於應用程式連線字串的網路服務名稱，並將字串對應至您的資料庫服務。

• sqlnet.ora：指定 SQL*Net 從屬端組態。

• cwallet.sso：包含自動開啟的 SSO 公事包。

若要以厚模式連線，請執行下列動作：

1. 將檔案 tnsnames.ora、sqlnet.ora 和 cwallet.sso 放置在您的系統上。

   使用兩個選項之一將這些檔案放置在您的系統上：

   • 如果您使用 Instant Client，請將檔案移至 Instant Client 目錄下的 network/admin 子目錄階層。例如，依據架構或用戶端系統以及安裝 Instant Client 的位置，這些檔案應該放置在目錄位置，例如：

     /home/myuser/instantclient_19_21/network/admin
     

     或

     /usr/lib/oracle/19.21/client64/lib/network/admin
     

     例如，如果您使用完整的 Oracle Client，請在 Linux 上將檔案移至 $ORACLE_HOME/network/admin。

   • 或者，將檔案移至任何可存取的目錄。

     例如，在 Linux 上，將檔案移至目錄 /opt/OracleCloud/MYDB，然後編輯 sqlnet.ora，將公事包位置目錄變更為包含 cwallet.sso 檔案的目錄。

     例如，在 Linux 上編輯 sqlnet.ora，如下所示：

     WALLET_LOCATION = (SOURCE = (METHOD=file) (METHOD_DATA = (DIRECTORY="/opt/OracleCloud/MYDB")))
     SSL_SERVER_DN_MATCH=yes
     

     當組態檔不在預設位置時，您的應用程式需要使用呼叫 oracledb.init_oracle_client() 中的 config_dir 參數或設定 TNS_ADMIN 環境變數來指示它們的位置。

     注意：這些設定值都不需要，如果您將所有組態檔放在 network/admin 目錄中，則不需要編輯 sqlnet.ora。

2. 在您的 Python 應用程式中，設定下列初始化和連線參數以連線至自治式 AI 資料庫實例：

   • config_dir：在放置配置檔案時指定配置目錄。只有當配置檔案放置在即時用戶端配置目錄 network/admin 以外的目錄中時，才需要此選項。

   • dsn：從 tnsnames.ora 檔案指定所需的網路別名。

   • password：指定資料庫使用者密碼。

   • user：指定資料庫使用者。

   在第一個放置組態檔的情況下，將 dsn 參數設為 tnsnames.ora 所需的網路別名，使用您的資料庫證明資料連線至 Autonomous AI Database 執行處理。

   例如，使用 oracledb.init_oracle_client 以 ADMIN 使用者身分連線，然後使用 db2024_low 網路服務名稱連線 (在 tnsnames.ora 中找到服務名稱的位置)：

    oracledb.init_oracle_client()
       connection=oracledb.connect(
           user="admin",
           password=password,
           dsn="db2024_low")
   

   當組態檔位於即時從屬端組態目錄外的目錄中時，請在呼叫 oracledb.init_oracle_client 時設定 config_dir 參數。

   Linux

   例如，在 Linux 上使用 db2024_low 網路服務名稱以 ADMIN 使用者身分連線：

    oracledb.init_oracle_client(config_dir="/opt/OracleCloud/MYDB")
       connection=oracledb.connect(
          user="admin",
          password=password,
          dsn="db2024_low")
   

   Windows

   例如，在 Windows 上使用 db2024_low 網路服務名稱以 ADMIN 使用者身分連線：

    oracledb.init_oracle_client(config_dir=r"C:\opt\OracleCloud\MYDB")
       connection=oracledb.connect(
          user="admin",
          password=password,
          dsn="db2024_low")
   

   使用 'raw' 字串 r"..." 表示將反斜線視為目錄分隔符號。

如果您位於防火牆後方，即可使用連線描述區中的 HTTPS_PROXY 或設定連線屬性，透過代理主機通道 TLS/SSL 連線。成功的連線取決於特定的代理主機組態。由於可能對效能造成影響，Oracle 不建議在生產環境中使用代理主機。請參閱 Oracle Database 19c Database Net Services Reference 中的 HTTPS_PROXY 或 Oracle Database 26ai Database Net Services Reference ，瞭解詳細資訊。

在「粗體」模式中，您可以編輯 sqlnet.ora 檔案並新增一行來指定代理主機：

SQLNET.USE_HTTPS_PROXY=on

此外，編輯 tnsnames.ora 並新增 HTTPS_PROXY 代理主機名稱和 HTTPS_PROXY_PORT 連接埠至您計畫使用之任何服務名稱的連線描述區位址清單。

舉例而言：

mydb_high=(description=
(address=(https_proxy=myproxy.example.com)
(https_proxy_port=80)
(protocol=tcps)(port=1522)(host=...)

如需「粗細」模式的資訊，請參閱啟用 python-oracledb Thick 模式。

相關內容

關於連線至專用自治式 AI 資料庫