Amazon Redshift 將不再支援從修補程式 198 開始建立新的 Python UDFs。現有 Python UDF 將繼續正常運作至 2026 年 6 月 30 日。如需詳細資訊，請參閱[部落格文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon Redshift Python 連接器
<a name="python-redshift-driver"></a>

透過使用適用於 Python 的 Amazon Redshift 連接器，您可以將工作與[適用於 Python (Boto3) 的 AWS SDK](https://github.com/boto/boto3)，以及 pandas 和數值 Python (NumPy) 整合。如需 pandas 的相關資訊，請參閱 [pandas GitHub 儲存庫](https://github.com/pandas-dev/pandas)。如需 NumPy 的相關資訊，請參閱 [NumPy GitHub 儲存庫](https://github.com/numpy/numpy)。

Amazon Redshift Python 連接器提供了開放原始碼的解決方案。您可以瀏覽原始碼、請求增強功能、回報問題並提供貢獻。

若要使用 Amazon Redshift Python 連線器，請確定您的 Python 是 3.6 版或更新版本。如需詳細資訊，請參閱 [Amazon Redshift Python 驅動程式授權合約](https://github.com/aws/amazon-redshift-python-driver/blob/master/LICENSE)。

Amazon Redshift Python 連接器可提供以下功能：
+ AWS Identity and Access Management (IAM) 身分驗證。如需詳細資訊，請參閱[Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。
+ 使用聯合 API 存取的身分提供者身分驗證。以下企業身分提供者可支援聯合 API 存取：
  + Azure AD。如需詳細資訊，請參閱 AWS 大數據部落格文章[使用 Microsoft Azure AD 單一登入聯合 Amazon Redshift 存取](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-microsoft-azure-ad-single-sign-on/)。
  + Active Directory Federation Services。如需詳細資訊，請參閱 AWS 大數據部落格文章[將 Amazon Redshift 叢集的存取與 Active Directory Federation Services (AD FS) 聯合：第 1 部分](https://aws.amazon.com/blogs/big-data/federate-access-to-your-amazon-redshift-cluster-with-active-directory-federation-services-ad-fs-part-1/)。
  + Okta。如需詳細資訊，請參閱 AWS 大數據部落格文章[以身分提供者 Okta 聯合 Amazon Redshift 存取](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-okta-as-an-identity-provider/)。
  + PingFederate。如需詳細資訊，請參閱 [PingFederate 網站](https://www.pingidentity.com/en/software/pingfederate.html)。
  + JumpCloud。如需詳細資訊，請參閱 [JumpCloud 網站](https://jumpcloud.com/)。
+ Amazon Redshift 資料類型。

Amazon Redshift Python 連接器會實作 Python Database API Specification 2.0。如需詳細資訊，請參閱 Python 網站上的 [PEP 249—Python Database API Specification v2.0](https://www.python.org/dev/peps/pep-0249/)。

**Topics**
+ [安裝 Amazon Redshift Python 連接器](python-driver-install.md)
+ [Amazon Redshift Python 連接器的組態選項](python-configuration-options.md)
+ [匯入 Python 連接器](python-start-import.md)
+ [將 Python 連接器與 NumPy 進行整合](python-connect-integrate-numpy.md)
+ [將 Python 連接器與 pandas 進行整合](python-connect-integrate-pandas.md)
+ [使用身分提供者外掛程式](python-connect-identity-provider-plugins.md)
+ [使用 Amazon Redshift Python 連接器的範例](python-connect-examples.md)
+ [Amazon Redshift Python 連接器的 API 參考](python-api-reference.md)

# 安裝 Amazon Redshift Python 連接器
<a name="python-driver-install"></a>

您可以使用下列任一方法來安裝 Amazon Redshift Python 連線器：
+ Python Package Index (PyPI)
+ Conda
+ 複製 GitHub 儲存庫

## 從 PyPI 安裝 Python 連接器
<a name="python-pip-install-pypi"></a>

若要從 Python Package Index (PyPI) 安裝 Python 連線器，您可以使用 pip。若要進行這項動作，請執行以下命令。

```
>>> pip install redshift_connector
```

您可以在虛擬環境內安裝連接器。若要進行這項動作，請執行以下命令。

```
>>> pip install redshift_connector
```

或者，您也可以選擇安裝 pandas 和 NumPy 與連接器。

```
>>> pip install 'redshift_connector[full]'
```

如需 pip 的相關資訊，請參閱 [pip 網站](https://pip.pypa.io/en/stable/)。

## 從 Conda 安裝 Python 連接器
<a name="python-pip-install-from-conda"></a>

您可以從 Anaconda.org 安裝 Python 連接器。

```
>>>conda install -c conda-forge redshift_connector
```

## 從 複製 GitHub 儲存庫來安裝 Python 連接器 AWS
<a name="python-pip-install-from-source"></a>

若要從來源安裝 Python 連接器，請從 AWS複製 GitHub 儲存庫。在安裝 Python 和 virtualenv 後，請透過執行以下命令來設定環境並安裝所需的相依性。

```
$ git clone https://github.com/aws/amazon-redshift-python-driver.git
$ cd amazon-redshift-python-driver
$ virtualenv venv
$ . venv/bin/activate
$ python -m pip install -r requirements.txt
$ python -m pip install -e .
$ python -m pip install redshift_connector
```

# Amazon Redshift Python 連接器的組態選項
<a name="python-configuration-options"></a>

接下來，您可以找到可為 Amazon Redshift Python 連接器指定之選項的描述。除非另有指明，否則以下選項適用於最新推出的連接器版本。

## access\$1key\$1id
<a name="python-access-key-id-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的存取金鑰。

此為選用參數。

## allow\$1db\$1user\$1override
<a name="python-allow-db-user-override-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

True  
指定連接器會使用安全性聲明標記語言 (SAML) 聲明中的 `DbUser` 值。

False  
指定使用 `DbUser` 連線參數中的值。

此為選用參數。

## app\$1name
<a name="python-app-name-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

用於身分驗證之身分提供者 (IdP) 應用程式的名稱。

此為選用參數。

## application\$1name
<a name="python-application_name-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

要傳遞至 Amazon Redshift 以進行稽核的用戶端應用程式名稱。您提供的應用程式名稱會出現在 [SYS\$1CONNECTION\$1LOG](https://docs.aws.amazon.com/redshift/latest/dg/SYS_CONNECTION_LOG.html) 資料表的 'application\$1name' 欄中。此名稱有助於在偵錯問題時，追蹤連線來源並進行故障診斷。

此為選用參數。

## auth\$1profile
<a name="python-auth-profile-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

具有 JSON 形式連線屬性之 Amazon Redshift 身分驗證設定檔的名稱。如需有關命名連線參數的詳細資訊，請參閱 `RedshiftProperty` 類別。`RedshiftProperty` 類別會儲存最終使用者提供的連線參數，以及 (適用的話) 在 IAM 身分驗證程序 (例如臨時 IAM 憑證) 進行期間產生的連線參數。如需詳細資訊，請參閱 [RedshiftProperty 類別](https://github.com/aws/amazon-redshift-python-driver/blob/master/redshift_connector/redshift_property.py#L9)。

此為選用參數。

## auto\$1create
<a name="python-auto-create-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

此值會指出是否要在使用者不存在時建立使用者。

此為選用參數。

## client\$1id
<a name="python-client-id-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

來自 Azure IdP 的用戶端 ID。

此為選用參數。

## client\$1secret
<a name="python-client-secret-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

來自 Azure IdP 的用戶端祕密。

此為選用參數。

## cluster\$1identifier
<a name="python-cluster-identifier-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Amazon Redshift 叢集的叢集識別碼。

此為選用參數。

## credentials\$1provider
<a name="python-credential-provider-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

用於以 Amazon Redshift 進行驗證的 IdP。有效值如下：
+ `AdfsCredentialsProvider`
+ `AzureCredentialsProvider`
+ `BrowserAzureCredentialsProvider`
+ `BrowserAzureOAuth2CredentialsProvider`
+ `BrowserIdcAuthPlugin` - 使用 AWS IAM Identity Center 的授權外掛程式。
+ `BrowserSamlCredentialsProvider`
+ `IdpTokenAuthPlugin` – 從任何 AWS 連結至 IAM Identity Center AWS 的 Web 身分提供者接受 IAM Identity Center 字符或 OpenID Connect (OIDC) JSON 型身分字符 (JWT) 的授權外掛程式。
+ `PingCredentialsProvider`
+ `OktaCredentialsProvider`

此為選用參數。

## 資料庫
<a name="python-database-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

要連線到之資料庫的名稱。

此為必要參數。

## database\$1metadata\$1current\$1db\$1only
<a name="python-database-metadata-current-db-only-option"></a>
+ **預設值** — True
+ **資料類型** — 布林值

此值會指出應用程式是否支援多資料庫資料共用型錄。預設值 True 會指出應用程式不會為了回溯相容性而支援多資料庫資料共用型錄。

此為選用參數。

## db\$1groups
<a name="python-db-groups-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

DbUser 所指出的使用者針對目前的工作階段所加入之現有資料庫群組名稱的逗號分隔清單。

此為選用參數。

## db\$1user
<a name="python-db-user-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

要與 Amazon Redshift 搭配使用的使用者 ID。

此為選用參數。

## endpoint\$1url
<a name="python-endpoint-url-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Amazon Redshift 端點的 URL。此選項僅供 AWS 內部使用。

此為選用參數。

## group\$1federation
<a name="python-group-federation-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

此選項會指定是否使用 Amazon Redshift IDP 群組。

此為選用參數。

**true**  
使用 Amazon Redshift 身分提供者 (IdP) 群組。

**false**  
針對使用者聯合使用 STS API 和 GetClusterCredentials，並指定連線的 **db\$1groups**。

## 託管
<a name="python-host-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Amazon Redshift 叢集的主機名稱。

此為選用參數。

## iam
<a name="python-iam-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

會啟用 IAM 身分驗證。

此為必要參數。

## iam\$1disable\$1cache
<a name="python-iam-disable-cache-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

此選項會指定是否快取 IAM 憑證。預設會快取 IAM 憑證。當對於 API 閘道的請求遭到限流時，這可以提高效能。

此為選用參數。

## idc\$1client\$1display\$1name
<a name="python-idc_client_display_name-option"></a>
+ **預設值** - Amazon Redshift Python 連接器
+ **資料類型** — 字串

使用 BrowserIdcAuthPlugin 的用戶端要使用的顯示名稱。

此為選用參數。

## idc\$1region
<a name="python-idc_region"></a>
+ **預設值** — 無
+ **資料類型** — 字串

IAM Identity Center AWS 執行個體所在的 AWS 區域。

只有在 credentials\$1provider 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。

## idp\$1partition
<a name="python-idp_partition-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

指定設定身分提供者 (IdP) 的雲端分割區。這會決定驅動程式連線到哪個 IdP 身分驗證端點。

如果此參數保留空白，驅動程式會預設為商業分割區。可能值為：
+  `us-gov`：如果您的 IdP 是在 Azure Government 中設定，請使用此值。例如，Azure AD Government 會使用端點 `login.microsoftonline.us`。
+  `cn`：如果您的 IdP 是在中國雲端分割區中設定，請使用此值。例如，Azure AD 中國使用端點 `login.chinacloudapi.cn`。

此為選用參數。

## idpPort
<a name="python-idp-port-option"></a>
+ **預設值** — 7890
+ **資料類型** — 整數

IdP 會將 SAML 聲明傳送到的接聽連接埠。

此為必要參數。

## idp\$1response\$1timeout
<a name="python-idp-response-timeout-option"></a>
+ **預設值** — 120
+ **資料類型** — 整數

從 IdP 擷取 SAML 聲明的逾時。

此為必要參數。

## idp\$1tenant
<a name="python-idp-tenant-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

IdP 租用戶。

此為選用參數。

## issuer\$1url
<a name="python-issuer_url"></a>
+ **預設值** — 無
+ **資料類型** — 字串

 指向 AWS IAM Identity Center 伺服器的執行個體端點。

只有在 credentials\$1provider 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。

## listen\$1port
<a name="python-listen-port-option"></a>
+ **預設值** — 7890
+ **資料類型** — 整數

透過瀏覽器外掛程式使用 SAML、Azure AD 或 IAM Identity Center AWS 服務時，驅動程式用來從身分提供者或授權碼接收 SAML 回應的連接埠。

此為選用參數。

## login\$1url
<a name="python-login-url-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

IdP 的單一登入 Url。

此為選用參數。

## max\$1prepared\$1statements
<a name="python-max-prepared-statements-option"></a>
+ **預設值** — 1000
+ **資料類型** — 整數

每個連線將快取的預備陳述式數量上限。將此參數設為 0 會停用快取機制。針對此參數輸入負數會將其設定為預設值。

此為選用參數。

## numeric\$1to\$1float
<a name="python-numeric-to-float-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

此選項指定連接器是否會將數值資料類型值從 decimal.Decimal 轉換為浮點數。依預設，連接器會接收 decimal.Decimal 形式的數值資料類型值，且不會對值進行轉換。

對於需要精確度的使用案例，不建議您啟用 numeric\$1to\$1float，因為得到的結果可能會經過四捨五入。

如需 decimal.Decimal 以及其與浮點數之間權衡的相關資訊，請參閱 Python 網站上的[小數 — 固定小數點和浮點數](https://docs.python.org/3/library/decimal.html)。

此為選用參數。

## partner\$1sp\$1id
<a name="python-partner-sp-id-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

針對以 Ping 進行的身分驗證所使用的合作夥伴 SP ID。

此為選用參數。

## password
<a name="python-password-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

用於身分驗證的密碼。

此為選用參數。

## port
<a name="python-port-option"></a>
+ **預設值** — 5439
+ **資料類型** — 整數

Amazon Redshift 叢集的連接埠號碼。

此為必要參數。

## preferred\$1role
<a name="python-preferred-role-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

目前連線偏好的 IAM 角色。

此為選用參數。

## principal\$1arn
<a name="python-principal-arn-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

要為其產生政策之使用者或 IAM 角色的 Amazon Resource Name (ARN)。建議您將政策連接至角色，然後將角色指派給您的使用者以提供存取權。

此為選用參數。

## profile
<a name="python-profile-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

登入 AWS AWS 資料檔案中包含登入資料的設定檔名稱。

此為選用參數。

## provider\$1name
<a name="python-provider_name-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Redshift 原生身分驗證提供者的名稱。

此為選用參數。

## region
<a name="python-region-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

 AWS 區域 叢集所在的 。

此為選用參數。

## role\$1arn
<a name="python-role-arn-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

呼叫者所擔任角色的 Amazon Resource Name (ARN)。`JwtCredentialsProvider` 所指出的提供者會使用此參數。

若為 `JwtCredentialsProvider` 提供者，此為必要參數。否則，此為選擇性參數。

## role\$1session\$1name
<a name="python-role-session-name-option"></a>
+ **預設值** — jwt\$1redshift\$1session
+ **資料類型** — 字串

擔任角色工作階段的識別碼。一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。應用程式使用的臨時安全憑證會與該使用者相關聯。`JwtCredentialsProvider` 所指出的提供者會使用此參數。

此為選用參數。

## scope
<a name="python-scope-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

使用者可以同意的範圍清單 (以空格分隔)。指定這個參數可讓您的應用程式針對您想要呼叫的 API 取得同意。當您為 credentials\$1provider 選項指定 BrowserAzureOAuth2CredentialsProvider 時，便可以指定此參數。

BrowserAzureOAuth2CredentialsProvider 外掛程式需要此參數。

## secret\$1access\$1key\$1id
<a name="python-secret-access-key-id-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的私密存取金鑰。

此為選用參數。

## session\$1token
<a name="python-session-token-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的存取金鑰。如果使用臨時 AWS 登入資料，則需要此參數。

此為選用參數。

## serverless\$1acct\$1id
<a name="python-serverless-acct-id-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Amazon Redshift Serverless 帳戶 ID。

此為選用參數。

## serverless\$1work\$1group
<a name="python-serverless-work-group-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

Amazon Redshift Serverless 工作群組名稱。

此為選用參數。

## ssl
<a name="python-ssl-option"></a>
+ **預設值** — True
+ **資料類型** — 布林值

會啟用 Secure Sockets Layer (SSL)。

此為必要參數。

## ssl\$1insecure
<a name="python-ssl-insecure-option"></a>
+ **預設值** — False
+ **資料類型** — 布林值

此值會指定是否要停用驗證 IdP 主機的伺服器 SSL 憑證。將此參數設定為 True 會停用驗證 IdP 主機的伺服器 SSL 憑證。建議您在生產環境中保留預設值 False。

此為選用參數。

## sslmode
<a name="python-sslmode-option"></a>
+ **預設值** — verify-ca
+ **資料類型** — 字串

連線至 Amazon Redshift 的安全。您可以指定下列任一項：
+ verify-ca
+ verify-full

此為必要參數。

## tcp\$1keepalive
<a name="python-tcp_keepalive-option"></a>
+ **預設值** — True
+ **資料類型** — 布林值

是否使用 TCP 保持連線來防止連線逾時。您可以指定下列值：
+ True：驅動器將使用 TCP 保持連線來防止連線逾時。
+ False：驅動器不會使用 TCP 保持連線。

此為選用參數。

## tcp\$1keepalive\$1count
<a name="python-tcp_keepalive_count-option"></a>
+ **預設值** — 無
+ **資料類型** — 整數

在判斷連線為非作用中之前，要傳送的未確認探查數目。例如，將值設定為 3，表示驅動器會先傳送 3 個未回應的保持連線封包，才確定連線非作用中。

如果未指定此參數，Amazon Redshift 會使用系統的預設值。

此為選用參數。

## tcp\$1keepalive\$1interval
<a name="python-tcp_keepalive_interval-option"></a>
+ **預設值** — 無
+ **資料類型** — 整數

後續保持連線探查之間的間隔 (以秒為單位)，如果驅動器未在此間隔之前收到探查的確認。如果您指定此參數，其必須是正整數。

如果未指定此參數，Amazon Redshift 會使用系統的預設值。

此為選用參數。

## tcp\$1keepalive\$1idle
<a name="python-tcp_keepalive_idle-option"></a>
+ **預設值** — 無
+ **資料類型** — 整數

無活動的持續時間 (以秒為單位)，經過這段時間後，驅動器會傳送第一個保持連線探查。例如，將值設定為 120，表示驅動器會等待 2 分鐘無活動的時間，才傳送第一個保持連線封包。如果您指定此參數，其必須是正整數。

如果未指定此參數，Amazon Redshift 會使用系統的預設值。

此為選用參數。

## timeout
<a name="python-timeout-option"></a>
+ **預設值** — 無
+ **資料類型** — 整數

對伺服器的連線在逾時前要經過的秒數。

此為選用參數。

## token
<a name="python-token-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

IAM Identity Center AWS 提供存取字符或由與 IAM Identity Center 連結的 Web 身分提供者提供的 OpenID Connect (OIDC) JSON Web Token AWS (JWT)。您的應用程式必須透過使用 IAM Identity Center AWS 或與 IAM Identity Center 連結的身分提供者來驗證應用程式的使用者來產生此字符 AWS 。

此參數適用於 `IdpTokenAuthPlugin`。

## token\$1type
<a name="python-token_type-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

`IdpTokenAuthPlugin` 中使用的權仗類型。

您可以指定下列值：

**ACCESS\$1TOKEN**  
如果您使用 AWS IAM Identity Center 提供的存取權杖，請輸入此選項。

**EXT\$1JWT**  
如果您使用與 AWS IAM Identity Center 整合的 Web 型身分提供者所提供的 OpenID Connect (OIDC) JSON Web Token (JWT)，請輸入此項。

此參數適用於 `IdpTokenAuthPlugin`。

## user
<a name="python-user-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

用於身分驗證的使用者名稱。

此為選用參數。

## web\$1identity\$1token
<a name="python-web-identity-token-option"></a>
+ **預設值** — 無
+ **資料類型** — 字串

由身分提供者提供的 OAuth 2.0 存取權杖或 OpenID Connect ID 權杖。請確保您的應用程式會透過以 Web 身分提供者對應用程式的使用者進行驗證來取得此權杖。`JwtCredentialsProvider` 所指出的提供者會使用此參數。

若為 `JwtCredentialsProvider` 提供者，此為必要參數。否則，此為選擇性參數。

# 匯入 Python 連接器
<a name="python-start-import"></a>

若要匯入 Python 連接器，請執行以下命令。

```
>>> import redshift_connector
```

若要使用 AWS 登入資料連線至 Amazon Redshift 叢集，請執行下列命令。

```
conn = redshift_connector.connect(
    host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com',
    port=5439,
    database='dev',
    user='awsuser',
    password='my_password'
 )
```

# 將 Python 連接器與 NumPy 進行整合
<a name="python-connect-integrate-numpy"></a>

以下是將 Python 連接器與 NumPy 進行整合的範例。

```
>>>  import numpy
#Connect to the cluster
>>> import redshift_connector
>>> conn = redshift_connector.connect(
     host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com',
     port=5439,
     database='dev',
     user='awsuser',
     password='my_password'
  )
  
# Create a Cursor object
>>> cursor = conn.cursor()

# Query and receive result set            
cursor.execute("select * from book")

result: numpy.ndarray = cursor.fetch_numpy_array()
print(result)
```

結果如下。

```
[['One Hundred Years of Solitude' 'Gabriel García Márquez']
['A Brief History of Time' 'Stephen Hawking']]
```

# 將 Python 連接器與 pandas 進行整合
<a name="python-connect-integrate-pandas"></a>

以下是將 Python 連接器與 pandas 進行整合的範例。

```
>>> import pandas

#Connect to the cluster
>>> import redshift_connector
>>> conn = redshift_connector.connect(
     host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com',
     port=5439,
     database='dev',
     user='awsuser',
     password='my_password'
  )
  
# Create a Cursor object
>>> cursor = conn.cursor()

# Query and receive result set
cursor.execute("select * from book")
result: pandas.DataFrame = cursor.fetch_dataframe()
print(result)
```

# 使用身分提供者外掛程式
<a name="python-connect-identity-provider-plugins"></a>

如需如何使用身分提供者外掛程式的一般資訊，請參閱[提供 IAM 登入資料的選項](options-for-providing-iam-credentials.md)。如需如何管理 IAM 身分的相關資訊 (包括 IAM 角色的最佳實務)，請參閱 [Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。

## 使用 ADFS 身分提供者外掛程式進行身分驗證
<a name="python-connect-identity-provider-active-dir"></a>

以下是使用 Active Directory Federation Service (ADFS) 身分提供者外掛程式來針對連線至 Amazon Redshift 資料庫的使用者進行驗證的範例。

```
>>> con = redshift_connector.connect(
    iam=True,
    database='dev',
    host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
    cluster_identifier='my-testing-cluster',
    credentials_provider='AdfsCredentialsProvider',
    user='brooke@myadfshostname.com',
    password='Hunter2',
    idp_host='myadfshostname.com'
)
```

## 使用 Azure 身分提供者外掛程式進行身分驗證
<a name="python-connect-identity-provider-azure"></a>

以下是使用 Azure 身分提供者外掛程式進行身分驗證的範例。您可以為 Azure 企業應用程式建立 `client_id` 和 `client_secret` 的值，如下所示。

```
>>>  con = redshift_connector.connect(
    iam=True,
    database='dev',
    host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
    cluster_identifier='my-testing-cluster',
    credentials_provider='AzureCredentialsProvider',
    user='brooke@myazure.org',
    password='Hunter2',
    idp_tenant='my_idp_tenant',
    client_id='my_client_id',
    client_secret='my_client_secret',
    preferred_role='arn:aws:iam:123:role/DataScientist'
)
```

## 使用 AWS IAM Identity Center 身分提供者外掛程式進行身分驗證
<a name="python-connect-identity-provider-aws-idc"></a>

 以下是使用 IAM Identity Center AWS 身分提供者外掛程式進行身分驗證的範例。

```
with redshift_connector.connect(
credentials_provider='BrowserIdcAuthPlugin',
host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
database='dev',
idc_region='us-east-1',
issuer_url='https://identitycenter.amazonaws.com/ssoins-790723ebe09c86f9',
idp_response_timeout=60,
listen_port=8100,
idc_client_display_name='Test Display Name',
# port value of 5439 is specified by default
)
```

## 使用 Azure Browser 身分提供者外掛程式進行身分驗證
<a name="python-connect-identity-provider-azure-browser"></a>

以下是使用 Azure Browser 身分提供者外掛程式來針對連線至 Amazon Redshift 資料庫的使用者進行驗證的範例。

由使用者提供登入憑據的瀏覽器會進行多重要素驗證。

```
>>>con = redshift_connector.connect(
    iam=True,
    database='dev',
    host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
    cluster_identifier='my-testing-cluster',
    credentials_provider='BrowserAzureCredentialsProvider',
    idp_tenant='my_idp_tenant',
    client_id='my_client_id',
)
```

## 使用 Okta 身分提供者外掛程式進行身分驗證
<a name="python-connect-identity-provider-okta"></a>

以下是使用 Okta 身分提供者外掛程式進行身分驗證的範例。您可以透過 Okta 應用程式取得 `idp_host`、`app_id` 和 `app_name` 的值。

```
>>> con = redshift_connector.connect(
    iam=True,
    database='dev',
    host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
    cluster_identifier='my-testing-cluster',
    credentials_provider='OktaCredentialsProvider',
    user='brooke@myazure.org',
    password='hunter2',
    idp_host='my_idp_host',
    app_id='my_first_appetizer',
    app_name='dinner_party'
)
```

## 搭配使用 JumpCloud 與一般 SAML 瀏覽器身分提供者外掛程式來進行身分驗證
<a name="python-connect-identity-provider-jumpcloud"></a>

以下是搭配使用 JumpCloud 與一般 SAML 瀏覽器身分提供者外掛程式來進行身分驗證的範例。

密碼是必要參數。但是，您不必輸入此參數，因為瀏覽器會進行多重要素驗證。

```
>>> con = redshift_connector.connect(
    iam=True,
    database='dev',
    host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com',
    cluster_identifier='my-testing-cluster',
    credentials_provider='BrowserSamlCredentialsProvider',
    user='brooke@myjumpcloud.org',
    password='',
    login_url='https://sso.jumpcloud.com/saml2/plustwo_melody'
)
```

# 使用 Amazon Redshift Python 連接器的範例
<a name="python-connect-examples"></a>

以下是如何使用 Amazon Redshift Python 連接器的範例。若要執行這些範例，您必須先安裝 Python 連接器。如需安裝 Amazon Redshift Python 連接器的相關資訊，請參閱[安裝 Amazon Redshift Python 連接器](python-driver-install.md)。如需可與 Python 連接器搭配使用之組態選項的相關資訊，請參閱 [Amazon Redshift Python 連接器的組態選項](python-configuration-options.md)。

**Topics**
+ [使用 AWS 登入資料連線至和查詢 Amazon Redshift 叢集](#python-connect-cluster)
+ [啟用自動遞交](#python-connect-enable-autocommit)
+ [設定游標 paramstyle](#python-connect-config-paramstyle)
+ [使用 COPY 從 Amazon S3 儲存貯體複寫資料，然後使用 UNLOAD 將資料寫入至 Amazon S3 儲存貯體](#python-connect-copy-unload-s3)

## 使用 AWS 登入資料連線至和查詢 Amazon Redshift 叢集
<a name="python-connect-cluster"></a>

下列範例會引導您使用 AWS 登入資料連線至 Amazon Redshift 叢集，然後查詢資料表並擷取查詢結果。

```
#Connect to the cluster
>>> import redshift_connector
>>> conn = redshift_connector.connect(
     host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com',
     database='dev',
     port=5439,
     user='awsuser',
     password='my_password'
  )
  
# Create a Cursor object
>>> cursor = conn.cursor()

# Query a table using the Cursor
>>> cursor.execute("select * from book")
                
#Retrieve the query result set
>>> result: tuple = cursor.fetchall()
>>> print(result)
 >> (['One Hundred Years of Solitude', 'Gabriel García Márquez'], ['A Brief History of Time', 'Stephen Hawking'])
```

## 啟用自動遞交
<a name="python-connect-enable-autocommit"></a>

自動遞交屬性會預設為關閉，以遵循 Python Database API Specification。執行復原命令後，您可以使用以下命令開啟連線的 autocommit 屬性，以確保沒有進行中的交易。

```
#Connect to the cluster
>>> import redshift_connector
>>> conn = redshift_connector.connect(...)

# Run a rollback command
>>>  conn.rollback()

# Turn on autocommit
>>>  conn.autocommit = True
>>>  conn.run("VACUUM")

# Turn off autocommit
>>>  conn.autocommit = False
```

## 設定游標 paramstyle
<a name="python-connect-config-paramstyle"></a>

游標的 paramstyle 可透過 cursor.paramstyle 進行修改。所使用的預設 paramstyle 是 `format`。此參數的有效值為 `qmark`、`numeric`、`named`、`format` 和 `pyformat`。

以下是使用各種 paramstyle 將參數傳遞至範例 SQL 陳述式的範例。

```
# qmark
redshift_connector.paramstyle = 'qmark'
sql = 'insert into foo(bar, jar) VALUES(?, ?)'
cursor.execute(sql, (1, "hello world"))

# numeric
redshift_connector.paramstyle = 'numeric'
sql = 'insert into foo(bar, jar) VALUES(:1, :2)'
cursor.execute(sql, (1, "hello world"))

# named
redshift_connector.paramstyle = 'named'
sql = 'insert into foo(bar, jar) VALUES(:p1, :p2)'
cursor.execute(sql, {"p1":1, "p2":"hello world"})

# format
redshift_connector.paramstyle = 'format'
sql = 'insert into foo(bar, jar) VALUES(%s, %s)'
cursor.execute(sql, (1, "hello world"))

# pyformat
redshift_connector.paramstyle = 'pyformat'
sql = 'insert into foo(bar, jar) VALUES(%(bar)s, %(jar)s)'
cursor.execute(sql, {"bar": 1, "jar": "hello world"})
```

## 使用 COPY 從 Amazon S3 儲存貯體複寫資料，然後使用 UNLOAD 將資料寫入至 Amazon S3 儲存貯體
<a name="python-connect-copy-unload-s3"></a>

下列範例顯示如何將資料從 Amazon S3 儲存貯體複製到資料表，然後從該資料表卸載回儲存貯體。

名為 `category_csv.txt` 且包含下列資料的文字檔案會上傳至 Amazon S3 儲存貯體：。

```
12,Shows,Musicals,Musical theatre
13,Shows,Plays,"All ""non-musical"" theatre"
14,Shows,Opera,"All opera, light, and ""rock"" opera"
15,Concerts,Classical,"All symphony, concerto, and choir concerts"
```

以下是 Python 程式碼範例，其會先連線至 Amazon Redshift 資料庫。然後，會建立名為 `category` 的資料表，並將 S3 儲存貯體中的 CSV 資料複製到資料表中。

```
#Connect to the cluster and create a Cursor
>>> import redshift_connector
>>> with redshift_connector.connect(...) as conn:
>>> with conn.cursor() as cursor:

#Create an empty table
>>>     cursor.execute("create table category (catid int, cargroup varchar, catname varchar, catdesc varchar)")

#Use COPY to copy the contents of the S3 bucket into the empty table 
>>>     cursor.execute("copy category from 's3://testing/category_csv.txt' iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;")

#Retrieve the contents of the table
>>>     cursor.execute("select * from category")
>>>     print(cursor.fetchall())

#Use UNLOAD to copy the contents of the table into the S3 bucket
>>>     cursor.execute("unload ('select * from category') to 's3://testing/unloaded_category_csv.txt'  iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;")

#Retrieve the contents of the bucket
>>>     print(cursor.fetchall())
 >> ([12, 'Shows', 'Musicals', 'Musical theatre'], [13, 'Shows', 'Plays', 'All "non-musical" theatre'], [14, 'Shows', 'Opera', 'All opera, light, and "rock" opera'], [15, 'Concerts', 'Classical', 'All symphony, concerto, and choir concerts'])
```

如果您未將 `autocommit` 設定為 true，請在執行 `execute()` 陳述式後使用 `conn.commit()` 遞交。

資料會卸載到 S3 儲存貯體中的 `unloaded_category_csv.text0000_part00` 檔案中，其內容如下：

```
12,Shows,Musicals,Musical theatre
13,Shows,Plays,"All ""non-musical"" theatre"
14,Shows,Opera,"All opera, light, and ""rock"" opera"
15,Concerts,Classical,"All symphony, concerto, and choir concerts"
```

# Amazon Redshift Python 連接器的 API 參考
<a name="python-api-reference"></a>

接下來，您可以找到 Amazon Redshift Python 連線器 API 操作的描述。

## redshift\$1connector
<a name="python-api-redshift_connector"></a>

接下來，您可以找到 `redshift_connector` API 操作的描述。

`connect(user, database, password[, port, …])`  
建立對 Amazon Redshift 叢集的連線。此函數會驗證使用者輸入、選擇性地使用身分提供者外掛程式進行驗證，然後建構連線物件。

`apilevel`  
支援 DBAPI 層級，目前為「2.0」。

`paramstyle``str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str`  
要全域使用的資料庫 API 參數樣式。

## 連線
<a name="python-api-connection"></a>

接下來，您可以找到 Amazon Redshift Python 連接器的連線 API 操作描述。

`__init__(user, password, database[, host, …])`  
將原始連線物件初始化。

`cursor`  
建立繫結至此連線的游標物件。

`commit`  
遞交目前的資料庫交易。

`rollback`  
復原目前的資料庫交易。

`close`  
關閉資料庫連線。

`execute(cursor, operation, vals)`  
執行指定的 SQL 命令。根據 `redshift_connector.paramstyle` 的值，您可以提供序列或映射形式的參數。

`run(sql[, stream])`  
執行指定的 SQL 命令。您可以選擇性提供與 COPY 命令搭配使用的串流。

`xid(format_id, global_transaction_id, …)`  
建立交易 ID。只有 `global_transaction_id` 參數會用於 postgres。format\$1id 和 branch\$1qualifier 不會用於 postgres。`global_transaction_id` 可以是由傳回元組 (`format_id`, `global_transaction_id`, `branch_qualifier`) 的 postgres 支援的任何字串識別碼。

`tpc_begin(xid)`  
使用由格式 ID、全域交易 ID 和分支限定詞組成的交易 ID `xid` 來開始 TPC 交易。

`tpc_prepare`  
執行以 .tpc\$1begin 開始之交易的第一個階段。

`tpc_commit([xid])`  
以無引數方式呼叫時，.tpc\$1commit 會遞交先前使用 .tpc\$1prepare() 所準備的 TPC 交易。

`tpc_rollback([xid])`  
以無引數方式呼叫時，.tpc\$1rollback 會復原 TPC 交易。

`tpc_recover`  
傳回適合與 .tpc\$1commit(xid) 或 .tpc\$1rollback(xid) 搭配使用的待定交易 ID 清單。

## 游標
<a name="python-api-cursor"></a>

接下來，您可以找到游標 API 操作的描述。

`__init__(connection[, paramstyle])`  
將原始游標物件初始化。

`insert_data_bulk(filename, table_name, parameter_indices, column_names, delimiter, batch_size)`  
執行大量 INSERT 陳述式。

`execute(operation[, args, stream, …])`  
執行資料庫操作。

`executemany(operation, param_sets)`  
準備資料庫操作，然後針對所提供的所有參數序列或映射執行此操作。

`fetchone`  
擷取查詢結果集的下一列。

`fetchmany([num])`  
擷取下一組查詢結果資料列。

`fetchall`  
擷取查詢結果的所有剩餘資料列。

`close`  
立即關閉游標。

`__iter__`  
可對游標物件進行迭代以從查詢中擷取資料列。

`fetch_dataframe([num])`  
傳回上次查詢結果的資料框。

`write_dataframe(df, table)`  
將相同結構資料框寫入到 Amazon Redshift 資料庫。

`fetch_numpy_array([num])`  
傳回上次查詢結果的 NumPy 陣列。

`get_catalogs`  
Amazon Redshift 不支援來自單一連線的多個型錄。Amazon Redshift 只會傳回目前的型錄。

`get_tables([catalog, schema_pattern, …])`  
傳回系統內使用者定義的唯一公有資料表。

`get_columns([catalog, schema_pattern, …])`  
傳回 Amazon Redshift 資料庫中特定資料表內所有資料欄的清單。

## AdfsCredentialsProvider 外掛程式
<a name="python-adfs-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 AdfsCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.AdfsCredentialsProvider()
```

## AzureCredentialsProvider 外掛程式
<a name="python-azure-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 AzureCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.AzureCredentialsProvider()
```

## BrowserAzureCredentialsProvider 外掛程式
<a name="python-browser-azure-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 BrowserAzureCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.BrowserAzureCredentialsProvider()
```

## BrowserSamlCredentialsProvider 外掛程式
<a name="python-browser-saml-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 BrowserSamlCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.BrowserSamlCredentialsProvider()
```

## OktaCredentialsProvider 外掛程式
<a name="python-okta-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 OktaCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.OktaCredentialsProvider()
```

## PingCredentialsProvider 外掛程式
<a name="python-ping-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 PingCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.PingCredentialsProvider()
```

## SamlCredentialsProvider 外掛程式
<a name="python-saml-credentials-plugin"></a>

以下是 Amazon Redshift Python 連接器的 SamlCredentialsProvider 外掛程式 API 操作語法。

```
redshift_connector.plugin.SamlCredentialsProvider()
```