本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 Oracle NetSuite Oracle NetSuite 是一款全方位雲端業務管理解決方案，透過自動化核心流程並提供營運和財務績效的即時可見性，協助組織更有效地運作。透過單一整合的應用程式套件來管理會計、訂單處理、庫存管理、生產、供應鏈和倉儲操作，Oracle NetSuite 可讓公司清楚了解其資料並對其業務進行更嚴格的控制。 **Topics** + [AWS Glue 支援 Oracle NetSuite](oracle-netsuite-support.md) + [包含用於建立和使用連線的 API 操作的政策](oracle-netsuite-configuring-iam-permissions.md) + [設定 Oracle NetSuite](oracle-netsuite-configuring.md) + [設定 Oracle NetSuite 連線](oracle-netsuite-configuring-connections.md) + [從 Oracle NetSuite 實體中讀取](oracle-netsuite-reading-from-entities.md) + [Oracle NetSuite 連線選項](oracle-netsuite-connection-options.md) + [Oracle NetSuite 連接器的限制和備註](oracle-netsuite-connector-limitations.md) # AWS Glue 支援 Oracle NetSuite AWS Glue 支援 Oracle NetSuite，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Oracle NetSuite 查詢資料。 **支援作為目標？** 否。 **支援的 Oracle NetSuite API 版本** 支援下列 Oracle NetSuite 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 主控台的使用者。 # 設定 Oracle NetSuite 您必須先符合下列要求，才能使用 從 Oracle NetSuite AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Oracle NetSuite 帳戶。如需詳細資訊，請參閱[建立 Oracle NetSuite 帳戶](#oracle-netsuite-configuring-creating-oracle-netsuite-account)。 + 您的 Oracle NetSuite 帳戶已啟用 API 存取。 + 您已在 Oracle NetSuite 開發人員帳戶中建立 OAuth 2.0 API 整合。此整合提供用戶端登入資料，在對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱[建立 Oracle NetSuite 用戶端應用程式和 OAuth 2.0 憑證](#oracle-netsuite-configuring-creating-oracle-netsuite-client-app)。 如果您符合這些要求，就可以 AWS Glue 連線到 Oracle NetSuite 帳戶。 ## 建立 Oracle NetSuite 帳戶 導覽至 [Oracle NetSuite](https://www.netsuite.com/portal/home.shtml)，然後選擇**免費產品導覽**。填寫必要的詳細資訊以取得免費產品導覽，可以透過該導覽聯絡廠商。獲取帳戶的程序如下： + 透過廠商完成 NetSuite 帳戶的獲取，廠商提供的表單/報價必須經過法律審查。 + Oracle NetSuite 連接器購買的帳戶是**標準雲端服務**。 + 此帳戶由廠商建立，臨時憑證由他們共用。您會收到來自 NetSuite 的歡迎郵件，其中包含使用者名稱等詳細資訊，以及設定密碼的連結。 + 使用**設定您的密碼**連結，為廠商提供的使用者名稱設定密碼。 ## 建立 Oracle NetSuite 用戶端應用程式和 OAuth 2.0 憑證 若要取得用戶端 ID 和用戶端機密，請建立 Oracle NetSuite 用戶端應用程式： 1. 透過 [NetSuite 客戶登入](https://system.netsuite.com/pages/customerlogin.jsp)來登入您的 NetSuite 帳戶。 1. 選擇**設定** > **公司** > **啟用功能**。 1. 導覽至 **SuiteCloud** 區段，然後選取 **SuiteTalk (Web 服務)** 下的 **REST WEB 服務**核取方塊。 1. 選取**管理身分驗證**下的 **OAUTH 2.0** 核取方塊。按一下 **Save (儲存)**。 1. 前往**設定** > **整合** > **管理整合**，然後選擇**新增**以建立 OAuth2.0 應用程式。 1. 輸入您選擇的名稱，並將 **STATE** 保留為「已啟用」。 1. 如果已勾選，請取消勾選**字符型身分驗證**下顯示的 **TBA: AUTHORIZATION FLOW** 和 **TOKEN-BASED AUTHENTICATION** 核取方塊。 1. 選取 **OAuth 2.0** 下的**授權碼授權**和**公有用戶端**核取方塊。 1. 在「驗證」下，記下用戶端 ID 和用戶端機密。 1. 輸入**重新導向 URI**。例如，https://us-east-1.console.aws.amazon.com/gluestudio/oauth 1. 選取**範圍**下的 **REST WEB 服務**核取方塊。 1. 選取**使用者憑證**下的**使用者憑證**核取方塊。選擇**儲存**。 1. 請記下**用戶端憑證**下的消費者金鑰/用戶端 ID 和消費者機密/用戶端機密。這些值只會顯示一次。 1. 導覽至**使用者/角色** > **管理角色** > **新增**，視需要建立「管理員」角色。 1. 建立自訂角色時，在**許可**索引標籤下為下列實體/功能新增完整存取權： + "Deposit", "Items", "Item Fulfillment", "Make Journal Entry", "Purchase Order", "Subsidiaries", "Vendors", "Bills", "Vendor Return Authorization", "Track Time", "Customer Payment", "Custom Record Entries", "Custom Record Types", "REST Web Services", "OAuth 2.0 Authorized Applications Management", "Custom Entity Fields", "Log in using OAuth 2.0 Access Tokens". 如需詳細資訊，請參閱《NetSuite 應用程式套件文件》中的 [OAuth 2.0](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_157769826287.html)。 # 設定 Oracle NetSuite 連線 Oracle NetSuite 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。授予類型決定 如何與 Oracle NetSuite AWS Glue 通訊，以請求存取您的資料。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。根據預設，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式 (AWS Glue 受管用戶端應用程式），除了 Oracle NetSuite 執行個體 URL 之外，不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Oracle NetSuite，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Oracle NetSuite 執行個體。 + 使用者仍然可以選擇在 Oracle NetSuite 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Oracle NetSuite 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需建立授權碼 OAuth 流程連線應用程式的公有 Oracle NetSuite 文件，請參閱[公有應用程式](https://developers.oracle-netsuite.com/docs/api/creating-an-app)。 若要設定 Oracle NetSuite 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：必須在 AWS Glue中建立連線機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Oracle NetSuite。 1. 提供 Oracle NetSuite 環境。 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`。 # 從 Oracle NetSuite 實體中讀取 **必要條件** 您想要從中讀取的 Oracle NetSuite 物件。您將需要物件名稱，例如 `deposit` 或 `timebill`。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援排序依據 | 支援限制 | 支援 SELECT \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 訂金 | 是 | 否 | 是 | 是 | 是 | | 說明項目 | 是 | 否 | 是 | 是 | 是 | | 庫存項目 | 是 | 否 | 是 | 是 | 是 | | 項目履行 | 是 | 否 | 是 | 是 | 是 | | 項目群組 | 是 | 否 | 是 | 是 | 是 | | 日誌項 | 是 | 否 | 是 | 是 | 是 | | 非庫存購買項目 | 是 | 否 | 是 | 是 | 是 | | 非庫存轉售項目 | 是 | 否 | 是 | 是 | 是 | | 非庫存銷售項目 | 是 | 否 | 是 | 是 | 是 | | 購買訂單 | 是 | 否 | 是 | 是 | 是 | | 附屬公司 | 是 | 否 | 是 | 是 | 是 | | 廠商 | 是 | 否 | 是 | 是 | 是 | | 廠商帳單 | 是 | 否 | 是 | 是 | 是 | | 供應商退貨授權 | 是 | 否 | 是 | 是 | 是 | | 時間帳單 | 是 | 否 | 是 | 是 | 是 | | 客戶付款 | 是 | 否 | 是 | 是 | 是 | | 履行請求 | 是 | 否 | 是 | 是 | 是 | | 項目 | 是 | 是 | 是 | 是 | 是 | | 交易行 | 是 | 是 | 是 | 是 | 是 | | 交易會計行 | 是 | 是 | 是 | 是 | 是 | | 自訂記錄類型 (動態) | 是 | 是 | 是 | 是 | 是 | **範例**： ``` netsuiteerp_read = glueContext.create_dynamic_frame.from_options( connection_type="netsuiteerp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "deposit", "API_VERSION": "v1" } ) ``` **Oracle NetSuite 實體和欄位詳細資訊**： Oracle NetSuite 會在選取的實體下動態載入可用欄位。視欄位的資料類型而定，其支援下列篩選條件運算子。 | 欄位資料類型 | 支援的篩選條件運算子 | | --- | --- | | String | LIKE, =, \$1= | | Date | BETWEEN, =, <, <=, >, >= | | DateTime | BETWEEN, <, <=, >, >= | | 數值 | =, \$1=, <, <=, >, >= | | Boolean | =, \$1= | **篩選條件表達式中布林值的預期輸入格式**： | 實體 | 布林值 "true" 值格式 | 布林值 "false" 值格式 | 範例 | | --- | --- | --- | --- | | 「項目」、「交易行」、「交易會計行」和「自訂記錄類型」實體 | T 或 t | F 或 f | isinactive = "T" 或 isinactive = "t" | | 所有其他實體 | true | false | isinactive = true | ## 分區查詢 **欄位型分區** Oracle NetSuite 連接器具有動態中繼資料，以便動態選擇欄位型分區的支援欄位。資料類型為 Integer、BigInteger、Date 或 DateTime 的欄位支援欄位型分區。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於時間戳記欄位，接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "TIMESTAMP \"1707256978123\"" "TIMESTAMP \"1702600882\"" "TIMESTAMP '2024-02-06T22:00:00:00.000Z'" "TIMESTAMP '2024-02-06T22:00:00:00Z'" "TIMESTAMP '2024-02-06'" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` netsuiteerp_read = glueContext.create_dynamic_frame.from_options( connection_type="netsuiteerp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "deposit", "API_VERSION": "v1", "PARTITION_FIELD": "id", "LOWER_BOUND": "1", "UPPER_BOUND": "10000", "NUM_PARTITIONS": "10" } ``` **記錄型分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 在記錄型分區中，會從 Oracle NetSuite API 中查詢存在的記錄總數，並除以提供的 `NUM_PARTITIONS` 數目，然後由每個子查詢同時擷取產生的記錄數目。 + `NUM_PARTITIONS`：分區數目。 範例： ``` netsuiteerp_read = glueContext.create_dynamic_frame.from_options( connection_type="netsuiteerp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "deposit", "API_VERSION": "v1", "NUM_PARTITIONS": "3" } ``` # Oracle NetSuite 連線選項 以下是 Oracle NetSuite 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Oracle NetSuite 實體的名稱。範例：deposit。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Oracle NetSuite Rest API 版本。該值將為 v1，因為 Oracle NetSuite 目前僅支援 v1 版本。 + `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。用於讀取。要讀取的分區數目。用於欄位型和記錄型分區。 + `INSTANCEE_URL`(String) - 格式為 https://\$1account-id\$1.suitetalk.api.netsuite.com 的有效 NetSuite 執行個體 URL。 # Oracle NetSuite 連接器的限制和備註 以下是 Oracle NetSuite 連接器的限制或備註： + access\$1token 與 refresh\$1token 參數的值採用 JSON Web Token (JWT) 格式。存取字符的有效期為 60 分鐘，而 refresh\$1token 的有效期為七天。 + 在產生用戶端 ID 和用戶端機密期間，如果選取 "PUBLIC CLIENT" 和 "AUTHORIZATION CODE GRANT"，則重新整理字符的有效期僅為三小時，且僅供一次性使用。 + 可以使用連接器擷取最多 1,00,000 筆記錄。如需詳細資訊，請參閱[透過 REST Web Services 執行 SuiteQL 查詢](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157909186990.html)。 + 會建立分區，每個分區會以 1000 的倍數擷取記錄，但可能最後一個分區會擷取剩餘記錄。 + 對於 Item、Transaction Line 和 Transaction Accounting Line 物件，連接器不支援幾個運算子，原因如下： + 將 `EQUAL_TO`、`NOT_EQUAL_TO` 篩選條件運算子套用至 Date 類型的欄位，會產生不可靠的結果。 + 將 `LESS_THAN_OR_EQUAL_TO` 篩選條件運算子套用至 Date 類型的欄位會產生不可靠的結果，並且行為類似於 `LESS_THAN` 運算子。 + 將 `GREATER_THAN` 篩選條件運算子套用至 Date= 類型的欄位會產生不可靠的結果，並且行為類似於 `GREATER_THAN_OR_EQUAL_TO` 運算子。 + 對於 Item、Transaction Line、Transaction Accounting Line 和 Custom Record Type 物件，布林值的格式為 T/F，而非標準的 true/false。連接器會將 t/f 值映射至 true/false，以確保資料一致性。