本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 PayPal
PayPal 是一種付款系統，可促進各方之間的線上資金轉帳，例如客戶和線上供應商之間的轉帳。如果您是 PayPal 使用者，您的帳戶會包含交易的資料，例如付款人、日期和狀態。您可以使用 AWS Glue 將資料從 PayPal 傳輸到特定 AWS 服務或其他支援的應用程式。
**Topics**
+ [AWS Glue 支援PayPal](paypal-support.md)
+ [包含用於建立和使用連線的 API 操作的政策](paypal-configuring-iam-permissions.md)
+ [設定 PayPal](paypal-configuring.md)
+ [設定 PayPal 連線](paypal-configuring-connections.md)
+ [從 PayPal 實體中讀取](paypal-reading-from-entities.md)
+ [PayPal 連線選項](paypal-connection-options.md)
+ [PayPal 連接器的限制和備註](paypal-connector-limitations.md)
# AWS Glue 支援PayPal
AWS Glue 支援PayPal，如下所示：
**支援作為來源？**
是。您可以使用 AWS Glue ETL 任務從PayPal 查詢資料。
**支援作為目標？**
否。
**支援的 PayPal API 版本**
支援以下 PayPal API 版本：
+ v1
# 包含用於建立和使用連線的 API 操作的政策
下列範例政策說明建立和使用 連線所需的 AWS IAM 許可。如果您要建立新角色，請建立包含下列項目的政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
如果不想使用上述方法，可選擇使用下列受管 IAM 政策：
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – 准許存取各種 AWS Glue 程序代表您執行所需的資源。這些資源包括 AWS Glue Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接至 的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。
# 設定 PayPal
您必須先符合下列要求，才能使用 AWS Glue 來從 PayPal 傳輸資料：
## 最低需求
以下是最低要求：
+ 您擁有一個具有用戶端憑證的 PayPal 帳戶。
+ 您的 PayPal 帳戶具有包含有效授權的 API 存取。
如果您符合這些要求，就可以 AWS Glue 連線到您的PayPal 帳戶。對於一般連線，不需要在 PayPal 中執行任何其他操作。
# 設定 PayPal 連線
PayPal 支援 OAuth2 的 CLIENT CREDENTIALS 授權類型。
+ 此授予類型會被視為 2 長度的 OAuth 2.0，因為用戶端使用它來取得使用者內容外的存取權杖。 AWS Glue 能夠使用用戶端 ID 和用戶端秘密來驗證您定義的自訂服務所提供的 PayPal APIs。
+ 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。
+ 此授權類型會產生短期存留的存取字符，且可以透過呼叫 `/v2/oauth2/token` 端點來續約。
+ 如需具有用戶端憑證之 OAuth 2.0 的公有 PayPal 文件，請參閱[身分驗證](https://developer.paypal.com/api/rest/authentication/)。
若要設定 PayPal 連線：
1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密：
1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。
1. 注意：您必須為 中的連線建立秘密 AWS Glue。
1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**：
1. 選取**連線類型**時，請選取 PayPal。
1. 提供您要連線的 PayPal 執行個體的 `INSTANCE_URL`。
1. 選取 AWS Glue 可以擔任並具有下列動作許可的 AWS IAM 角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。
1. 如果想要使用您的網路，請選取網路選項。
1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。
## 取得 OAuth 2.0 憑證
若要呼叫 Rest API，需要將用戶端 ID 和用戶端機密交換為存取字符。如需詳細資訊，請參閱[開始使用 PayPal REST API](https://developer.paypal.com/api/rest/)。
# 從 PayPal 實體中讀取
**必要條件**
您要從中讀取的 PayPal 物件。將需要物件名稱，`transaction`。
**來源的支援實體**：
| 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- |
| transaction | 是 | 是 | 否 | 是 | 是 |
**範例**：
```
paypal_read = glueContext.create_dynamic_frame.from_options(
connection_type="paypal",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "transaction",
"API_VERSION": "v1",
"INSTANCE_URL": "https://api-m.paypal.com"
}
```
**PayPal 實體和欄位詳細資訊**：
具有靜態中繼資料的實體：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/paypal-reading-from-entities.html)
## 分區查詢
如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。
+ `PARTITION_FIELD`：用來分區查詢的欄位名稱。
+ `LOWER_BOUND`：所選分區欄位的**包含**下限值。
對於 Datetime 欄位，接受 ISO 格式的值。
有效值的範例：
```
"2024-07-01T00:00:00.000Z"
```
+ `UPPER_BOUND`：所選分區欄位的**唯一**上限值。
+ `NUM_PARTITIONS`：分區數目。
實體分區支援下列欄位：
| 實體名稱 | 分區欄位 | 資料類型 |
| --- | --- | --- |
| transaction | transaction\$1initiation\$1date | DateTime |
範例：
```
paypal_read = glueContext.create_dynamic_frame.from_options(
connection_type="paypal",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "transaction",
"API_VERSION": "v1",
"PARTITION_FIELD": "transaction_initiation_date"
"LOWER_BOUND": "2024-07-01T00:00:00.000Z"
"UPPER_BOUND": "2024-07-02T00:00:00.000Z"
"NUM_PARTITIONS": "10"
}
```
# PayPal 連線選項
以下是 PayPal 的連線選項：
+ `ENTITY_NAME`(String) - (必要) 用於讀取。PayPal 中的物件名稱。
+ `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 PayPal Rest API 版本。
+ `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。
+ `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。
+ `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。
+ `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。
+ `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。
+ `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。
+ `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。
# PayPal 連接器的限制和備註
以下是 PayPal 連接器的限制或備註：
+ [PayPal 交易文件](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get)提到，執行的交易最多需要三小時才會出現在清單交易呼叫中。不過，據觀察，根據 [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime) 的不同，需要的時間更長。在這裡，`last_refreshed_datetime` 是您從 API 獲得資料之前的時間量。
+ 如果 `last_refreshed_datetime` 小於請求的 `end_date`，則 `end_date` 會變成等於 `last_refreshed_datetime`，因為我們只有該時間點之前的資料。
+ `transaction_initiation_date` 欄位是為 `transaction` 實體提供的強制性篩選條件，此欄位[支援的最大](https://developer.paypal.com/docs/transaction-search/#:~:text=The%20maximum%20supported%20date%20range%20is%2031%20days.)日期範圍為 31 天。
+ 當您使用篩選條件 (查詢參數) 而非 `transaction_initiation_date` 欄位來呼叫 `transaction` 實體 API 請求時，預期不會在回應中擷取 [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.) 欄位的值。