本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 新增 AWS Glue 連線 您可以透過程式設計方式連接到 AWS Glue for Spark 中的資料來源。如需詳細資訊，請參閱[AWS Glue for Spark 中 ETL 的連線類型和選項](aws-glue-programming-etl-connect.md) 您也可以使用 AWS Glue 主控台來新增、編輯、刪除和測試連線。如需 AWS Glue 連線的相關資訊，請參閱 [連線至資料](glue-connections.md)。 **Topics** + [連線至 Adobe Analytics](connecting-to-adobe-analytics.md) + [連線至 Adobe Marketo Engage](connecting-to-data-adobe-marketo-engage.md) + [在 AWS Glue Studio 中連線至 Amazon Redshift](connecting-to-data-redshift.md) + [連線至 Asana](connecting-to-asana.md) + [在 AWS Glue Studio 中連線至 Azure Cosmos DB](connecting-to-data-azurecosmos.md) + [在 AWS Glue Studio 中連線至 Azure SQL](connecting-to-data-azuresql.md) + [連線至 Blackbaud Raiser's Edge NXT](connecting-to-data-blackbaud.md) + [連線至 CircleCI](connecting-to-data-circleci.md) + [連線至 Datadog](connecting-to-datadog.md) + [連線至 Docusign Monitor](connecting-to-data-docusign-monitor.md) + [連線至 Domo](connecting-to-data-domo.md) + [連線至 Dynatrace](connecting-to-data-dynatrace.md) + [連線至 Facebook Ads](connecting-to-data-facebook-ads.md) + [連線至 Facebook Page Insights](connecting-to-data-facebook-page-insights.md) + [連線至 Freshdesk](connecting-to-data-freshdesk.md) + [連線至 Freshsales](connecting-to-data-freshsales.md) + [連線至 Google Ads](connecting-to-googleads.md) + [連線至 Google Analytics 4](connecting-to-googleanalytics.md) + [在 AWS Glue Studio 中連線至 Google BigQuery](connecting-to-data-bigquery.md) + [連線至 Google Search Console](connecting-to-data-google-search-console.md) + [連線至 Google Sheets](connecting-to-googlesheets.md) + [連線至 HubSpot](connecting-to-data-hubspot.md) + [連線至 Instagram Ads](connecting-to-data-instagram-ads.md) + [在 AWS Glue Studio 中連線至 Intercom](connecting-to-data-intercom.md) + [連線至 Jira Cloud](connecting-to-data-jira-cloud.md) + [連線至 Kustomer](connecting-to-data-kustomer.md) + [連線至 LinkedIn](connecting-to-linkedin.md) + [連線至 Mailchimp](connecting-to-mailchimp.md) + [連線至 Microsoft Dynamics 365 CRM](connecting-to-microsoft-dynamics-365.md) + [連線至 Microsoft Teams](connecting-to-microsoft-teams.md) + [連線至 Mixpanel](connecting-to-mixpanel.md) + [連線至 Monday](connecting-to-monday.md) + [在 AWS Glue Studio 中連線至 MongoDB](connecting-to-data-mongodb.md) + [連線至 Oracle NetSuite](connecting-to-data-oracle-netsuite.md) + [在 AWS Glue Studio 中連線至 OpenSearch Service](connecting-to-data-opensearch.md) + [連線至 Okta](connecting-to-okta.md) + [連線至 PayPal](connecting-to-data-paypal.md) + [連線至 Monday](connecting-to-pendo.md) + [連線至 Pipedrive](connecting-to-pipedrive.md) + [連線至 Productboard](connecting-to-productboard.md) + [連線至 QuickBooks](connecting-to-data-quickbooks.md) + [連線至 REST API](connecting-to-data-rest-api.md) + [連線至 Salesforce](connecting-to-data-salesforce.md) + [連線至 Salesforce Marketing Cloud](connecting-to-data-salesforce-marketing-cloud.md) + [連線至 Salesforce Commerce Cloud](connecting-to-salesforce-commerce-cloud.md) + [連線至 Salesforce Marketing Cloud Account Engagement](connecting-to-data-salesforce-marketing-cloud-account-engagement.md) + [在 AWS Glue Studio 中連線至 SAP HANA](connecting-to-data-saphana.md) + [連線至 SAP OData](connecting-to-data-sap-odata.md) + [連線至 SendGrid](connecting-to-data-sendgrid.md) + [連線至 ServiceNow](connecting-to-data-servicenow.md) + [在 AWS Glue Studio 中連線至 Slack](connecting-to-data-slack.md) + [連線至 Smartsheet](connecting-to-smartsheet.md) + [在 AWS Glue Studio 中連線至 Snapchat Ads](connecting-to-data-snapchat-ads.md) + [在 AWS Glue Studio 中連線至 Snowflake](connecting-to-data-snowflake.md) + [在 AWS Glue Studio 中連線至 Stripe](connecting-to-data-stripe.md) + [在 AWS Glue Studio 中連線至 Teradata Vantage](connecting-to-data-teradata.md) + [連線至 Twilio](connecting-to-data-twilio.md) + [在 AWS Glue Studio 中連線至 Vertica](connecting-to-data-vertica.md) + [連線至 WooCommerce](connecting-to-data-woocommerce.md) + [連線至 Zendesk](connecting-to-data-zendesk.md) + [連線至 Zoho CRM](connecting-to-data-zoho-crm.md) + [連線至 Zoom Meetings](connecting-to-data-zoom-meetings.md) + [使用自己的 JDBC 驅動程式新增 JDBC 連線](console-connections-jdbc-drivers.md) # 連線至 Adobe Analytics Adobe Analytics 是一種強大的資料分析平台，可從支援客戶旅程的多管道數位體驗收集資料，並提供分析資料的工具。這是行銷人員和商業分析師經常用於商業分析目的的平台。如果您是 Adobe Analytics 使用者，您可以 AWS Glue 連線至您的 Adobe Analytics 帳戶。然後，您可以在 ETL 任務中使用 Adobe Analytics 作為資料來源。執行這些任務，以在 Adobe Analytics AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Adobe Analytics](adobe-analytics-support.md) + [包含用於建立和使用連線的 API 操作的政策](adobeanalytics-configuring-iam-permissions.md) + [設定 Adobe Analytics](adobeanalytics-configuring.md) + [設定 Adobe Analytics 連線](adobeanalytics-configuring-connections.md) + [從 Adobe Analytics 實體中讀取](adobeanalytics-reading-from-entities.md) + [Adobe Analytics 連線選項](adobeanalytics-connection-options.md) + [建立 Adobe Analytics 帳戶](adobeanalytics-create-account.md) + [限制](adobeanalytics-connector-limitations.md) # AWS Glue 支援 Adobe Analytics AWS Glue 支援 Adobe Analytics，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Adobe Analytics 查詢資料。 **支援作為目標？** 否。 **支援的 Adobe Analytics API 版本** v2.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Adobe Analytics 您必須先符合下列要求，才能使用 從 Adobe Analytics AWS Glue 傳輸： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Adobe Analytics 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Adobe Analytics 帳戶](adobeanalytics-create-account.md)。 + 您的 Adobe Analytics 帳戶已啟用 API 存取。Select、Prime 和 Ultimate 版本預設會啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到 Adobe Analytics 帳戶。對於一般連線，不需要在 Adobe Analytics 中執行任何其他操作。 # 設定 Adobe Analytics 連線 Adobe Analytics 支援 `OAuth2` 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。使用者可以選擇在 Adobe Analytics 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，其仍會重新導向至 Adobe Analytics 以登入，並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需為 AUTHORIZATION\$1CODE OAuth 流程建立連線應用程式的公有 Adobe Analytics 文件，請參閱 [Adobe Analytics API](https://adobedocs.github.io/analytics-2.0-apis/)。 若要設定 Adobe Analytics 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Adobe Analytics。 1. 提供您要連線的 Adobe Analytics 的 `x_api_key, instanceUrl`。 1. 選取 AWS Glue 可擔任的 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`。 # 從 Adobe Analytics 實體中讀取 **先決條件** 您想要從中讀取的 Adobe Analytics 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 註釋 | 是 | 是 | 是 | 是 | 否 | | 計算的指標 | 是 | 是 | 是 | 是 | 否 | | 計算的指標函數 | 是 | 否 | 否 | 是 | 否 | | 元件中繼資料共用 | 是 | 是 | 否 | 是 | 否 | | 日期範圍 | 是 | 是 | 否 | 是 | 否 | | 維度 | 是 | 否 | 否 | 是 | 否 | | 指標 | 是 | 否 | 否 | 是 | 否 | | 專案 | 是 | 否 | 否 | 是 | 否 | | 報告熱門項目 | 是 | 是 | 否 | 是 | 否 | | 客群 | 是 | 是 | 是 | 是 | 否 | | 使用日誌 | 是 | 是 | 否 | 是 | 否 | **範例** ``` adobeAnalytics_read = glueContext.create_dynamic_frame.from_options( connection_type="adobeanalytics", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "annotation/ex*****", "API_VERSION": "v2.0" }) ``` **Adobe Analytics 實體和欄位詳細資訊** + [註釋](https://adobedocs.github.io/analytics-2.0-apis/#/Annotations) + [計算的指標](https://adobedocs.github.io/analytics-2.0-apis/#/Calculated%20Metrics) + [元件中繼資料](https://adobedocs.github.io/analytics-2.0-apis/#/Component%20Meta%20Data) + [日期範圍](https://adobedocs.github.io/analytics-2.0-apis/#/Date%20Ranges) + [Dimensions (尺寸)](https://adobedocs.github.io/analytics-2.0-apis/#/Dimensions) + [指標](https://adobedocs.github.io/analytics-2.0-apis/#/Metrics) + [專案](https://adobedocs.github.io/analytics-2.0-apis/#/Projects) + [報告](https://adobedocs.github.io/analytics-2.0-apis/#/Reports) + [客群](https://adobedocs.github.io/analytics-2.0-apis/#/Segments) + [使用者](https://adobedocs.github.io/analytics-2.0-apis/#/Users) + [使用日誌](https://adobedocs.github.io/analytics-2.0-apis/#/Usage%20Logs) # Adobe Analytics 連線選項 以下是 Adobe Analytics 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Adobe Analytics 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Adobe Analytics Rest API 版本。例如，V2.0。 + `X_API_KEY`(String) - (必要) 用於讀取/寫入。需要驗證向 API 提出請求的開發人員或應用程式。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Adobe Analytics 帳戶 1. 透過存取 [Adobe 合作夥伴計畫](https://partners.adobe.com/exchangeprogram/creativecloud.html)註冊交換合作夥伴計畫。 1. 選擇**加入交換計畫**。 1. 使用貴公司電子郵件地址註冊或建立帳戶。 1. 從建議方塊中，選取具有 Adobe Analytics 產品訂閱的適當公司。 1. 確保帳戶已向具有作用中 Adobe Analytics 訂閱的有效組織 (從可用的清單中) 註冊。 1. 在公司管理部門核准後，按一下核准電子郵件中的連結來啟用您的帳戶。 **驗證您建立的帳戶是否可以存取 Adobe Analytics 服務** 1. 登入 [Adobe 管理主控台](https://adminconsole.adobe.com/)。 1. 檢查頁面右上角的組織名稱，以確保您已登入正確的公司。 1. 選取**產品**並驗證 Adobe Analytics 是否可用。 **注意** 如果沒有可用的組織，或 Adobe Analytics 產品呈現灰色或不可用，則可能是您的帳戶未與組織關聯和/或沒有作用中的 Adobe Analytics 訂閱。請聯絡您的系統管理員，以請求存取您帳戶的此服務。 **建立專案和 `OAuth2.0` 憑證** 1. 登入您希望在其中建立 [OAuth 2.0 應用程式](https://developer.adobe.com/developer-console/docs/guides/services/services-add-api-oauth/)的 Adobe Analytics 帳戶。 1. 選取**專案**，然後**建立新專案**。 1. 若要新增專案，請選取**新增至專案**，然後選取 **API**。 1. 選取 **Adobe Analytics API**。 1. 選取 **OAUTH** 作為使用者身分驗證。 1. 選取 **Web** 作為 `OAUTH` 並提供重新導向 URI。 如需重新導向 URI 及其模式，請參閱下列內容： + `OAuth 2.0` 預設重新導向 URI – 預設重新導向 URI 是 Adobe 在身分驗證程序期間將存取的頁面 URL。例如 `https://ap-southeast-2.console.aws.amazon.com/appflow/oauth` + OAuth 2.0 重新導向 URI 模式 – 重新導向 URI 模式是 URI 路徑 (或以逗號分隔的路徑清單)，Adobe 可以在登入流程完成時重新導向到該路徑 (如果請求)。例如 `https://ap-southeast-2\\.console\\.aws\\.amazon\\.com` 1. 新增下列範圍： + `openid` + `read_organizations` + `additional_info.projectedProductContext` + `additional_info.job_function` 1. 選擇**儲存憑證**。 1. 建立應用程式之後，將 `Client ID` 和 `Client Secret` 值複製到文字檔案。 # 限制 以下是 Adobe Analytics 連接器的限制： + Adobe Analytics 不支援欄位型分區和記錄型分區。不支援以欄位為基礎的分區，因為您無法查詢您分區的欄位。無法支援記錄型分區，因為沒有佈建而無法取得分頁的「偏移」。 + 在 `Report Top Item` 實體中，`startDate` 和 `endDate` 查詢參數未如預期般運作。系統不會根據這些參數來篩選回應，這會導致此實體的篩選條件和增量流程發生問題。 + 對於 `Annotation`、`Calculated Metrics`、`Calculated Metrics Function`、`Date Ranges`、`Dimension`、`Metric`、`Report Top Items`、 `Project`和 `Segment`實體，`locale` 查詢參數會指定要用於回應當地語系化區段的語言，而不會篩選記錄。例如， `locale="ja_JP"` 會以日文顯示資料。 + `Report Top Item` 實體 – 篩選 `dateRange` 和 `lookupNoneValues` 欄位目前無法運作。 + `Segment` 實體：使用篩選條件值 `includeType=“templates”`時，其他欄位上的篩選條件無法運作。 + `Date Range` 實體 – `curatedRsid` 欄位上的篩選條件無法運作。 + `Metric entity` 實體 – 使用 "false" 值篩選可分區欄位可同時提供 true 和 false 值的結果。 # 連線至 Adobe Marketo Engage Adobe Marketo Engage 是一種行銷自動化平台，可讓行銷人員管理面向潛在客戶和客戶的個人化多管道計畫和行銷活動。 **Topics** + [AWS Glue 支援 Adobe Marketo Engage](adobe-marketo-engage-support.md) + [包含用於建立和使用連線的 API 操作的政策](adobe-marketo-engage-configuring-iam-permissions.md) + [設定 Adobe Marketo Engage](adobe-marketo-engage-configuring.md) + [設定 Adobe Marketo Engage 連線](adobe-marketo-engage-configuring-connections.md) + [從 Adobe Marketo Engage 實體讀取](adobe-marketo-engage-reading-from-entities.md) + [寫入 Adobe Marketo Engage 實體](adobe-marketo-engage-writing-to-entities.md) + [Adobe Marketo Engage 連線選項](adobe-marketo-engage-connection-options.md) + [Adobe Marketo Engage 連接器的限制和備註](adobe-marketo-engage-connector-limitations.md) # AWS Glue 支援 Adobe Marketo Engage AWS Glue 支援 Adobe Marketo Engage，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Adobe Marketo Engage 查詢資料。 **支援作為目標？** 是。您可以使用 AWS Glue ETL 任務將資料寫入 Adobe Marketo。 **支援的 Adobe Marketo Engage API 版本** 支援下列 Adobe Marketo Engage 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 主控台的使用者。 # 設定 Adobe Marketo Engage 您必須先符合下列要求，才能使用 從 Adobe Marketo Engage AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有包含用戶端憑證的 Adobe Marketo Engage 帳戶。 + 您的 Adobe Marketo Engage 帳戶具有包含有效授權的 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到 Adobe Marketo Engage 帳戶。對於一般連線，不需要在 Adobe Marketo Engage 中執行任何其他操作。 ## 取得 OAuth 2.0 憑證 若要取得 API 憑證以對執行個體進行已驗證的呼叫，請參閱 [Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api) # 設定 Adobe Marketo Engage 連線 Adobe Marketo Engage 支援 CLIENT CREDENTIALS 授權類型。 + 此授予類型會被視為 2 字長度的 OAuth 2.0，因為用戶端使用它來取得使用者內容外的存取權杖。 AWS Glue 能夠使用用戶端 ID 和用戶端秘密來驗證您定義的自訂服務所提供的 Adobe Marketo Engage APIs。 + 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。 + 此授權類型會產生短期存留的存取字符，且可以透過呼叫身分端點來續約。 + 如需具有用戶端認證的 OAuth 2.0 的公有 Adobe Marketo Engage 文件，請參閱《Adobe Marketo Engage 開發人員指南》中的[身分驗證](https://developers.adobe-marketo-engage.com/rest-api/authentication/)。 設定 Adobe Marketo Engage 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須在 AWS Glue中為每個連線建立機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 在選取**連線類型**時，選取 Adobe Marketo Engage。 1. 提供您要連線的 Adobe Marketo Engage 執行個體的 `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`。 # 從 Adobe Marketo Engage 實體讀取 **必要條件** 您想要從中讀取的 Adobe Marketo Engage 物件。您將需要物件名稱，例如潛在客戶、活動或自訂物件。下表顯示支援的實體。 **來源 (同步) 支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | leads | 是 | 是 | 否 | 是 | 否 | | 活動 | 是 | 是 | 否 | 是 | 否 | | customobjects | 是 | 是 | 否 | 是 | 否 | **來源 (非同步) 支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | leads | 是 | 否 | 否 | 是 | 是 | | 活動 | 是 | 否 | 否 | 是 | 否 | | customobjects | 是 | 否 | 否 | 是 | 是 | **範例**： ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v2", "INSTANCE_URL": "https://539-t**-6**.mktorest.com" } ``` **Adobe Marketo Engage 實體和欄位詳細資訊**： **具有靜態中繼資料的實體**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) **具有動態中繼資料的實體**： 對於下列實體，Adobe Marketo Engage 會提供端點來動態擷取中繼資料，以便在每個實體的資料類型層級擷取運算子支援。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-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`：分區數目。 下表說明實體分區欄位支援詳細資訊： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) 範例： ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2024-07-01T00:00:00.000Z" "UPPER_BOUND": "2024-07-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # 寫入 Adobe Marketo Engage 實體 **先決條件** + 您想要寫入的 Adobe Marketo 物件。您將需要物件名稱，例如 `leads` 或 `customobjects`。 + Adobe Marketo 連接器支援三種寫入操作： + INSERT + UPSERT (更新插入) + UPDATE + 對於 `UPSERT`和 `UPDATE` 寫入操作，您必須提供 `ID_FIELD_NAMES` 選項，以指定記錄的 ID 欄位。使用 `leads` 實體時，使用 `email` 作為 `ID_FIELD_NAMES` 進行 `UPSERT` 操作，使用 `id` 進行 `UPDATE` 操作。對於 `customobjects` 實體，使用 `marketoGUID` 作為 `ID_FIELD_NAMES` 同時進行 `UPDATE` 和 `UPSERT` 操作。 **目的地支援的實體 (同步)** | 實體名稱 | 將支援為目的地連接器 | 可以插入 | 可以更新 | 可以更新插入 | | --- | --- | --- | --- | --- | | leads | 是 | 是 (大量) | 是 (大量) | 是 (大量) | | customobjects | 是 | 是 (大量) | 是 (大量) | 是 (大量) | **範例**： **INSERT 操作：** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "INSERT" } ``` **UPDATE 操作：** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "UPDATE", "ID_FIELD_NAMES": "id" } ``` **注意** 對於 `leads` 和 `customobjects` 實體，Adobe Marketo 會提供端點來動態擷取中繼資料，以便從 Marketo API 回應中識別可寫入欄位。 # Adobe Marketo Engage 連線選項 以下是 Adobe Marketo Engage 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Adobe Marketo Engage 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Adobe Marketo Engage Rest API 版本。例如：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。用於讀取。要讀取的分區數目。 + `TRANSFER_MODE`(String) - 預設：SYNC。用於非同步讀取。 + `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT、UPDATE、UPSERT。 + `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 和 UPSERT 的必要項目。 # Adobe Marketo Engage 連接器的限制和備註 以下是 Adobe Marketo Engage 連接器的限制或備註： + 'sinceDatetime' 和 'activityTypeId' 是 Sync Activities 實體的必要篩選條件參數。 + 訂閱每天分配 5 萬個 API 呼叫 (每天在中部標準時間上午 12：00 重設)。您可以在 Adobe Marketo Engage 訂閱中購買額外的每日容量。如需參考，請參閱 [Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api)。 + 日期範圍篩選條件 (`createdAt` 或 `updatedAt`) 的時間範圍上限為 31 天。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 在任何指定時間內，訂閱在佇列中最多分配 10 個大量擷取任務。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 依預設，擷取任務每天限制為 500 MB (每天在中部標準時間上午 12：00 重設)。您可以在 Adobe Marketo Engage 訂閱中購買額外的每日容量。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 並行匯出任務的數目上限為 2。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 已排入佇列的匯出任務數目上限 (包括目前匯出的任務) 為 10。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 允許的最大檔案大小為 1 GB，可從大量任務中擷取。 + 建立非同步任務後，檔案將保留 7 天才到期。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + `createdAt` 或 `updatedAt` 是 Async Leads 實體的必要篩選條件參數。 + `createdAt` 是 Async Activities 實體的必要篩選條件參數。 + `updatedAt` 是 Async Custom Object 實體的必要篩選條件參數。 + 使用 AWS Glue SaaS 連接器時，使用者無法識別在寫入目的地 SaaS 平台期間發生部分故障時，哪些特定記錄失敗。 + 使用同步寫入操作時，輸入檔案中具有 null 值的任何欄位都會自動捨棄，而不會傳送至 SaaS 平台。 + 您可以在批次中建立或更新最多 300 個記錄以進行同步寫入。 如需詳細資訊，請參閱 [Adobe Marketo Engage 整合最佳實務](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/marketo-integration-best-practices)和[大量擷取](https://https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-activity-extract)。 # 在 AWS Glue Studio 中連線至 Amazon Redshift **注意** 您可以使用 AWS Glue 讓 Spark 從 以外的 Amazon Redshift 資料庫中讀取和寫入資料表AWS Glue Studio。若要以程式設計方式設定 Amazon Redshift AWS Glue任務，請參閱 [Redshift 連線](aws-glue-programming-etl-connect-redshift-home.md)。 AWS Glue 提供 的內建支援 Amazon Redshift。 AWS Glue Studio提供視覺化界面來連線 Amazon Redshift、撰寫資料整合任務，以及在無AWS Glue Studio伺服器 Spark 執行時間上執行任務。 **Topics** + [建立 Amazon Redshift 連線](creating-redshift-connection.md) + [建立 Amazon Redshift 來源節點](creating-redshift-source-node.md) + [建立 Amazon Redshift 目標節點](creating-redshift-target-node.md) + [進階選項](creating-redshift-connection-advanced-options.md) # 建立 Amazon Redshift 連線 ## 需要的許可 需要額外的許可才能使用 Amazon Redshift 叢集和無 Amazon Redshift 伺服器環境。如需有關如何向 ETL 任務新增許可的詳細資訊，請參閱 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。 + redshift:DescribeClusters + redshift-serverless:ListWorkgroups + redshift-serverless:ListNamespaces ## 概觀 新增 Amazon Redshift 連線時，您可以選擇現有的 Amazon Redshift 連線，或在 中新增**資料來源 - Redshift** 節點時建立新的連線AWS Glue Studio。 AWS Glue 同時支援 Amazon Redshift 叢集和無 Amazon Redshift 伺服器環境。當您建立連線時，無 Amazon Redshift 伺服器環境會在連線選項旁顯示**無伺服器**標籤。 如需如何建立 Amazon Redshift 連線的詳細資訊，請參閱[往返移動資料 Amazon Redshift](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-redshift.html#aws-glue-programming-etl-redshift-using)。 # 建立 Amazon Redshift 來源節點 ## 需要的許可 AWS Glue Studio 使用 Amazon Redshift 資料來源的任務需要額外的許可。如需有關如何向 ETL 任務新增許可的詳細資訊，請參閱 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。 需要下列許可才能使用 Amazon Redshift 連線。 + redshift-data:ListSchemas + redshift-data:ListTables + redshift-data:DescribeTable + redshift-data:ExecuteStatement + redshift-data:DescribeStatement + redshift-data:GetStatementResult ## 新增 Amazon Redshift 資料來源 **若要新增**資料來源 – Amazon Redshift** 節點：** 1. 選擇 Amazon Redshift 存取類型： + 直接資料連線 (建議)：如果您要直接存取 Amazon Redshift 資料，請選擇此選項。這是建議的選項，也是預設選項。 + Data Catalog tables：如果您有要使用的資料目錄資料表，請選擇此選項。 1. 如果您選擇直接資料連線，請選擇 Amazon Redshift 資料來源的連線。假設連線已存在，您可以從現有的連線中進行選擇。如果您需要建立連線，請選擇**建立 Redshift 連線**。如需詳細資訊，請參閱 [Overview of using connectors and connections ](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。隨即會顯示連線的相關資訊，包括 URL、安全群組、子網路、可用區域、說明，以及建立的 (UTC) 和上次更新的 (UTC) 時間戳記。 1. 選擇 Amazon Redshift 來源選項： + **選擇單一資料表** – 這是包含您要從單一資料表存取之資料的 Amazon Redshift 資料表。 + **輸入自訂查詢**：可讓您根據自訂查詢從多個 Amazon Redshift 資料表存取資料集。 1. 如果您選擇單一資料表，請選擇 Amazon Redshift 結構描述。可供選擇的結構描述清單由選取的資料表決定。 或者，選擇**輸入自訂查詢**。選擇此選項可從多個 Amazon Redshift 資料表存取自訂資料集。當您選擇此選項時，請輸入 Amazon Redshift 查詢。 連線至無 Amazon Redshift 伺服器環境時，請將下列許可新增至自訂查詢： ``` GRANT SELECT ON ALL TABLES IN TO PUBLIC ``` 您可以選擇**推論結構描述**，根據您輸入的查詢讀取結構描述。您也可以選擇**開啟 Redshift 查詢編輯器**來輸入 Amazon Redshift 查詢。如需詳細資訊，請參閱 [Querying a database using the query editor](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor.html)。 1. 在**效能和安全性**中，選擇 Amazon S3 暫存目錄和 IAM 角色。 + **Amazon S3 暫存目錄**：選擇暫存資料的 Amazon S3 位置。 + **IAM 角色**：選擇可寫入您選取之 Amazon S3 位置的 IAM 角色。 1. 在**自訂 Redshift 參數 - 選用**中，輸入參數和值。 # 建立 Amazon Redshift 目標節點 ## 需要的許可 AWS Glue Studio 使用 Amazon Redshift 資料目標的任務需要額外的許可。如需有關如何向 ETL 任務新增許可的詳細資訊，請參閱 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。 需要下列許可才能使用 Amazon Redshift 連線。 + redshift-data:ListSchemas + redshift-data:ListTables ## 新增 Amazon Redshift 目標節點 **若要建立 Amazon Redshift 目標節點：** 1. 選擇現有的 Amazon Redshift 資料表做為目標，或輸入新的資料表名稱。 1. 如果您使用**資料目標 - Redshift** 目標節點，您可從以下選項中選擇： + **附加**：如果資料表已存在，請將所有新資料以插入方式傾印到資料表中。如果資料表不存在，請建立資料表，然後插入所有新資料。 此外，如果您要更新 (UPSERT) 目標資料表中的現有記錄，請勾選此方塊。資料表必須先存在，否則操作將會失敗。 + **合併**：AWS Glue 會根據您指定的條件，將資料更新或附加至目標資料表。 **注意** 若要在 中使用合併動作AWS Glue，您必須啟用 Amazon Redshift 合併功能。如需如何為 Amazon Redshift 執行個體啟用合併的指示，請參閱 [MERGE （預覽）。 ](https://docs.aws.amazon.com/redshift/latest/dg/r_MERGE.html) 選擇選項： + **選擇索引鍵和簡單動作**：選擇要用作來源資料與目標資料集之間相符索引鍵的資料欄。 符合時指定下列選項： + 使用來源中的資料更新目標資料集中的記錄。 + 刪除目標資料集中的記錄。 不符合時指定下列選項： + 將來源資料作為新列插入目標資料集。 + 什麼都不做。 + **輸入自訂 MERGE 陳述式**：然後您可以選擇**驗證 Merge 陳述式**，以驗證陳述式是有效還是無效。 + **截斷**：如果資料表已存在，請先清除目標資料表的內容來截斷資料表資料。如果截斷成功，則插入所有資料。如果資料表不存在，請建立資料表並插入所有資料。如果截斷未成功，則操作將會失敗。 + **刪除**：如果資料表已存在，請刪除資料表中繼資料和資料。如果刪除成功，則插入所有資料。如果資料表不存在，請建立資料表並插入所有資料。如果刪除未成功，則操作將會失敗。 + **建立**：使用預設名稱建立新資料表。如果資料表名稱已存在，則建立一個新資料表，並在名稱後加上名稱後置詞 `job_datetime` 以確保唯一性。這會將所有資料插入新資料表中。如果資料表存在，則最終的資料表名稱將會附加後置詞。如果資料表不存在，則會建立資料表。無論哪種情況，都會建立新資料表。 # 進階選項 請參閱[在 上使用 Amazon Redshift Spark 連接器AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-redshift.html#aws-glue-programming-etl-redshift-using)。 # 連線至 Asana Asana 是一種以雲端為基礎的團隊協作解決方案，可協助團隊組織、規劃和完成任務和專案。如果您是 Asana 使用者，您的帳戶會包含有關工作區、專案、任務、團隊等的資料。您可以將資料從 Asana 傳輸到特定 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Asana](asana-support.md) + [包含用於建立和使用連線的 API 操作的政策](asana-configuring-iam-permissions.md) + [設定 Asana](asana-configuring.md) + [設定 Asana 連線](asana-configuring-connections.md) + [從 Asana 實體中讀取](asana-reading-from-entities.md) + [Asana 連線選項](asana-connection-options.md) + [建立 Asana 帳戶](asana-create-account.md) + [限制](asana-connector-limitations.md) # AWS Glue 支援 Asana AWS Glue 支援 Asana，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Asana 查詢資料。 **支援作為目標？** 否。 **支援的 Asana API 版本** 1.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Asana 您必須先符合下列要求，才能使用 從 Asana AWS Glue 轉移： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Asana 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Asana 帳戶](asana-create-account.md)。 + 您必須使用 服務存取建立 AWS 帳戶 AWS Glue。 + 確保您已在 Asana 帳戶中建立下列其中一個資源： + 支援 `OAuth 2.0` 身分驗證的開發人員應用程式。如需更多指示，請參閱 Asana 開發人員文件中的 [OAuth](https://developers.asana.com/docs/oauth)。或者，請參閱 [建立 Asana 帳戶](asana-create-account.md)。 + 個人存取字符。如需詳細資訊，請參閱 Asana 開發人員文件中的「個人存取字符 [https://developers.asana.com/docs/personal-access-token](https://developers.asana.com/docs/personal-access-token)」。 如果您符合這些要求，就可以 AWS Glue 連線到 Adobe Analytics 帳戶。對於一般連線，不需要在 Adobe Analytics 中執行任何其他操作。 # 設定 Asana 連線 Asana 支援 `OAuth2` 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。使用者可以選擇在 Asana 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Asana 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需有關為 `AUTHORIZATION_CODE OAuth` 流程建立連線應用程式的公有 Asana 文件，請參閱 [Asana API](https://developers.asana.com/docs/oauth)。 若要設定 Asana 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 + **注意** 必須在 AWS Glue中建立連線機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Asana。 1. 提供 Asana 環境。 1. 選取 AWS Glue 可擔任的 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`。 # 從 Asana 實體中讀取 **先決條件** 您想要從中讀取的 Asana 物件。請參閱以下支援的實體表格，以檢查可用實體。 **來源的支援實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 工作區 | 否 | 是 | 否 | 是 | 否 | | Tag | 否 | 是 | 否 | 是 | 否 | | 使用者 | 否 | 是 | 否 | 是 | 否 | | 產品組合 | 否 | 是 | 否 | 是 | 否 | | 團隊 | 否 | 是 | 否 | 是 | 否 | | 專案 | 是 | 是 | 否 | 是 | 否 | | 區段 | 否 | 是 | 否 | 是 | 否 | | 任務 | 是 | 否 | 否 | 是 | 是 | | 目標 | 是 | 是 | 否 | 是 | 否 | | AuditLogEvent | 是 | 是 | 否 | 是 | 否 | | 狀態更新 | 是 | 是 | 否 | 是 | 否 | | 自訂欄位 | 否 | 是 | 否 | 是 | 否 | | 專案簡介 | 是 | 否 | 否 | 是 | 是 | **範例** ``` read_read = glueContext.create_dynamic_frame.from_options( connection_type="Asana", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "task/workspace:xxxx", "API_VERSION": "1.0", "PARTITION_FIELD": "created_at", "LOWER_BOUND": "2024-02-05T14:09:30.115Z", "UPPER_BOUND": "2024-06-07T13:30:00.134Z", "NUM_PARTITIONS": "3" } ``` **Asana 實體和欄位詳細資訊** + [工作區](https://developers.asana.com/docs/workspaces) + [標籤](https://developers.asana.com/docs/tags) + [使用者](https://developers.asana.com/docs/users) + [產品組合](https://developers.asana.com/docs/portfolios) + [團隊](https://developers.asana.com/docs/teams) + [專案](https://developers.asana.com/docs/get-all-projects-in-a-workspace) + [區段](https://developers.asana.com/docs/get-sections-in-a-project) + [任務](https://developers.asana.com/docs/search-tasks-in-a-workspace) + [目標](https://developers.asana.com/docs/get-goals) + [AuditLogEvent](https://developers.asana.com/docs/audit-log-api) + [狀態更新](https://developers.asana.com/reference/status-updates) + [自訂欄位](https://developers.asana.com/reference/custom-fields) + [專案簡介](https://developers.asana.com/reference/project-briefs) **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`2024-06-07T13:30:00.134Z`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示。 | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 任務 | created\$1at | DateTime | | 任務 | modified\$1at | DateTime | **範例** ``` read_read = glueContext.create_dynamic_frame.from_options( connection_type="Asana", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "task/workspace:xxxx", "API_VERSION": "1.0", "PARTITION_FIELD": "created_at", "LOWER_BOUND": "2024-02-05T14:09:30.115Z", "UPPER_BOUND": "2024-06-07T13:30:00.134Z", "NUM_PARTITIONS": "3" } ``` # Asana 連線選項 以下是 Asana 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Asana 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您要使用的 Asana Rest API 版本。例如：1.0。 + `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。用於讀取。要讀取的分區數目。 # 建立 Asana 帳戶 1. 註冊 [Asana 帳戶](https://asana.com/create-account)，然後選擇**註冊**。 1. 登入後，系統會將您重新導向至[帳戶設定](https://app.asana.com/0/account_setup)頁面。請完成下列步驟： + 檢閱帳戶設定表單。 + 填寫所有相關的詳細資訊以建立您的 Asana 帳戶。 + 再次檢查資訊的準確性。 1. 選擇**建立帳戶**或**提交** (確切按鈕文字可能會有所不同) 以完成您的帳戶設定。 **在適用於 `OAuth2.0` 的 Asana 中建立應用程式** 1. 使用您的 [Asana 客戶憑證](https://app.asana.com/-/login)登入 Asana 帳戶。 1. 選擇右上角的使用者設定檔圖示，然後從下拉式功能表中選取**我的設定**。 1. 選取**應用程式**索引標籤，然後選取**管理開發人員應用程式**。 1. 選取**建立新應用程式**，然後輸入相關詳細資訊。 1. 選擇**建立應用程式**。 1. 在**我的應用程式**頁面上： 1. 選取 **OAuth**，然後在**應用程式憑證**區段中，記下您的用戶端 ID 和用戶端機密。 1. 在**重新導向 URL** 區段中，新增必要的重新導向 URL。 **注意** 使用此格式輸入重新導向 URI：`https://{aws-region-code}.console.aws.amazon.com/gluestudio/oauth`。範例：對於美國東部 (維吉尼亞北部)，使用：`https://us-east-1.console.aws.amazon.com/gluestudio/oauth` **在適用於 `PAT` 字符的 Asana 中建立應用程式** 1. 使用您的 [Asana 客戶憑證](https://app.asana.com/-/login)登入 Asana 帳戶。 1. 選擇右上角的使用者設定檔圖示，然後從下拉式功能表中選取**我的設定檔設定**。 1. 選取**應用程式**索引標籤，然後選取**服務帳戶**。 1. 選取**建立新應用程式**，然後輸入相關詳細資訊。 1. 選擇**新增服務帳戶**。 1. 下一頁會顯示您的字符、複製字符並安全地儲存字符。 **重要** 此字符只會顯示一次。確保您複製並安全地儲存其。 # 限制 以下是 Asana 連接器的限制： + 企業網域中的服務帳戶只能存取稽核日誌 API 端點。存取這些端點需要使用服務帳戶的個人存取字符進行身分驗證。 + 只有具有高級計畫或更新版本的使用者帳戶才能存取目標實體。 + `Audit Log Event Entity` – 在連接器中，`start_at` 和 `end_at` 欄位會合併為單一欄位 "start\$1end\$1at"，以支援篩選和增量傳輸。 + `Date` 欄位無法支援分區，即使其支援 greater-than-or-equal-to 運算子和 less-than-or-equal-to 運算子。案例：建立一個任務，其中 `partitionField` 為 `due_on` (資料類型：date)、`lowerBound` 為 `2019-09-14`、`upperBound` 為 `2019-09-16`、`numPartition` 為 `2`。端點 URL 的篩選條件部分建立方式如下： + partition1：due\$1on.before=2019-09-14&due\$1on.after=2019-09-14 + partition2：due\$1on.before=2019-09-15&due\$1on.after=2019-09-15 輸出： + 在 partition1 中，我們取得 due\$1date 為 2019-09-14 和 2019-09-15 的資料 + 在 partition2 中，我們取得與 partition1 中 due\$1date 為 2019-09-15 相同的資料以及其他資料，從而導致資料重複。 + 由於從 SaaS 終端擲回不良請求錯誤，因此無法在相同的欄位中支援篩選和分區。 + 任務實體在篩選條件中至少需要 1 個欄位。Asana 有一項限制，在未根據以時間為基礎的欄位排序記錄的情況下，無法識別分頁。因此，Created\$1at 欄位會與分頁搭配使用，以區分下一組記錄。Created\$1at 欄位在篩選條件中標記為必要，如果未提供，預設值為 2000-01-01T00:00:00Z。如需分頁的詳細資訊，請參閱[工作區中的任務](https://developers.asana.com/reference/searchtasksforworkspace)。 # 在 AWS Glue Studio 中連線至 Azure Cosmos DB AWS Glue 會提供 Azure Cosmos DB 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 Azure Cosmos DB for NoSQL、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 **Topics** + [建立 Azure Cosmos DB 連線](creating-azurecosmos-connection.md) + [建立 Azure Cosmos DB 來源節點](creating-azurecosmos-source-node.md) + [建立 Azure Cosmos DB 目標節點](creating-azurecosmos-target-node.md) + [進階選項](#creating-azurecosmos-connection-advanced-options) # 建立 Azure Cosmos DB 連線 **先決條件：** + 在 Azure 中，您將需要識別或產生 Azure Cosmos 資料庫金鑰以供 AWS Glue使用`cosmosKey`。如需詳細資訊，請參閱《Azure 文件》中的[安全存取 Azure Cosmos DB 中的資料](https://learn.microsoft.com/en-us/azure/cosmos-db/secure-access-to-data?tabs=using-primary-key)。 **設定連至 Azure Cosmos DB 的連線：** 1. 在 中 AWS Secrets Manager，使用您的 Azure Cosmos 資料庫金鑰建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *cosmosKey* 值來建立 `spark.cosmos.accountKey` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便未來在 AWS Glue中使用。 + 選取**連線類型**時，請選取 Azure Cosmos DB。 + 選取 **AWS 機密**時，請提供 *secretName*。 # 建立 Azure Cosmos DB 來源節點 ## 必要先決條件 + AWS Glue Azure Cosmos 資料庫連線，使用 AWS Secrets Manager 秘密設定，如上節所述：[建立 Azure Cosmos DB 連線](creating-azurecosmos-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要讀取的 Azure Cosmos DB for NoSQL 容器。您將需要容器的識別資訊。 An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。 ## 新增 Azure Cosmos DB 資料來源 **新增**資料來源 – Azure Cosmos DB** 節點：** 1. 選擇 Azure Cosmos DB 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Azure Cosmos DB 連線**。如需詳細資訊，請參閱前一 [建立 Azure Cosmos DB 連線](creating-azurecosmos-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇 **Cosmos DB 資料庫名稱**：提供您想要讀取的資料庫名稱 *cosmosDBName*。 1. 選擇 **Azure Cosmos 資料庫容器**：提供您想要讀取的容器名稱 *cosmosContainerName*。 1. 或者，選擇 **Azure Cosmos DB 自訂查詢**：提供 SQL SELECT 查詢，以便從 Azure Cosmos DB 擷取特定資訊。 1. 在**自訂 Azure Cosmos 屬性**中，視需要輸入參數和值。 # 建立 Azure Cosmos DB 目標節點 ## 必要先決條件 + AWS Glue Azure Cosmos 資料庫連線，使用 AWS Secrets Manager 秘密設定，如上節所述：[建立 Azure Cosmos DB 連線](creating-azurecosmos-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 Azure Cosmos DB 資料表。您將需要容器的識別資訊。**您必須先建立容器，再呼叫連線方法。** An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。 ## 新增 Azure Cosmos DB 資料目標 **新增**資料目標 – Azure Cosmos DB** 節點：** 1. 選擇 Azure Cosmos DB 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Azure Cosmos DB 連線**。如需詳細資訊，請參閱前一 [建立 Azure Cosmos DB 連線](creating-azurecosmos-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇 **Cosmos DB 資料庫名稱**：提供您想要讀取的資料庫名稱 *cosmosDBName*。 1. 選擇 **Azure Cosmos 資料庫容器**：提供您想要讀取的容器名稱 *cosmosContainerName*。 1. 在**自訂 Azure Cosmos 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 Azure Cosmos DB 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[Azure Cosmos DB 連線](aws-glue-programming-etl-connect-azurecosmos-home.md)。 # 在 AWS Glue Studio 中連線至 Azure SQL AWS Glue 會提供 Azure SQL 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 Azure SQL、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 **Topics** + [建立 Azure SQL 連線](creating-azuresql-connection.md) + [建立 Azure SQL 來源節點](creating-azuresql-source-node.md) + [建立 Azure SQL 目標節點](creating-azuresql-target-node.md) + [進階選項](#creating-azuresql-connection-advanced-options) # 建立 Azure SQL 連線 若要從 連線至 Azure SQL AWS Glue，您需要在 AWS Secrets Manager 秘密中建立並存放 Azure SQL 登入資料，然後將該秘密與 Azure SQL AWS Glue 連線建立關聯。 **設定連至 Azure SQL 的連線：** 1. 在 中 AWS Secrets Manager，使用您的 Azure SQL 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *azuresqlUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *azuresqlPassword* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便未來在 AWS Glue中使用。 + 選取**連線類型**時，請選取 Azure SQL。 + 提供 **Azure SQL URL**時，請提供 JDBC 端點 URL。 此 URL 必須採用下列格式：`jdbc:sqlserver://databaseServerName:databasePort;databaseName=azuresqlDBname;`。 AWS Glue 需要下列 URL 屬性： + `databaseName`：要連線之 Azure SQL 的預設資料庫。 如需有關 Azure SQL 受控執行個體之 JDBC URL 的詳細資訊，請參閱 [Microsoft 文件](https://learn.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=azuresqldb-mi-current)。 + 選取 **AWS 機密**時，請提供 *secretName*。 # 建立 Azure SQL 來源節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue Azure SQL 連線，如上節所述：[建立 Azure SQL 連線](creating-azuresql-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要讀取的 Azure SQL 資料表 *tableName*。 Azure SQL 資料表由資料庫、結構描述及資料表名稱識別。連線至 Azure SQL 時，您必須提供資料庫名稱和資料表名稱。如果結構描述不是預設的 "public"，您也必須提供結構描述。資料庫會透過 *connectionName* 中的 URL 屬性提供，而結構描述和資料表名稱會透過 `dbtable` 提供。 ## 新增 Azure SQL 資料來源 **新增**資料來源 – Azure SQL** 節點：** 1. 選擇 Azure SQL 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Azure SQL 連線**。如需詳細資訊，請參閱前一 [建立 Azure SQL 連線](creating-azuresql-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇 **Azure SQL 來源**選項： + **選擇單一資料表**：從單一資料表存取所有資料。 + **輸入自訂查詢**：根據自訂查詢從多個資料表存取資料集。 1. 如果您選擇單一資料表，請輸入 *tableName*。 如果您選擇**輸入自訂查詢**，請輸入 TransactSQL SELECT 查詢。 1. 在**自訂 Azure SQL 屬性**中，視需要輸入參數和值。 # 建立 Azure SQL 目標節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue Azure SQL 連線，如上節所述：[建立 Azure SQL 連線](creating-azuresql-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 Azure SQL 資料表 *tableName*。 Azure SQL 資料表由資料庫、結構描述及資料表名稱識別。連線至 Azure SQL 時，您必須提供資料庫名稱和資料表名稱。如果結構描述不是預設的 "public"，您也必須提供結構描述。資料庫會透過 *connectionName* 中的 URL 屬性提供，而結構描述和資料表名稱會透過 `dbtable` 提供。 ## 新增 Azure SQL 資料目標 **新增**資料目標 – Azure SQL** 節點：** 1. 選擇 Azure SQL 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Azure SQL 連線**。如需詳細資訊，請參閱前一 [建立 Azure SQL 連線](creating-azuresql-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 透過提供 *tableName* 來設定**資料表名稱**。 1. 在**自訂 Azure SQL 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 Azure SQL 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[Azure SQL 連線](aws-glue-programming-etl-connect-azuresql-home.md)。 # 連線至 Blackbaud Raiser's Edge NXT Blackbaud Raiser's Edge NXT 是全方位的雲端型籌款和捐贈者管理軟體解決方案，專為非營利組織和整個社會公益社群而打造。此連接器建置在 Blackbaud Raiser’s Edge NXT 的 SKY API 之上，並提供操作為協助管理 Raisers Edge NXT 內的實體。 **Topics** + [AWS Glue 支援 Blackbaud 提升器的 Edge NXT](blackbaud-support.md) + [包含用於建立和使用連線的 API 操作的政策](blackbaud-configuring-iam-permissions.md) + [設定 Blackbaud Raiser's Edge NXT](blackbaud-configuring.md) + [設定 Blackbaud Raiser's Edge NXT 連線](blackbaud-configuring-connections.md) + [從 Blackbaud Raiser's Edge NXT 實體中讀取](blackbaud-reading-from-entities.md) + [Blackbaud Raiser's Edge NXT 連線選項](blackbaud-connection-options.md) + [BBlackbaud Raiser's Edge NXT 限制](blackbaud-connection-limitations.md) # AWS Glue 支援 Blackbaud 提升器的 Edge NXT AWS Glue 支援 Blackbaud 提升器的 Edge NXT，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Blackbaud Raiser 的 Edge NXT 查詢資料。 **支援作為目標？** 否。 **支援的 Blackbaud Raiser's Edge NXT API 版本** 支援下列 Blackbaud Raiser's Edge NXT 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 主控台的使用者。 # 設定 Blackbaud Raiser's Edge NXT 您必須先符合下列要求，才能使用 從 Blackbaud Raiser 的 Edge NXT AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您有 Blackbaud Raiser's Edge NXT 帳戶。 + 您已在 Blackbaud Raiser's Edge NXT 帳戶中產生存取字符，並指派適當的讀取/寫入範圍來存取 API。如需詳細資訊，請參閱[授權](https://developer.blackbaud.com/skyapi/docs/authorization)。 如果您符合這些要求，就可以 AWS Glue 連線到 Blackbaud 提出者的 Edge NXT 帳戶。 # 設定 Blackbaud Raiser's Edge NXT 連線 Blackbaud Raiser's Edge NXT 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 AWS Glue 主控台會將使用者重新導向至 Blackbaud Raiser 的 Edge NXT，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Blackbaud Raiser 的 Edge NXT 執行個體。 + 使用者可以選擇在 Blackbaud Raiser 的 Edge NXT 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID、訂閱金鑰和執行個體 URL。在此案例中，它們仍會重新導向至 Blackbaud 提出者的 Edge NXT，以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 Blackbaud Raiser’s Edge NXT 文件，請參閱[授權](https://developer.blackbaud.com/skyapi/docs/authorization)。 若要設定 Blackbaud Raiser's Edge NXT 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式 – 機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式 API 金鑰。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**資料來源**時，選取 Blackbaud Raiser's Edge NXT。 1. 提供您要連線的 Blackbaud Raiser's Edge NXT 帳戶的 `INSTANCE_URL`。 1. 提供使用者受管用戶端應用程式 `clientId`。 1. 提供與您的帳戶關聯的訂閱金鑰。 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`。 # 從 Blackbaud Raiser's Edge NXT 實體中讀取 **必要條件** 您想要讀取的 Blackbaud Raiser's Edge NXT 物件。將需要物件名稱。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 組成部分地址 | 是 | 是 | 否 | 是 | 是 | | 組成部分教育 | 是 | 是 | 否 | 是 | 是 | | 組成部分電子郵件地址 | 是 | 是 | 否 | 是 | 是 | | 組成部分電話 | 是 | 是 | 否 | 是 | 是 | | 組成部分備註 | 是 | 是 | 否 | 是 | 是 | | 組成部分關係 | 是 | 是 | 否 | 是 | 是 | | 組成部分線上存在 | 是 | 是 | 否 | 是 | 是 | | 機會 | 是 | 是 | 否 | 是 | 是 | | 吸引力 | 是 | 是 | 否 | 是 | 是 | | 行銷活動 | 是 | 是 | 否 | 是 | 是 | | 資金 | 是 | 是 | 否 | 是 | 是 | | 套件 | 是 | 是 | 否 | 是 | 是 | | 禮物批次 | 是 | 是 | 否 | 是 | 否 | | 事件參與者 | 是 | 是 | 是 | 是 | 是 | | 組成部分籌款者指派 | 否 | 否 | 否 | 是 | 否 | | 禮物 | 是 | 是 | 是 | 是 | 是 | | 成員資格 | 是 | 是 | 否 | 是 | 是 | | Action | 是 | 是 | 否 | 是 | 否 | | 組成部分 | 是 | 是 | 是 | 是 | 是 | | 組成部分商品 | 是 | 是 | 否 | 是 | 是 | | 事件 | 是 | 是 | 是 | 是 | 是 | | 禮物自訂欄位 | 是 | 是 | 否 | 是 | 是 | **範例**： ``` blackbaud_read = glueContext.create_dynamic_frame.from_options( connection_type="BLACKBAUD", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1", "SUBSCRIPTION_KEY": } ``` ## Blackbaud Raiser's Edge NXT 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [Action](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Action) + [組成部分](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Constituent) + [組成部分地址](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Address) + [組成部分成員資格](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Membership) + [組成部分籌款者指派](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#FundraiserAssignment) + [組成部分教育](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Education) + [組成部分電子郵件地址](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#EmailAddress) + [組成部分電話](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Phone) + [組成部分備註](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Note) + [組成部分線上存在](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#OnlinePresence) + [組成部分關係](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Relationship) + [事件](https://developer.blackbaud.com/skyapi/renxt/event/entities#Event) + [事件參與者](https://developer.blackbaud.com/skyapi/renxt/event/entities#Participant) + [吸引力](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Appeal) + [行銷活動](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Campaign) + [資金](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Fund) + [套件](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Package) + [禮物](https://developer.blackbaud.com/skyapi/renxt/gift/entities#Gift) + [禮物自訂欄位](https://developer.blackbaud.com/skyapi/renxt/gift/entities#CustomField) + [禮物批次](https://developer.blackbaud.com/skyapi/renxt/gift-batch/entities#GiftBatch) + [機會](https://developer.blackbaud.com/skyapi/renxt/opportunity/entities#Opportunity) + [組成部分程式碼](https://developer.sky.blackbaud.com/api#api=56b76470069a0509c8f1c5b3) **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型，DateTime 資料類型會轉換為 Timestamp。 ## 分區查詢 **欄位型分區**： Blackbaud Raiser's Edge NXT 不支援欄位型分區或記錄型分區。 **以記錄型分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 在記錄型分區中，存在的記錄總數會從 Blackbaud Raiser's Edge NXT API 查詢，並除以提供的 `NUM_PARTITIONS` 數目。然後，每個子查詢都會同時擷取產生的記錄數目。 + `NUM_PARTITIONS`：分區數目。 範例： ``` blackbaud_read = glueContext.create_dynamic_frame.from_options( connection_type="BLACKBAUD", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1", "NUM_PARTITIONS": "2", "SUBSCRIPTION_KEY": } ``` # Blackbaud Raiser's Edge NXT 連線選項 以下是 Blackbaud Raiser's Edge NXT 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Blackbaud Raiser's Edge NXT 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Blackbaud Raiser's Edge NXT Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。範例值：10。 + `SUBSCRIPTION_KEY`(String) - (必要) 預設：空。用於讀取。與開發人員帳戶關聯的訂閱金鑰。 # BBlackbaud Raiser's Edge NXT 限制 以下是 Blackbaud Raiser's Edge NXT 的限制或備註： + SaaS 僅支援 `EQUAL_TO` 運算子，該運算子會傳回在指定日期或之後建立或修改的結果。此外，"id" 欄位是字串資料類型。也不會識別不可為 Null 的欄位。因此，不支援欄位型分區。 + 只有具有每日、每月和每週頻率的 `Event` 實體才支援增量提取。 + 組成部分籌款者指派實體最多傳回 20 筆記錄。 + 記錄型分區： + `Action`、`Constituent Fundraiser Assignment` 或 `Gift Batch` 實體不支援。 + 只有 `Event` 和 `Event Participant` 實體支援具有篩選條件述詞的記錄型分區。如果篩選條件述詞與任何其他記錄型支援實體搭配使用，則會擲回例外狀況。 + 在 `Gift Custom Field` 實體中，欄位 'value' 必須與欄位 'category' 結合使用，否則會導致未篩選的回應。因此，為了強制使用者在使用 'value' 欄位進行篩選時插入 'category' 欄位，如果未遵循上述要求，則會擲回例外狀況。 + 所有適用實體的 `date_added` 和 `last_modified` 欄位不支援任何比較運算子。其僅支援 equal to 運算子。此外，沒有可以與上述欄位配對以提供一系列記錄的欄位。因此，這些欄位只能查詢，且不支援增量傳輸。 + `Gift Batch` 實體中的 `added_by` 欄位不會被視為可篩選，因為其可能不會發出正確的結果。 + 在 `Gift` 實體中插入資料時，透過 `/GET Gift List` 端點擷取記錄的延遲約為 30 分鐘。 + 由於資料來源結尾的限制，已捨棄對「禮物」實體的增量傳輸支援。 + 在「機會」實體中，狀態欄位有 10 分鐘的延遲。 + `Fundraiser Assignment` 實體具有 `Constituent` 作為相依實體。連接器最多載入 5,000 ID 以供選擇，以避免回應大小超過允許的承載大小上限。 # 連線至 CircleCI CircleCI 是一種持續整合和持續交付平台。您的 CircleCI 帳戶包含專案、管道、工作流程等相關資料。如果您是 CircleCI 使用者，您可以 AWS Glue 連線到您的 CircleCI 帳戶。然後，您可以在 ETL 任務中使用 CircleCI 作為資料來源。執行這些任務以在 CircleCI AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 CircleCI](circleci-support.md) + [包含用於建立和使用連線的 API 操作的政策](circleci-configuring-iam-permissions.md) + [設定 CircleCI](circleci-configuring.md) + [設定 CircleCI 連線](circleci-configuring-connections.md) + [從 CircleCI 實體讀取](circleci-reading-from-entities.md) + [CircleCI 連線選項](circleci-connection-options.md) + [CircleCI 限制](circleci-connection-limitations.md) # AWS Glue 支援 CircleCI AWS Glue 支援 CircleCI，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 CircleCI 查詢資料。 **支援作為目標？** 否。 **支援的 CircleCI API 版本** 支援下列 CircleCI API 版本： +   v2 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 CircleCI 您必須先符合下列要求，才能使用 從 CircleCI AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有一個 CircleCI 帳戶，其中包含您要傳輸的資料。 + 在您的帳戶的使用者設定中，您已建立個人 API 字符。如需詳細資訊，請參閱[建立個人 API 字符](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token)。 + 您在建立連線 AWS Glue 時提供個人 API 權杖給 。 如果您符合這些要求，就可以 AWS Glue 連線到您的 CircleCI 帳戶。 # 設定 CircleCI 連線 CircleCI 支援自訂身分驗證。 若要設定 CircleCI 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式 – 機密應包含以 `Circle-Token` 作為金鑰的連線應用程式 API 金鑰。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**資料來源**時，選取 CircleCI。 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`。 # 從 CircleCI 實體讀取 **必要條件** 您想要從中讀取的 CircleCI 物件。將需要物件名稱。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | Context | 是 | 否 | 否 | 是 | 否 | | 組織摘要指標 | 是 | 否 | 否 | 是 | 否 | | 管道 | 否 | 否 | 否 | 是 | 否 | | 管道工作流程 | 是 | 否 | 否 | 是 | 否 | | 專案分支 | 是 | 否 | 否 | 是 | 否 | | 專案不穩定的測試 | 否 | 否 | 否 | 是 | 否 | | 專案摘要指標 | 是 | 否 | 否 | 是 | 否 | | Schedule | 否 | 否 | 否 | 是 | 否 | | 工作流程任務時間序列 | 是 | 否 | 否 | 是 | 否 | | 工作流程指標和趨勢 | 是 | 否 | 否 | 是 | 否 | | 工作流程最近執行 | 是 | 否 | 否 | 是 | 否 | | 工作流程摘要指標 | 是 | 否 | 否 | 是 | 否 | | 工作流程測試指標 | 是 | 否 | 否 | 是 | 否 | **範例**： ``` circleci_read = glueContext.create_dynamic_frame.from_options( connection_type="circleci", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "context/e7ea2945-dccb-4205-b673-8391fe1b3a4c", "API_VERSION": "v2" } ``` ## CircleCI 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [內容](https://circleci.com/docs/api/v2/#operation/listContexts) + [專案摘要指標](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowsPageData) + [工作流程任務時間序列](https://circleci.com/docs/api/v2/#operation/getJobTimeseries) + [組織摘要指標](https://circleci.com/docs/api/v2/#operation/getOrgSummaryData) + [專案分支](https://circleci.com/docs/api/v2/#operation/getAllInsightsBranches) + [專案不穩定的測試](https://circleci.com/docs/api/v2/#operation/getFlakyTests) + [工作流程最近執行](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowRuns) + [工作流程摘要指標](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowMetrics) + [工作流程指標和趨勢](https://circleci.com/docs/api/v2/#operation/getWorkflowSummary) + [工作流程測試指標](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowTestMetrics) + [管道](https://circleci.com/docs/api/v2/#operation/listPipelinesForProject) + [管道工作流程](https://circleci.com/docs/api/v2/#operation/listWorkflowsByPipelineId) + [排程](https://circleci.com/docs/api/v2/#operation/listSchedulesForProject) 具有靜態中繼資料的實體： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/circleci-reading-from-entities.html) **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。 **分區查詢** CircleCI 不支援欄位型分區或記錄型分區。 # CircleCI 連線選項 以下是 CircleCI 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。CircleCI 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 CircleCI Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # CircleCI 限制 以下是 CircleCI 的限制或備註： + CircleCI 不支援欄位型分區或記錄型分區。 + 包含 '-' (連字號) 的篩選條件欄位只有當包裝在反引號內時才有效。例如：`workflow-name` = "abc" + 無法支援 GitLab VCS 類型，因為沒有以程式設計方式擷取 GitLab VCS 實體路徑所需的「專案 ID」。 # 連線至 Datadog Datadog 是雲端規模應用程式的監控和分析平台，包括基礎設施、應用程式、服務及工具。 **Topics** + [AWS Glue 支援 Datadog](datadog-support.md) + [包含用於建立和使用連線的 API 操作的政策](datadog-configuring-iam-permissions.md) + [設定 Datadog](datadog-configuring.md) + [設定 Datadog 連線](datadog-configuring-connections.md) + [從 Datadog 實體中讀取](datadog-reading-from-entities.md) + [Datadog 連線選項](datadog-connection-options.md) + [建立 Datadog 帳戶](datadog-create-account.md) + [限制](datadog-connector-limitations.md) # AWS Glue 支援 Datadog AWS Glue 支援 Datadog，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Datadog 查詢資料。 **支援作為目標？** 否。 **支援的 Datadog API 版本** + v1 +   v2 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Datadog 您必須先符合下列要求，才能使用 從 Datadog AWS Glue 傳輸 ： ## 最低需求 + 您具有 DD-API-KEY 和 DD-APPLICATION-KEY 的 Datadog 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Datadog 帳戶](datadog-create-account.md)。 + 您的 Datadog 帳戶具有包含有效授權的 API 存取。 Datadog 支援下列六個 URL。依預設，所有 Datadog API 用戶端都會設定為使用 Datadog US1 站點 API。如果您在 Datadog EU 站點上，則必須使用 Datadog EU 站點的 `DD-API-KEY` 和 `DD-APPLICATION-KEY` 選取 https://api.datadoghq.eu URL 來存取 API。同樣地，對於其他站點，您應使用個別站點的 `DD-API-KEY and DD-APPLICATION-KEY` 來選取個別 URL。 + US1 API URL – [https://api.datadoghq.com](https://api.datadoghq.com)https://api.datadoghq.com + EU API URL – [https://api.datadoghq.eu ](https://api.datadoghq.eu) + US3 API URL – [https://api.us3.datadoghq.com](https://api.us3.datadoghq.com) + US5 API URL – [https://api.us5.datadoghq.com](https://api.us5.datadoghq.com) + S1-FED API URL – [https://api.ddog-gov.com](https://api.ddog-gov.com) + 日本 API URL – [https://api.ap1.datadoghq.com](https://api.ap1.datadoghq.com) 如果您符合這些要求，就可以 AWS Glue 連線到 Datadog 帳戶。 # 設定 Datadog 連線 Datadog 支援自訂身分驗證。以下是設定 Datadog 連線的步驟： 若要設定 Datadog 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 對於客戶管理的連線應用程式，機密應包含以 `API_KEY` 和 `APPLICATION_KEY` 作為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Teradata。 1. 提供您要連線的 Datadog 的 `Instance_Url`。 1. 選取 AWS Glue 可擔任的 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`。 # 從 Datadog 實體中讀取 **先決條件** 您要從中讀取的 Datadog 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 指標時間序列 | 是 | 否 | 否 | 是 | 否 | | 日誌查詢 | 是 | 是 | 是 | 是 | 否 | **範例** ``` Datadog_read = glueContext.create_dynamic_frame.from_options( connection_type="datadog", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "log-queries", "API_VERSION": "v2", "INSTANCE_URL": "https://api.datadoghq.com", "FILTER_PREDICATE": "from = `2023-10-03T09:00:26Z`" } ``` **Datadog 實體和欄位詳細資訊** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/datadog-reading-from-entities.html) # Datadog 連線選項 以下是 Datadog 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Datadog 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您要使用的 Datadog Rest API 版本。`v1` 版本支援 `metrics-timeseries` 實體，而 `v2` 版本支援 `log-queries` 實體。 + `INSTANCE_URL`(String) – (必要) 用於讀取。Datadog 執行個體 URL。Datadog 執行個體 URL 因區域而異。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Datadog 帳戶 1. 前往 [https://www.datadoghq.com/](https://api.datadoghq.com)。 1. 選擇**免費開始使用**。 1. 輸入所需資訊並註冊。 1. 依建議安裝 **Datadog 代理程式安裝程式**。 1. 確保帳戶已向具有作用中 Datadog 訂閱的有效組織 (從可用的清單中) 註冊。 1. 登入 Datadog 帳戶後，將滑鼠的游標移至右上角的您的使用者名稱上，以檢視**金鑰**詳細資訊： 1. 若要取得您的 API 金鑰，請選擇 **API 金鑰**。 1. 若要取得您的應用程式金鑰，請選擇**應用程式金鑰**。 # 限制 以下是 Datadog 連接器的限制： + Datadog 不支援欄位型分區或記錄型分區。 + `from` 是 `Log Queries` 實體的必要篩選條件參數。 + `from_to_date` 和 `query` 是 `Metrics Timeseries` 實體的必要篩選條件參數。 # 連線至 Docusign Monitor Docusign Monitor 透過全天候活動追蹤，協助組織保護其協議。Monitor API 會將此活動追蹤資訊直接提供給現有的安全堆疊或資料視覺化工具，可讓團隊偵測未經授權的活動、調查事件，以及快速回應已驗證的威脅。還提供靈活性，安全團隊需要自訂儀表板和提醒，以符合特定的業務需求。 **Topics** + [AWS Glue 支援 Docusign Monitor](docusign-monitor-support.md) + [包含用於建立和使用連線的 API 操作的政策](docusign-monitor-configuring-iam-permissions.md) + [設定 Docusign Monitor](docusign-monitor-configuring.md) + [設定 Docusign Monitor 連線](docusign-monitor-configuring-connections.md) + [從 Docusign Monitor 實體中讀取](docusign-monitor-reading-from-entities.md) + [Docusign Monitor 連線選項](docusign-monitor-connection-options.md) + [Docusign Monitor 限制](docusign-monitor-connection-limitations.md) # AWS Glue 支援 Docusign Monitor AWS Glue 支援 Docusign Monitor，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Docusign Monitor 查詢資料。 **支援作為目標？** 否。 **支援的 Docusign Monitor API 版本** 支援下列 Docusign Monitor API 版本： + v2.0 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Docusign Monitor 您必須先符合下列要求，才能使用 AWS Glue 將資料從 Docusign Monitor 傳輸到支援的目的地： ## 最低需求 以下是最低要求： + 您具有 Docusign 帳戶，其中您在 Docusign Monitor 中使用 Docusign 軟體產品。 + 在 Docusign 帳戶的開發人員主控台中，您已為 AWS Glue建立 OAuth 2.0 整合應用程式。 此應用程式提供用戶端登入資料，在對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱 Docusign Monitor 文件中的 [OAuth 2.0](https://developers.docusign.com/platform/webhooks/connect/validation-and-security/oauth-connect/)。 如果您符合這些要求，就可以 AWS Glue 連線到 Docusign Monitor 帳戶。 # 設定 Docusign Monitor 連線 Docusign Monitor 支援 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者可以選擇在 Docusign Monitor 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Docusign Monitor 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需為授權碼 OAuth 流程建立連線應用程式的公有 Docusign Monitor 文件，請參閱 [Docusign Connect 的 OAuth](https://developers.docusign.com/platform/webhooks/connect/validation-and-security/oauth-connect/)。 若要設定 Docusign Monitor 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式 – 機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式 API 金鑰。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 在**連線**下，選擇**建立連線**。 1. 選取**資料來源**時，選取 Docusign Monitor。 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. 提供 Docusign Monitor 應用程式的**使用者受管用戶端應用程式 ClientId**。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 Docusign Monitor 實體中讀取 **必要條件** 您要從中讀取的 Docusign Monitor 物件。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 監控資料 | 是 | 是 | 否 | 是 | 否 | **範例**： ``` docusignmonitor_read = glueContext.create_dynamic_frame.from_options( connection_type="docusign_monitor", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "monitoring-data", "API_VERSION": "v2.0" } ``` ## Docusign Monitor 實體和欄位詳細資訊 具有靜態中繼資料的實體： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/docusign-monitor-reading-from-entities.html) **分區查詢** Docusign Monitor 不支援欄位型分區或記錄型分區。 # Docusign Monitor 連線選項 以下是 Docusign Monitor 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Docusign Monitor 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。要使用的 Docusign Monitor Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 # Docusign Monitor 限制 以下是 Docusign Monitor 的限制或備註： + 使用 `cursor` 欄位套用篩選條件時，API 會從指定的日期開始擷取接下來七天的記錄。 + 如果未提供任何篩選條件，API 將從 API 請求的目前日期起擷取前七天的記錄。 + Docusign Monitor 不支援欄位型分區或記錄型分區。 + Docusign Monitor 不支援「排序依據」功能。 # 連線至 Domo Domo 是以雲端為基礎的儀表板工具。透過 Domo 的企業應用程式平台，擴展 Domo 所需的基礎已到位，因此您可以更快地建置自訂解決方案。 **Topics** + [AWS Glue 支援 Domo](domo-support.md) + [包含用於建立和使用連線的 API 操作的政策](domo-configuring-iam-permissions.md) + [設定 Domo](domo-configuring.md) + [設定 Domo 連線](domo-configuring-connections.md) + [從 Domo 實體中讀取](domo-reading-from-entities.md) + [Domo 連線選項](domo-connection-options.md) + [Domo 限制](domo-connection-limitations.md) # AWS Glue 支援 Domo AWS Glue 支援 Domo，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Domo 查詢資料。 **支援作為目標？** 否。 **支援的 Domo API 版本** 支援以下 Domo 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 主控台的使用者。 # 設定 Domo 您必須先符合下列要求，才能使用 AWS Glue 將資料從 Domo 傳輸到支援的目的地： ## 最低需求 以下是最低要求： + 您已為 API 存取啟用 Domo 帳戶。 + 您的 Domo 開發人員帳戶下有一個應用程式，提供用戶端登入資料，當其對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱[建立 Domo 開發人員應用程式](#domo-configuring-creating-developer-app)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Domo 帳戶。 ## 建立 Domo 開發人員應用程式 若要取得用戶端 ID 和用戶端機密，可建立開發人員帳戶。 1. 前往 [Domo 開發人員登入頁面](https://developer.domo.com/manage-clients)。 1. 選擇 **Login (登入)**。 1. 提供網域名稱，然後按一下**繼續**。 1. 將滑鼠游標移至**我的帳戶**上，然後選擇**新用戶端**。 1. 提供名稱和描述，選取範圍 (「資料」)，然後選擇**建立**。 1. 從建立的新用戶端擷取產生的**用戶端 ID **和**用戶端機密**。 # 設定 Domo 連線 Domo 支援 OAuth2 的 CLIENT\$1CREDENTIALS 授權類型。 + 此授權類型視為兩條腿的 OAuth，因為只有用戶端應用程式會向伺服器驗證自己，而不會影響使用者。 + 使用者可以選擇在 Domo 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。 + 如需為授權碼 OAuth 流程建立連線應用程式的公有 Domo 文件，請參閱 [OAuth 身分驗證](https://developer.domo.com/portal/1845fc11bbe5d-api-authentication)。 若要設定 Domo 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含連線應用程式存取字符、`client_id` 和 `client_secret`。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 在**連線**下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Domo。 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`。 # 從 Domo 實體中讀取 **必要條件** 您要從中讀取的 Domo 物件。您需要物件名稱，例如資料集或資料許可政策。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 資料集 | 是 | 是 | 是 | 是 | 是 | | 資料許可政策 | 否 | 否 | 否 | 是 | 否 | **範例**： ``` Domo_read = glueContext.create_dynamic_frame.from_options( connection_type="domo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "dataset", "API_VERSION": "v1" } ``` ## Domo 實體和欄位詳細資訊 具有靜態中繼資料的實體： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/domo-reading-from-entities.html) 對於下列實體，Domo 會提供端點來動態擷取中繼資料，以便在實體的資料類型層級擷取運算子支援。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/domo-reading-from-entities.html) ## 分區查詢 **欄位型分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，接受 ISO 格式的值。 有效值範例： ``` "2023-01-15T11:18:39.205Z" ``` 對於 Date 欄位，我們接受 ISO 格式的值。 有效值範例： ``` "2023-01-15" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 有效值範例： ``` "2023-02-15T11:18:39.205Z" ``` + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/domo-reading-from-entities.html) 範例： ``` Domo_read = glueContext.create_dynamic_frame.from_options( connection_type="domo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "dataset", "API_VERSION": "v1", "PARTITION_FIELD": "permissionTime" "LOWER_BOUND": "2023-01-15T11:18:39.205Z" "UPPER_BOUND": "2023-02-15T11:18:39.205Z" "NUM_PARTITIONS": "2" } ``` **記錄型分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 在記錄型分區中，從 Domo 中查詢存在的記錄總數，然後除以提供的 `NUM_PARTITIONS` 數字。然後，每個子查詢都會同時擷取產生的記錄數目。 範例： ``` Domo_read = glueContext.create_dynamic_frame.from_options( connection_type="domo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "dataset", "API_VERSION": "v1", "NUM_PARTITIONS": "2" } ``` # Domo 連線選項 以下是 Domo 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Domo 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。要使用的 Domo 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。用於讀取。要讀取的分區數目。 # Domo 限制 以下是 Domo 的限制或備註： + 由於 SDK 限制，對於以 '\$1' 開頭的可查詢欄位，篩選無法如預期運作 (例如：\$1BATCH\$1ID)。 + 由於 API 限制，篩選會在您提供日期之前的日期運作。這也會影響增量提取。為了克服此限制，請根據您的時區 (相對於 UTC) 選擇日期，以取得所需日期的資料。 # 連線至 Dynatrace Dynatrace 是提供分析和自動化的平台，可提供全面的可觀測性和安全性。其專注於監控和最佳化應用程式效能、基礎設施及使用者體驗。 **Topics** + [AWS Glue 支援 Dynatrace](dynatrace-support.md) + [包含用於建立和使用連線的 API 操作的政策](dynatrace-configuring-iam-permissions.md) + [設定 Dynatrace](dynatrace-configuring.md) + [設定 Dynatrace 連線](dynatrace-configuring-connections.md) + [從 Dynatrace 實體中讀取](dynatrace-reading-from-entities.md) + [Dynatrace 連線選項](dynatrace-connection-options.md) + [Dynatrace 限制](dynatrace-connection-limitations.md) # AWS Glue 支援 Dynatrace AWS Glue 支援 Dynatrace，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Dynatrace 查詢資料。 **支援作為目標？** 否。 **支援的 Dynatrace API 版本** 支援下列 Dynatrace API 版本： +   v2 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Dynatrace 您必須先符合下列要求，才能使用 從 Dynatrace AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有 Dynatrace 帳戶。 + 您已在 Dynatrace 帳戶中產生存取字符，並指派適當的讀取/寫入範圍來存取 API。如需詳細資訊，請參閱[產生字符](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/basics/dynatrace-api-authentication#create-token)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Dynatrace 帳戶。 # 設定 Dynatrace 連線 Dynatrace 支援自訂身分驗證。 若要設定 Dynatrace 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式 – 機密應包含以 `apiToken` 作為金鑰的連線應用程式 API 金鑰。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**資料來源**時，選取 Dynatrace。 1. 提供您要連線的 Dynatrace 帳戶的 `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`。 # 從 Dynatrace 實體中讀取 **必要條件** 您要從中讀取的 Dynatrace 物件。您將需要物件名稱，例如 "problem"。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 問題 | 是 | 是 | 是 | 是 | 否 | **範例**： ``` Dynatrace_read = glueContext.create_dynamic_frame.from_options( connection_type="Dynatrace", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "problem", "API_VERSION": "v2", "INSTANCE_URL": "https://[instanceName].live.dynatrace.com" } ``` **Dynatrace 實體和欄位詳細資訊**： Dynatrace 提供端點，可動態擷取支援實體的中繼資料。因此，運算子支援是在資料類型層級擷取的。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/dynatrace-reading-from-entities.html) ## 分區查詢 Dynatrace 不支援欄位型分區或記錄型分區。 # Dynatrace 連線選項 以下是 Dynatrace 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Dynatrace 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。要使用的 Dynatrace Rest API 版本。 + `INSTANCE_URL`(String) - 用於讀取。有效的 Dynatrace 執行個體 URL。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # Dynatrace 限制 以下是 Dynatrace 的限制或備註： + Dynatrace 不支援欄位型分區或記錄型分區。 + 對於「全選」功能，如果您在篩選條件中提供「欄位」，則每個頁面的記錄數將不允許超過 10 個。 + 支援的頁面大小上限為 500。如果您在建立流程時選取任何 [`evidenceDetails, impactAnalysis, recentComments`] 欄位，則每個頁面的記錄數將預設為 10。 # 連線至 Facebook Ads Facebook Ads 是一個強大的數位廣告平台，各種規模的企業都可以使用其來接觸目標受眾並實現各種行銷目標。平台可讓廣告商建立量身打造的廣告，可顯示在 Facebook 的應用程式和服務系列中，包括 Facebook 和 Messenger。憑藉進階鎖定功能，Facebook Ads 可讓企業涵蓋特定的人口統計、興趣、行為和位置。 **Topics** + [AWS Glue 支援 Facebook 廣告](facebook-ads-support.md) + [包含用於建立和使用連線的 API 操作的政策](facebook-ads-configuring-iam-permissions.md) + [設定 Facebook Ads](facebook-ads-configuring.md) + [設定 Facebook Ads 連線](facebook-ads-configuring-connections.md) + [從 Facebook Ads 實體讀取](facebook-ads-reading-from-entities.md) + [Facebook Ads 連線選項](facebook-ads-connection-options.md) + [Facebook Ads 連接器的限制和備註](facebook-ads-connector-limitations.md) # AWS Glue 支援 Facebook 廣告 AWS Glue 支援 Facebook 廣告，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Facebook Ads 查詢資料。 **支援作為目標？** 否。 **支援的 Facebook Ads API 版本** 支援以下 Facebook Ads API 版本： + v17.0 + v18.0 + v19.0 + v20.0 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Facebook Ads 您必須先符合下列要求，才能使用 從 Facebook Ads AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 可以透過 Facebook 直接存取 Facebook Standard 帳戶。 + 需要使用者身分驗證才能產生存取字符。 + Facebook Ads SDK 連接器將實作*使用者存取字符 OAuth* 流程。 + 我們使用 OAuth2.0 來驗證對 Facebook Ads 的 API 請求。此 Web 型身分驗證屬於多重要素驗證 (MFA) 架構，其是 2FA 的超集。 + 使用者需要授權許可，才能存取端點。為了存取使用者的資料，可透過[許可](https://developers.facebook.com/docs/permissions)和[功能](https://developers.facebook.com/docs/features-reference)來處理端點授權。 ## 取得 OAuth 2.0 憑證 若要取得 API 憑證，以便對執行個體進行已驗證的呼叫，請參閱《Facebook Ads 開發人員指南》中的 [REST API](https://developers.facebook-ads.com/rest-api/)。 # 設定 Facebook Ads 連線 Facebook Ads 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 + 使用者仍然可以選擇在 Facebook Ads 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Facebook Ads 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生存取字符。過期的系統使用者字符自產生或重新整理之日起 60 天內有效。若要建立連續性，開發人員應在 60 天內重新整理存取字符。否則會導致存取字符被沒收，並且需要開發人員獲取新的存取字符才能重新獲取 API 存取權。請參閱[重新整理存取字符](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)。 + 如需為授權碼 OAuth 流程建立連線應用程式的公有 Facebook Ads 文件，請參閱《Google for Developers 指南》中的[使用 OAuth 2.0 存取 Google API](https://developers.google.com/identity/protocols/oauth2)。 若要設定 Facebook Ads 連線，請執行以下操作： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**連線類型**時，請選取 Facebook Ads。 1. 提供您要連線的 Facebook Ads 執行個體的 `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`。 # 從 Facebook Ads 實體讀取 **必要條件** 您想要從中讀取的 Facebook Ads 物件。將需要物件名稱。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | 是 | 是 | 否 | 是 | 是 | | 廣告集 | 是 | 是 | 否 | 是 | 是 | | 廣告 | 是 | 是 | 否 | 是 | 是 | | 廣告創意 | 否 | 是 | 否 | 是 | 否 | | Insights - 帳戶 | 否 | 是 | 否 | 是 | 否 | | 帳戶 | 是 | 是 | 否 | 是 | 否 | | Insights - 廣告 | 是 | 是 | 否 | 是 | 是 | | Insights - 廣告集 | 是 | 是 | 否 | 是 | 是 | | Insights - 行銷活動 | 是 | 是 | 否 | 是 | 是 | **範例**： ``` FacebookAds_read = glueContext.create_dynamic_frame.from_options( connection_type="FacebookAds", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0" } ``` ## Facebook Ads 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [廣告帳戶](https://developers.facebook.com/docs/marketing-api/reference/ad-account) + [行銷活動](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group) + [廣告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign) + [廣告](https://developers.facebook.com/docs/marketing-api/reference/adgroup) + [廣告創意](https://developers.facebook.com/docs/marketing-api/reference/ad-creative) + [Insight 廣告帳戶](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights) + [Insights 廣告](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/) + [Insights 廣告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights) + [Insights 行銷活動](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights) 如需詳細資訊，請參閱[行銷 API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)。 **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。 ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值範例： ``` "2022-01-01" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` FacebookADs_read = glueContext.create_dynamic_frame.from_options( connection_type="FacebookAds", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0", "PARTITION_FIELD": "created_time" "LOWER_BOUND": "2022-01-01" "UPPER_BOUND": "2024-01-02" "NUM_PARTITIONS": "10" } ``` # Facebook Ads 連線選項 以下是 Facebook Ads 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Facebook Ads 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Facebook Ads Rest API 版本。例如：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。用於讀取。要讀取的分區數目。 + `TRANSFER_MODE`(String) - 預設：SYNC。用於非同步讀取。 # Facebook Ads 連接器的限制和備註 以下是 Facebook Ads 連接器的限制或備註： + 由於 Facebook Ads 支援動態中繼資料，因此可以查詢所有欄位。所有欄位都支援篩選，如果資料可用，則會擷取記錄，否則 Facebook 會傳回錯誤請求 (400) 回應，並顯示適當的錯誤訊息。 + 應用程式的呼叫計數是使用者在滾動一小時時段 200 期間可以進行的呼叫次數乘以使用者數目。如需速率限制詳細資訊，請參閱[速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)與[商業使用案例速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)。 # 連線至 Facebook Page Insights Facebook Pages 可讓公司和其他興趣群組為 Facebook.com 社交網路建立頁面。公司使用這些頁面來分享營業時間，發布公告，以及在線上與客戶互動。如果您是 Facebook Page Insights 使用者，您可以 AWS Glue 連線至您的 Facebook Page Insights 帳戶。您可以使用 Facebook Page Insights 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Facebook Page Insights 傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Facebook Page Insights](facebook-page-insights-support.md) + [包含用於建立和使用連線的 API 操作的政策](facebook-page-insights-configuring-iam-permissions.md) + [設定 Facebook Page Insights](facebook-page-insights-configuring.md) + [設定 Facebook Page Insights 連線](facebook-page-insights-configuring-connections.md) + [從 Facebook Page Insights 實體讀取](facebook-page-insights-reading-from-entities.md) + [Facebook Page Insights 連線選項](facebook-page-insights-connection-options.md) + [Facebook Page Insights 連接器的限制和備註](facebook-page-insights-connector-limitations.md) # AWS Glue 支援 Facebook Page Insights AWS Glue 支援 Facebook Page Insights，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Facebook Page Insights 查詢資料。 **支援作為目標？** 否。 **支援的 Facebook Page Insights API 版本** 支援以下 Facebook Page Insights API 版本： + v17 + v18 + v19 + v20 + v21 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Facebook Page Insights 您必須先符合下列要求，才能使用 從 Facebook Page Insights AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 可以透過 Facebook 直接存取 Facebook Standard 帳戶。 + 需要使用者身分驗證才能產生存取字符。 + Facebook Page Insights 連接器會實作使用者存取字符 OAuth 流程。 + 連接器使用 OAuth2.0 驗證對 Facebook Page Insights 的 API 請求。這屬於多重要素驗證 (MFA) 架構，其是 2FA 的超集。其是以 Web 為基礎的身分驗證。 + 使用者需要授予存取端點的許可。為了存取使用者的資料，可透過許可和功能來處理端點授權。 # 設定 Facebook Page Insights 連線 若要設定 Facebook Page Insights 連線，請執行以下操作： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**連線類型**時，選取 Facebook Page Insights。 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. 選取授權碼 URL。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 Facebook Page Insights 實體讀取 **必要條件** 您想要從中讀取的 Facebook Page Insights 物件。將需要物件名稱。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 頁面內容 | 是 | 否 | 是 | 是 | 是 | | 頁面 CTA 點按數 | 是 | 否 | 否 | 是 | 是 | | 頁面參與度 | 是 | 否 | 否 | 是 | 是 | | 頁面瀏覽數 | 是 | 否 | 否 | 是 | 是 | | 頁面貼文 | 是 | 否 | 否 | 是 | 是 | | 頁面貼文參與度 | 否 | 否 | 否 | 是 | 否 | | 頁面貼文回應 | 否 | 否 | 否 | 是 | 否 | | 頁面回應 | 是 | 否 | 否 | 是 | 是 | | 案例 | 是 | 否 | 否 | 是 | 是 | | 頁面使用者人口統計 | 是 | 否 | 否 | 是 | 是 | | 頁面影片檢視 | 是 | 否 | 否 | 是 | 是 | | 頁面檢視 | 是 | 否 | 否 | 是 | 是 | | 頁面影片貼文 | 是 | 否 | 否 | 是 | 是 | | 頁面 | 否 | 是 | 否 | 是 | 否 | | 饋送 | 是 | 是 | 否 | 是 | 是 | **範例**： ``` facebookPageInsights_read = glueContext.create_dynamic_frame. from options( connection_type="facebookpageinsights", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v21" } ``` **Facebook Page Insights 欄位詳細資訊**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/facebook-page-insights-reading-from-entities.html) ## 分區查詢 **基於篩選條件的分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-09-30T01:01:01.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` facebookPageInsights_read = glueContext.create_dynamic_frame.from_options( connection_type="facebookpageinsights", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v21", "PARTITION_FIELD": "created_Time" "LOWER_BOUND": "2024-10-27T07:00:00+0000" "UPPER_BOUND": "2024-10-27T07:00:00+0000" "NUM_PARTITIONS": "10" } ``` # Facebook Page Insights 連線選項 以下是 Facebook Page Insights 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Facebook Page Insights 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Facebook Page Insights 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 Facebook Page Insights 執行個體 URL。 # Facebook Page Insights 連接器的限制和備註 以下是 Facebook Page Insights 連接器的限制或備註： + 大多數指標將每 24 小時更新一次。 + 只有過去兩年的洞察資料可用。 + 使用 `since` 和 `until` 參數時，一次只能檢視 90 天的洞察。 # 連線至 Freshdesk Freshdesk 是一種以雲端為基礎的客戶支援軟體，功能豐富且易於使用。提供多個支援管道，包括即時聊天、電子郵件、電話和社交媒體，您可以透過客戶偏好的通訊方法來協助客戶。如果您是 Freshdesk 使用者，您可以 AWS Glue 連線到您的 Freshdesk 帳戶。您可以使用 Freshdesk 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Freshdesk 傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Freshdesk](freshdesk-support.md) + [包含用於建立和使用連線的 API 操作的政策](freshdesk-configuring-iam-permissions.md) + [設定 Freshdesk](freshdesk-configuring.md) + [設定 Freshdesk 連線](freshdesk-configuring-connections.md) + [從 Freshdesk 實體讀取](freshdesk-reading-from-entities.md) + [Freshdesk 連線選項](freshdesk-connection-options.md) + [Freshdesk 連接器的限制和備註](freshdesk-connector-limitations.md) # AWS Glue 支援 Freshdesk AWS Glue 支援 Freshdesk，如下所示： **支援作為來源？** 是 – 同步和非同步。您可以使用 AWS Glue ETL 任務從 Freshdesk 查詢資料。 **支援作為目標？** 否。 **支援的 Freshdesk API 版本** 支援下列 Freshdesk API 版本： +   v2 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Freshdesk 您必須先符合下列要求，才能使用 從 Freshdesk AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + Freshdesk 帳戶。您可以選擇免費、成長、專業或企業版本。 + Freshdesk 使用者的 API 金鑰。 # 設定 Freshdesk 連線 Freshdesk 支援自訂身分驗證。 如需產生自訂授權所需 API 金鑰的公有 Freshdesk 文件，請參閱 [Freshdesk 身分驗證](https://developer.freshdesk.com/api/#authentication)。 以下是設定 Freshdesk 連線的步驟： + 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於客戶管理的連線應用程式 – 機密應包含以 `apiKey` 作為金鑰的連線應用程式 API 金鑰。請注意，您必須在 AWS Glue中為每個連線建立機密。 + 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections 下建立連線**： + 選取**資料來源**時，選取 Freshdesk。 + 提供您要連線的 Freshdesk 執行個體的 `INSTANCE_URL`。 + 選取 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": "*" } ] } ``` ------ + 選取要`secretName`用於此連線的 AWS Glue ，以放置字符。 + 如果想要使用您的網路，請選取網路選項。 + 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 + 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Freshdesk 實體讀取 **必要條件** 您想要從中讀取的 Freshdesk 物件。將需要物件名稱。 **同步來源支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 客服人員 | 是 | 是 | 否 | 是 | 是 | | 營業時間 | 否 | 是 | 否 | 是 | 是 | | 公司 | 是 | 是 | 否 | 是 | 是 | | 聯絡人 | 是 | 是 | 否 | 是 | 是 | | 對話 | 否 | 是 | 否 | 是 | 否 | | 電子郵件組態 | 否 | 是 | 否 | 是 | 否 | | 電子郵件收件匣 | 是 | 是 | 是 | 是 | 否 | | 論壇類別 | 否 | 是 | 否 | 是 | 否 | | 論壇 | 否 | 是 | 否 | 是 | 否 | | Groups (群組) | 否 | 是 | 否 | 是 | 否 | | 產品 | 否 | 是 | 否 | 是 | 否 | | 角色 | 否 | 是 | 否 | 是 | 否 | | 滿意度評分 | 是 | 是 | 否 | 是 | 否 | | 技能 | 否 | 是 | 否 | 是 | 否 | | 解決方案 | 是 | 是 | 否 | 是 | 否 | | 問卷 | 否 | 是 | 否 | 是 | 否 | | 票證 | 是 | 是 | 是 | 是 | 是 | | 時間項目 | 是 | 是 | 否 | 是 | 否 | | 主題 | 否 | 是 | 否 | 是 | 否 | | 主題評論 | 否 | 是 | 否 | 是 | 否 | **非同步來源支援的實體**： | 實體 | API 版本 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | 公司 |   v2 | 否 | 否 | 否 | 否 | 否 | | 聯絡人 |   v2 | 否 | 否 | 否 | 否 | 否 | **範例**： ``` freshdesk_read = glueContext.create_dynamic_frame.from_options( connection_type="freshdesk", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v2" } ``` **Freshdesk 實體和欄位詳細資訊**： | 實體 | 欄位 | | --- | --- | | 客服人員 | https://developers.freshdesk.com/api/\$1list\$1all\$1agents | | 營業時間 | https://developers.freshdesk.com/api/\$1list\$1all\$1business\$1hours | | 說明 | https://developers.freshdesk.com/api/\$1comment\$1attributess | | 公司 | https://developers.freshdesk.com/api/\$1companies | | 聯絡人 | https://developers.freshdesk.com/api/\$1list\$1all\$1contacts | | 對話 | https://developers.freshdesk.com/api/\$1list\$1all\$1ticket\$1notes | | Email-configs | https://developers.freshdesk.com/api/\$1list\$1all\$1email\$1configs | | Email-inboxes | https://developers.freshdesk.com/api/\$1list\$1all\$1email\$1mailboxes | | Forum-categories | https://developers.freshdesk.com/api/\$1category\$1attributes | | 論壇 | https://developers.freshdesk.com/api/\$1forum\$1attributes | | Groups (群組) | https://developers.freshdesk.com/api/\$1list\$1all\$1groups | | 產品 | https://developers.freshdesk.com/api/\$1list\$1all\$1products | | 角色 | https://developers.freshdesk.com/api/\$1list\$1all\$1roles | | Satisfaction-rating | https://developers.freshdesk.com/api/\$1view\$1all\$1satisfaction\$1ratingss | | 技能 | https://developers.freshdesk.com/api/\$1list\$1all\$1skills | | 解決方案 | https://developers.freshdesk.com/api/\$1solution\$1content | | 問卷 | https://developers.freshdesk.com/api/\$1list\$1all\$1survey | | 票證 | https://developers.freshdesk.com/api/\$1list\$1all\$1tickets | | Time-entries | https://developers.freshdesk.com/api/\$1list\$1all\$1time\$1entries | | 主題 | https://developers.freshdesk.com/api/\$1topic\$1attributes | ## 分區查詢 **基於篩選條件的分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-09-30T01:01:01.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` freshDesk_read = glueContext.create_dynamic_frame.from_options( connection_type="freshdesk", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v2", "PARTITION_FIELD": "Created_Time" "LOWER_BOUND": " 2024-10-27T23:16:08Z“ "UPPER_BOUND": " 2024-10-27T23:16:08Z" "NUM_PARTITIONS": "10" } ``` # Freshdesk 連線選項 以下是 Freshdesk 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Freshdesk 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Freshdesk 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 Freshdesk 執行個體 URL。 + `TRANSFER_MODE`(String) - 用來指示處理類型 (如 `SYNC` 或 `ASYNC`) 是否預設為 `SYNC`。(選用) # Freshdesk 連接器的限制和備註 以下是 Freshdesk 連接器的限制或備註： + 具有篩選功能的 `Company`、`Contacts` 和 `Tickets` 實體具有分頁限制。其每頁只會傳回 30 筆記錄，而頁面值最多可設定為 10 筆 (擷取最多 300 筆記錄)。 + `Tickets` 實體不會擷取超過 30 天的記錄。 + `Company`、`Contacts` 和 `Tickets` 實體支援篩選中的 'Date' 資料類型。您應選取這三個實體的「每日」後續觸發頻率。選取「分鐘」或「每小時」可能會導致資料重複。此外，選取這些欄位進行篩選時，應僅選取日期值，因為其只會考慮所選時間戳記的日期部分。 + 每分鐘 API 呼叫次數取決於您的計畫。無論用來進行呼叫的客服人數或 IP 地址等因素為何，此限制都會套用於整個帳戶。對於所有試用使用者，預設 API 限制為每分鐘 50 次呼叫。如需更多詳細資訊，請參閱 [Freshdesk](https://developer.freshdesk.com/api/#ratelimit) + 對於任何實體，一次只會處理一個匯出/非同步任務。只有在現有任務成功完成或失敗時，才會處理新任務。如需更多詳細資訊，請參閱 [Freshdesk](https://developers.freshdesk.com/api/#export_contact) + 同步 API 呼叫支援下列欄位，但不支援/允許在非同步 API 請求內文中傳遞。 + id + created\$1at + updated\$1at + updated\$1since + active + company\$1id + other\$1companies + avatar + view\$1all\$1tickets + 已刪除 + other\$1emails + state + 標籤 + 標籤 # 連線至 Freshsales Freshsales 是一種直覺式 CRM，可協助銷售代表擺脫銷售的猜測。使用內建電話和電子郵件、任務、預約及備註，銷售代表不需要在索引標籤之間切換，即可追蹤潛在客戶。您可以使用管道檢視更好地管理您的交易，並推動更多交易完成。如果您是 Freshsales 使用者，您可以 AWS Glue 連線到您的 Freshsales 帳戶。您可以使用 Freshsales 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Freshsales 傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Freshsales](freshsales-support.md) + [包含用於建立和使用連線的 API 操作的政策](freshsales-configuring-iam-permissions.md) + [設定 Freshsales](freshsales-configuring.md) + [設定 Freshsales 連線](freshsales-configuring-connections.md) + [從 Freshsales 實體中讀取](freshsales-reading-from-entities.md) + [Freshsales 連線選項](freshsales-connection-options.md) + [Freshsales 限制](freshsales-connection-limitations.md) # AWS Glue 支援 Freshsales AWS Glue 支援 Freshsales，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務來查詢來自 Freshsales 的資料。 **支援作為目標？** 否。 **支援的 Freshsales API 版本** 支援下列 Freshsales API 版本： + v1.0 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Freshsales 您必須先符合下列要求，才能使用 從 Freshsales AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有 Freshsales 帳戶。 + 您具有使用者 API 金鑰。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Freshsales 帳戶。對於一般連線，您不需要在 Freshsales 中執行任何其他操作。 # 設定 Freshsales 連線 Freshsales 支援自訂身分驗證。 如需產生自訂身分驗證所需 API 金鑰的公有 Freshsales 文件，請參閱[身分驗證](https://developer.freshsales.io/api/#authentication)。 若要設定 Freshsales 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： 1. 對於客戶管理的連線應用程式 – 機密應包含以 `apiSecretKey` 作為金鑰的連線應用程式 API 金鑰。機密也需要包含另一個金鑰值對，其中包含 `apiKey` 作為金鑰和 `token` 作為值。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**資料來源**時，選取 Freshsales。 1. 提供您要連線的 Freshsales 帳戶的 `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`。 # 從 Freshsales 實體中讀取 **必要條件** 您想要從中讀取的 Freshdesk 物件。將需要物件名稱。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 帳戶 | 是 | 是 | 是 | 是 | 是 | | 聯絡人 | 是 | 是 | 是 | 是 | 是 | **範例**： ``` freshSales_read = glueContext.create_dynamic_frame.from_options( connection_type="freshsales", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1.0" } ``` **Freshsales 實體和欄位詳細資訊**： Freshsales 提供端點，可動態擷取支援實體的中繼資料。因此，運算子支援是在資料類型層級擷取的。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/freshsales-reading-from-entities.html) ## 分區查詢 **基於篩選條件的分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，接受 ISO 格式的值。 有效值的範例： ``` "2024-09-30T01:01:01.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` freshSales_read = glueContext.create_dynamic_frame.from_options( connection_type="freshsales", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1", "PARTITION_FIELD": "Created_Time" "LOWER_BOUND": " 2024-10-15T21:16:25Z" "UPPER_BOUND": " 2024-10-20T21:25:50Z" "NUM_PARTITIONS": "10" } ``` # Freshsales 連線選項 以下是 Freshsales 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Freshsales 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Freshsales 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - 用於讀取。有效的 Freshsales 執行個體 URL。 # Freshsales 限制 以下是 Freshsales 的限制或備註： + 在 Freshsales 中，API 速率限制為每個帳戶每小時 1,000 個 API 請求 (請參閱[錯誤](https://developer.freshsales.io/api/#error))。但此限制可透過企業訂閱計劃進行擴展 (請參閱[計劃比較](https://www.freshworks.com/crm/pricing-compare/))。 # 連線至 Google Ads Google Ads API 是 Google Ads 的程式設計介面，用於管理大型或複雜的 Google Ads 帳戶和行銷活動。如果您是 Google Ads 使用者，您可以 AWS Glue 連線到 Google Ads 帳戶。然後，您可以在 ETL 任務中使用 Google Ads 作為資料來源。執行這些任務以在 Google Ads AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Google Ads](googleads-support.md) + [包含用於建立和使用連線的 API 操作的政策](googleads-configuring-iam-permissions.md) + [設定 Google Ads](googleads-configuring.md) + [設定 Google Ads 連線](googleads-configuring-connections.md) + [從 Google Ads 實體中讀取](googleads-reading-from-entities.md) + [Google Ads 連線選項](googleads-connection-options.md) + [建立 Google Ads 帳戶](googleads-create-account.md) + [限制](googleads-connector-limitations.md) # AWS Glue 支援 Google Ads AWS Glue 支援 Google Ads，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Google Ads 查詢資料。 **支援作為目標？** 否。 **支援的 Google Ads API 版本** v18 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Google Ads 您必須先符合下列要求，才能使用 從 Google Ads AWS Glue 傳輸： ## 最低需求 + 您有一個具有電子郵件和密碼的 Google Ads 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Google Ads 帳戶](googleads-create-account.md)。 + 您的 Google Ads 帳戶已啟用 API 存取。所有 Google Ads API 的使用皆免費。 + 您的 Google Ads 帳戶可讓您安裝連線的應用程式。如果無法存取此功能，請聯絡您的 Google Ads 管理員。 如果您符合這些要求，就可以 AWS Glue 連線到 Google Ads 帳戶。 # 設定 Google Ads 連線 Google Ads 支援 OAuth2 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Google Ads，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Google Ads 執行個體。 使用者可以選擇在 Google Ads 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Google Ads 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需詳細資訊，請參閱[有關為授權碼 OAuth 流程建立連線應用程式的公有 Google Ads 文件](https://developers.google.com/workspace/guides/create-credentials)。 若要設定 Google Ads 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於 AuthorizationCode 授權類型： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Google Ads。 1. 提供您要連線的 Google Ads 的 `developer token`。 1. 如果您想要以管理員身分登入，請提供 Google Ads 的 `MANAGER ID`。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Google Ads 實體中讀取 **先決條件** + 您想要從中讀取的 Google Ads 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 廣告群組廣告 | 是 | 是 | 是 | 否 | 是 | | 廣告群組 | 是 | 是 | 是 | 否 | 是 | | 行銷活動預算 | 是 | 是 | 是 | 是 | 是 | | 帳戶預算 | 是 | 否 | 是 | 是 | 否 | | 行銷活動 | 是 | 是 | 是 | 是 | 是 | | 帳戶 | 是 | 否 | 是 | 否 | 否 | **範例** ``` googleAds_read = glueContext.create_dynamic_frame.from_options( connection_type="googleads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign-3467***", "API_VERSION": "v16" } ``` **Google Ads 實體和欄位詳細資訊** | 實體 | 欄位 | 資料類型 | 支援的運算子 | | --- | --- | --- | --- | | 帳戶 | resourceName | String | \$1=, = | | 帳戶 | callReportingEnabled | Boolean | \$1=, = | | 帳戶 | callConversionReportingEnabled | Boolean | \$1=, = | | 帳戶 | callConversionAction | String | \$1=, = | | 帳戶 | conversionTrackingId | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | crossAccountConversionTrackingId | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | payPerConversionEligibilityFailureReasons | 清單 | | | 帳戶 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | currencyCode | String | \$1=, =, LIKE | | 帳戶 | timeZone | String | \$1=, =, LIKE | | 帳戶 | autoTaggingEnabled | Boolean | \$1=, = | | 帳戶 | hasPartnersBadge | Boolean | \$1=, = | | 帳戶 | manager | Boolean | \$1=, = | | 帳戶 | testAccount | Boolean | \$1=, = | | 帳戶 | date | Date | BETWEEN, =, <, >, <=, >= | | 帳戶 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | acceptedCustomerDataTerms | Boolean | | | 帳戶 | conversionTrackingStatus | String | \$1=, =, LIKE | | 帳戶 | enhancedConversionsForLeadsEnabled | Boolean | | | 帳戶 | googleAdsConversionCustomer | String | | | 帳戶 | status | String | \$1=, = | | 帳戶 | allConversionsByConversionDate | Double | \$1=, =, <, > | | 帳戶 | allConversionsValueByConversionDate | Double | \$1=, =, <, > | | 帳戶 | conversionsByConversionDate | Double | \$1=, =, <, > | | 帳戶 | conversionsValueByConversionDate | Double | \$1=, =, <, > | | 帳戶 | valuePerAllConversionsByConversionDate | Double | \$1=, =, <, > | | 帳戶 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | 點按數 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | invalidClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | costPerAllConversions | Double | \$1=, =, <, > | | 帳戶 | costPerConversion | Double | \$1=, =, <, > | | 帳戶 | 轉換 | Double | \$1=, =, <, > | | 帳戶 | absoluteTopImpressionPercentage | Double | \$1=, =, <, > | | 帳戶 | impressions | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | topImpressionPercentage | Double | \$1=, =, <, > | | 帳戶 | averageCpc | Double | \$1=, =, <, > | | 帳戶 | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶 | averageCost | Double | \$1=, =, <, > | | 帳戶 | ctr | Double | \$1=, =, <, > | | 帳戶 | activeViewCtr | Double | \$1=, =, <, > | | 帳戶 | searchImpressionShare | Double | \$1=, =, <, > | | 帳戶 | conversionAction | String | \$1=, = | | 帳戶 | conversionActionCategory | String | \$1=, = | | 帳戶 | conversionActionName | String | \$1=, =, LIKE | | 帳戶預算 | resourceName | String | \$1=, = | | 帳戶預算 | status | String | \$1=, = | | 帳戶預算 | proposedEndTimeType | String | \$1=, = | | 帳戶預算 | approvedEndTimeType | String | \$1=, = | | 帳戶預算 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶預算 | billingSetup | String | \$1=, = | | 帳戶預算 | name | String | \$1=, =, LIKE | | 帳戶預算 | approvedStartDateTime | DateTime | BETWEEN, =, <, >, <=, >= | | 帳戶預算 | proposedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶預算 | approvedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶預算 | adjustedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 帳戶預算 | amountServedMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | resourceName | String | \$1=, =, LIKE | | 廣告群組 | status | String | \$1=, =, LIKE | | 廣告群組 | type | String | \$1=, =, LIKE | | 廣告群組 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | name | String | \$1=, =, LIKE | | 廣告群組 | 行銷活動 | String | \$1=, = | | 廣告群組 | cpcBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | targetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | cpmBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | cpvBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | targetCpmMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | effectiveTargetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | date | Date | BETWEEN, =, <, >, <=, >= | | 廣告群組 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | useAudienceGrouped | Boolean | \$1=, = | | 廣告群組 | effectiveCpcBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | allConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | allConversionsValueByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | conversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | conversionsValueByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | valuePerAllConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | valuePerConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組 | averageCost | Double | \$1=, =, <, > | | 廣告群組 | costPerAllConversions | Double | \$1=, =, <, > | | 廣告群組 | costPerConversion | Double | \$1=, =, <, > | | 廣告群組 | averagePageViews | Double | \$1=, =, <, > | | 廣告群組 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | 點按數 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | allConversions | Double | \$1=, =, <, > | | 廣告群組 | averageCpc | Double | \$1=, =, <, > | | 廣告群組 | absoluteTopImpressionPercentage | Double | \$1=, =, <, > | | 廣告群組 | impressions | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組 | topImpressionPercentage | Double | \$1=, =, <, > | | 廣告群組 | activeViewCtr | Double | \$1=, =, <, > | | 廣告群組 | ctr | Double | \$1=, =, <, > | | 廣告群組 | searchTopImpressionShare | Double | \$1=, =, <, > | | 廣告群組 | searchImpressionShare | Double | \$1=, =, <, > | | 廣告群組 | searchAbsoluteTopImpressionShare | Double | \$1=, =, <, > | | 廣告群組 | relativeCtr | Double | \$1=, =, <, > | | 廣告群組 | conversionAction | String | \$1=, = | | 廣告群組 | conversionActionCategory | String | \$1=, = | | 廣告群組 | conversionActionName | String | \$1=, =, LIKE | | 廣告群組 | updateMask | String | | | 廣告群組 | 建立 | Struct | | | 廣告群組 | update | Struct | | | 廣告群組 | primaryStatus | String | \$1=, = | | 廣告群組 | primaryStatusReasons | 清單 | | | 廣告群組廣告 | resourceName | String | \$1=, = | | 廣告群組廣告 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | status | String | \$1=, = | | 廣告群組廣告 | labels | 清單 | | | 廣告群組廣告 | adGroup | String | \$1=, = | | 廣告群組廣告 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | approvalStatus | String | \$1=, = | | 廣告群組廣告 | reviewStatus | String | \$1=, = | | 廣告群組廣告 | adStrength | String | \$1=, = | | 廣告群組廣告 | type | String | \$1=, = | | 廣告群組廣告 | businessName | String | \$1=, =, LIKE | | 廣告群組廣告 | date | Date | BETWEEN, =, <, >, <=, >= | | 廣告群組廣告 | allConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | allConversionsValueByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | conversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | conversionsValueByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | valuePerAllConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | valuePerConversionsByConversionDate | Double | \$1=, =, <, > | | 廣告群組廣告 | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | averageCost | Double | \$1=, =, <, > | | 廣告群組廣告 | costPerAllConversions | Double | \$1=, =, <, > | | 廣告群組廣告 | costPerConversion | Double | \$1=, =, <, > | | 廣告群組廣告 | 點按數 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | averagePageViews | Double | \$1=, =, <, > | | 廣告群組廣告 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | allConversions | Double | \$1=, =, <, > | | 廣告群組廣告 | averageCpc | Double | \$1=, =, <, > | | 廣告群組廣告 | topImpressionPercentage | Double | \$1=, =, <, > | | 廣告群組廣告 | impressions | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 廣告群組廣告 | absoluteTopImpressionPercentage | Double | \$1=, =, <, > | | 廣告群組廣告 | activeViewCtr | Double | \$1=, =, <, > | | 廣告群組廣告 | ctr | Double | \$1=, =, <, > | | 廣告群組廣告 | conversionAction | String | \$1=, = | | 廣告群組廣告 | conversionActionCategory | String | \$1=, = | | 廣告群組廣告 | conversionActionName | String | \$1=, =, LIKE | | 廣告群組廣告 | updateMask | String | | | 廣告群組廣告 | 建立 | Struct | | | 廣告群組廣告 | update | Struct | | | 廣告群組廣告 | policyValidationParameter | Struct | | | 廣告群組廣告 | primaryStatus | String | \$1=, = | | 廣告群組廣告 | primaryStatusReasons | 清單 | | | 行銷活動 | resourceName | String | \$1=, = | | 行銷活動 | status | String | \$1=, = | | 行銷活動 | baseCampaign | String | \$1=, = | | 行銷活動 | name | String | \$1=, =, LIKE | | 行銷活動 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | campaignBudget | String | \$1=, =, LIKE | | 行銷活動 | startDate | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動 | endDate | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動 | adServingOptimizationStatus | String | \$1=, = | | 行銷活動 | advertisingChannelType | String | \$1=, = | | 行銷活動 | advertisingChannelSubType | String | \$1=, = | | 行銷活動 | experimentType | String | \$1=, = | | 行銷活動 | servingStatus | String | \$1=, = | | 行銷活動 | biddingStrategyType | String | \$1=, = | | 行銷活動 | domainName | String | \$1=, =, LIKE | | 行銷活動 | languageCode | String | \$1=, =, LIKE | | 行銷活動 | useSuppliedUrlsOnly | Boolean | \$1=, = | | 行銷活動 | positiveGeoTargetType | String | \$1=, = | | 行銷活動 | negativeGeoTargetType | String | \$1=, = | | 行銷活動 | paymentMode | String | \$1=, = | | 行銷活動 | optimizationGoalTypes | 清單 | | | 行銷活動 | date | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動 | averageCost | Double | | | 行銷活動 | 點按數 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | impressions | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | useAudienceGrouped | Boolean | \$1=, = | | 行銷活動 | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | costPerAllConversions | Double | \$1=, =, <, > | | 行銷活動 | costPerConversion | Double | \$1=, =, <, > | | 行銷活動 | invalidClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | publisherPurchasedClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | averagePageViews | Double | \$1=, =, <, > | | 行銷活動 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動 | allConversionsByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | allConversionsValueByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | conversionsByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | conversionsValueByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | valuePerAllConversionsByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | valuePerConversionsByConversionDate | Double | \$1=, =, <, > | | 行銷活動 | allConversions | Double | \$1=, =, <, > | | 行銷活動 | absoluteTopImpressionPercentage | Double | \$1=, =, <, > | | 行銷活動 | searchAbsoluteTopImpressionShare | Double | \$1=, =, <, > | | 行銷活動 | averageCpc | Double | \$1=, =, <, > | | 行銷活動 | searchImpressionShare | Double | \$1=, =, <, > | | 行銷活動 | searchTopImpressionShare | Double | \$1=, =, <, > | | 行銷活動 | activeViewCtr | Double | \$1=, =, <, > | | 行銷活動 | ctr | Double | \$1=, =, <, > | | 行銷活動 | relativeCtr | Double | \$1=, =, <, > | | 行銷活動 | updateMask | String | | | 行銷活動 | 建立 | Struct | | | 行銷活動 | update | Struct | | | 行銷活動預算 | resourceName | String | \$1=, = | | 行銷活動預算 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | status | String | \$1=, = | | 行銷活動預算 | deliveryMethod | String | \$1=, = | | 行銷活動預算 | period | String | \$1=, = | | 行銷活動預算 | type | String | \$1=, = | | 行銷活動預算 | name | String | \$1=, =, LIKE | | 行銷活動預算 | amountMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | explicitlyShared | Boolean | \$1=, = | | 行銷活動預算 | referenceCount | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | hasRecommendedBudget | Boolean | \$1=, = | | 行銷活動預算 | date | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動預算 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | startDate | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動預算 | endDate | Date | BETWEEN, =, <, >, <=, >= | | 行銷活動預算 | maximizeConversionValueTargetRoas | Double | \$1=, =, <, > | | 行銷活動預算 | maximizeConversionsTargetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | selectiveOptimizationConversionActions | String | | | 行銷活動預算 | averageCost | Double | \$1=, =, <, > | | 行銷活動預算 | costPerAllConversions | Double | \$1=, =, <, > | | 行銷活動預算 | costPerConversion | Double | \$1=, =, <, > | | 行銷活動預算 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | 點按數 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | allConversions | Double | \$1=, =, <, > | | 行銷活動預算 | valuePerAllConversions | Double | \$1=, =, <, > | | 行銷活動預算 | averageCpc | Double | \$1=, =, <, > | | 行銷活動預算 | impressions | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= | | 行銷活動預算 | ctr | Double | \$1=, =, <, > | | 行銷活動預算 | updateMask | String | | | 行銷活動預算 | 建立 | Struct | | | 行銷活動預算 | update | Struct | | **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示。 | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 廣告群組廣告 | date | Date | | 廣告群組 | date | Date | | 行銷活動 | date | Date | | 行銷活動預算 | date | Date | **範例** ``` googleads_read = glueContext.create_dynamic_frame.from_options( connection_type="googleads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign-3467***", "API_VERSION": "v16", "PARTITION_FIELD": "date" "LOWER_BOUND": "2024-01-01" "UPPER_BOUND": "2024-06-05" "NUM_PARTITIONS": "10" } ) ``` # Google Ads 連線選項 以下是 Google Ads 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Google Ads 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。要使用的 Google Ads Rest API 版本。範例：v16。 + `DEVELOPER_TOKEN`(String) - (必要) 用於讀取/寫入。需要對向 API 提出請求的開發人員或應用程式進行身分驗證。 + `MANAGER_ID`(String) - 用於讀取/寫入。可讓您管理多個 Google Ads 帳戶的唯一識別碼。這是授權管理員的客戶 ID。如果您透過管理員帳戶存取客戶帳戶，則需要 `MANAGER_ID`。如需詳細資訊，請參閱 [login-customer-id](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid)。 + `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。用於讀取。要讀取的分區數目。 # 建立 Google Ads 帳戶 1. 使用您的憑證登入 [Google Ads 開發人員帳戶](https://console.cloud.google.com)，然後前往 \$1MyProject。 ![\[螢幕擷取畫面顯示了登入 Google Ads 開發人員帳戶的歡迎畫面。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-log-in-developer-account.png) 1. 選擇**新專案**，並提供建立 Google 專案所需的資訊 (如果您在其中沒有任何已註冊的應用程式)。 ![\[螢幕擷取畫面顯示「選取專案」頁面。選擇右上角的「新增專案」。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-new-project.png) ![\[螢幕擷取畫面顯示「新增專案」視窗，以輸入專案名稱並選擇位置。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-new-project-name-location.png) 1. 選擇**導覽索引標籤**，然後選擇 **API 和設定**，以及**建立用戶端 ID **和 **ClientSecret**，這將需要進一步的組態才能在 AWS Glue 和 GoogleAds 之間建立連線。如需詳細資訊，請參閱 [API 憑證](https://console.cloud.google.com/apis/credentials)。 ![\[螢幕擷取畫面顯示 API 和服務組態頁面。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-apis-and-services.png) 1. 依次選擇**建立憑證**和 **OAuth 用戶端 ID**。 ![\[螢幕擷取畫面顯示 API 和服務組態頁面，其中包含「建立憑證」下拉式清單和反白顯示的「Oauth 用戶端 ID」選項。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-create-credentials.png) 1. 選取**應用程式類型**為 **Web 應用程式**。 ![\[螢幕擷取畫面顯示「建立 OAuth 用戶端 ID」頁面，以及應用程式類型為 Web 應用程式。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-oauth-client-id-application-type.png) 1. 在**已授權的重新導向 URI** 下，新增 OAuth 重新導向 URI，然後選擇**建立**。如有需要，您可以新增多個重新導向 URI。 ![\[螢幕擷取畫面會顯示「建立 OAuth 用戶端 ID」頁面和「已授權的重新導向 URI」區段。可在此新增 URI，並在需要時選擇「新增 URI」。完成後，選擇「建立」。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-oauth-redirect-uris.png) 1. 在 和 Google Ads 之間建立連線時，會產生您的**用戶端 ID** AWS Glue 和**用戶端秘密**。 ![\[螢幕擷取畫面會顯示「建立 OAuth 用戶端 ID」頁面和「已授權的重新導向 URI」區段。可在此新增 URI，並在需要時選擇「新增 URI」。完成後，選擇「建立」。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-oauth-client-created.png) 1. 根據您的應用程式需求新增範圍，選擇 **OAuth 同意畫面**，提供所需資訊，然後根據要求新增範圍。 ![\[螢幕擷取畫面顯示「更新選取的範圍」頁面。視需要選取您的範圍。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/google-ads-selected-scopes.png) # 限制 以下是 Google Ads 連接器的限制： + `MANAGER_ID` 是建立連線時的選用輸入。但是，當您想要存取任何特定管理員下的客戶時， `MANAGER_ID` 是強制性輸入。下表說明基於連線中是否包含 `MANAGER_ID` 的存取限制。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/googleads-connector-limitations.html) + 選擇管理員帳戶作為物件時，只有 `Account` 會顯示為子物件。在 Google Ads 連接器中，系統會根據個別用戶端帳戶 (而非管理員帳戶) 擷取行銷活動、廣告等實體。 + 您無法擷取管理員帳戶的指標。您可以改為擷取個別用戶端帳戶的指標。 + 每個帳戶最多可有 1 萬個行銷活動，包括作用中和暫停的行銷活動。如需詳細資訊，請參閱[行銷活動](https://support.google.com/google-ads/answer/6372658)。 + 建立報告時，如果您選擇要顯示的特定指標，則不會傳回所選取指標都為零的任何資料列。如需詳細資訊，請參閱[零指標](https://developers.google.com/google-ads/api/docs/reporting/zero-metrics?hl=en#exclude_zero_metrics_by_segmenting)。 + 使用下列欄位時，完整映射流程不適用於帳戶、廣告群組和廣告群組廣告實體，特別是 conversionAction、conversionActionCategory 和 conversionActionName。如需詳細資訊，請參閱[區段和指標](https://developers.google.com/google-ads/api/docs/reporting/segmentation?hl=en#selectability_between_segments_and_metrics)。 + 選取 `segments.date` 欄位時，日期範圍篩選條件是必要的。 # 連線至 Google Analytics 4 Google Analytics 4 是一種分析服務，可追蹤和報告訪客與您的應用程式及網站互動的指標。這些指標包括頁面檢視、作用中使用者及事件。如果您是 Google Analytics 4 使用者，您可以 AWS Glue 連線至 Google Analytics 4 帳戶。您可以使用 Google Analytics 4 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Google Analytics 4 傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Google Analytics 4](googleanalytics-support.md) + [包含用於建立和使用連線的 API 操作的政策](googleanalytics-configuring-iam-permissions.md) + [設定 Google Analytics 4](googleanalytics-configuring.md) + [設定 Google Analytics 4 連線](googleanalytics-configuring-connections.md) + [從 Google Analytics 4 實體中讀取](googleanalytics-reading-from-entities.md) + [Google Analytics 4 連線選項](googleanalytics-connection-options.md) + [建立 Google Analytics 4 帳戶](googleanalytics-create-account.md) + [建立用戶端應用程式和 OAuth 2.0 憑證的步驟](googleanalytics-client-app-oauth-credentials.md) + [限制及考量](googleanalytics-connector-limitations.md) # AWS Glue 支援 Google Analytics 4 AWS Glue 支援 Google Analytics 4，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Google Analytics 4 查詢資料。 **支援作為目標？** 否。 **支援的 Google Analytics 4 API 版本** v1 Beta。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Google Analytics 4 您必須先符合下列要求，才能使用 從 Google Analytics 4 AWS Glue 傳輸： ## 最低需求 + 您有一個 Google Analytics 帳戶，其中包含一個或多個資料串流，可收集您要傳輸的資料。 + 您有一個 Google Cloud Platform 帳戶和 Google Cloud 專案。 + 在您的 Google Cloud 專案中，已啟用下列 API： + Google Analytics API + Google Analytics Admin API + Google Analytics Data API + 在 Google Cloud 專案中，您已為外部使用者設定 OAuth 同意畫面。如需有關 OAuth 同意畫面的資訊，請參閱 Google Cloud Platform 主控台說明中的[設定 OAuth 同意畫面](https://support.google.com/cloud/answer/10311615#)。 + 在您的 Google Cloud 專案中，已設定 OAuth 2.0 用戶端 ID。如需詳細資訊，請參閱[設定 OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en#zippy=)。 如果您符合這些要求，就可以 AWS Glue 連線到 Google Analytics 4 帳戶。 # 設定 Google Analytics 4 連線 若要設定 Google Sheet 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於 AuthorizationCode 授權類型： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Google Analytics 4。 1. 提供您要連線的 Google Analytics 4 的 `INSTANCE_URL`。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Google Analytics 4，其中使用者必須登入並允許 AWS Glue 請求的許可存取其 Google Analytics 4 執行個體。 使用者仍然可以選擇在 Google Analytics 4 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Google Analytics 4 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需詳細資訊，請參閱[使用 Auth 2.0 存取 Google API](https://developers.google.com/identity/protocols/oauth2)。 # 從 Google Analytics 4 實體中讀取 **先決條件** + 您想要從中讀取的 Google Analytics 4 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 即時報告 | 是 | 是 | 是 | 是 | 否 | | 核心報告 | 是 | 是 | 是 | 是 | 是 | **範例** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta" } ``` **Google Analytics 4 實體和欄位詳細資訊** | 實體 | 欄位 | 資料類型 | 支援的運算子 | | --- | --- | --- | --- | | 核心報告 | 動態欄位 | | | | 核心報告 | 維度欄位 | String | LIKE, = | | 核心報告 | 維度欄位 | Date | LIKE, = | | 核心報告 | 指標欄位 | String | >, <, >=, <=, = BETWEEN | | 核心報告 | 自訂維度和自訂指標欄位 | String | NA | | 即時報告 | appVersion | String | LIKE, = | | 即時報告 | audienceId | String | LIKE, = | | 即時報告 | audienceName | String | LIKE, = | | 即時報告 | 城市 | String | LIKE, = | | 即時報告 | cityId | String | LIKE, = | | 即時報告 | 國家/地區 | String | LIKE, = | | 即時報告 | countryId | String | LIKE, = | | 即時報告 | deviceCategory | String | LIKE, = | | 即時報告 | eventName | String | LIKE, = | | 即時報告 | minutesAgo | String | LIKE, = | | 即時報告 | 平台 | String | LIKE, = | | 即時報告 | streamId | String | LIKE, = | | 即時報告 | streamName | String | LIKE, = | | 即時報告 | unifiedScreenName | String | LIKE, = | | 即時報告 | activeUsers | String | >, <, >=, <=, = BETWEEN | | 即時報告 | 轉換 | String | >, <, >=, <=, = BETWEEN | | 即時報告 | eventCount | String | >, <, >=, <=, = BETWEEN | | 即時報告 | screenPageViews | String | >, <, >=, <=, = BETWEEN | **分區查詢** 1. **基於篩選條件的分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 **範例** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta", "PARTITION_FIELD": "date" "LOWER_BOUND": "2022-01-01" "UPPER_BOUND": "2024-01-02" "NUM_PARTITIONS": "10" } ``` 1. **記錄型分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `NUM_PARTITIONS`：分區數目。 **範例** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta", "NUM_PARTITIONS": "10" } ``` # Google Analytics 4 連線選項 以下是 Google Analytics 4 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Google Analytics 4 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Google Analytics 4 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(Integer) - 用於讀取。(選用) # 建立 Google Analytics 4 帳戶 請依照下列步驟建立 Google Analytics 4 帳戶：[https://support.google.com/analytics/answer/9304153?hl=en](https://support.google.com/analytics/answer/9304153?hl=en) # 建立用戶端應用程式和 OAuth 2.0 憑證的步驟 如需詳細資訊，請參閱 [Google Analytics4 API 文件](https://developers.google.com/analytics/devguides/reporting/data/v1)。 1. 使用您的憑證登入 [Google Analytics 帳戶](https://analytics.google.com/)，以建立和設定您的帳戶。然後導覽至**管理員** > **建立帳戶**。 1. 選擇**建立屬性**，為您建立的帳戶建立屬性。設定具有必要詳細資訊的屬性。提供所有詳細資訊之後，就會產生對應的屬性 ID。 1. 從下拉式清單中選擇**資料串流** > **新增串流** > **Web**，為建立的屬性新增資料串流。提供網站詳細資訊，例如 URL 和其他必要欄位。提供所有詳細資訊之後，將產生對應的**串流 ID **和**測量 ID**。 1. 透過複製測量 ID，在您的網站中設定 Google Analytics，並新增至網站的組態。 1. 透過導覽至**報告**並產生所需的報告，從 Google Analytics 中建立報告。 1. 透過導覽至 [console.cloud.google.com]( https://console.cloud.google.com) 來授權您的應用程式並搜尋 Google Analytics Data API ，然後啟用 API。 1. 導覽至「API 和服務」頁面，並選擇**憑證** > **設定 OAuth 2.0 用戶端 ID**。 1. 新增重新導向 URL，以提供 AWS Glue 重新導向 URL。 1. 複製需要進一步建立連線的用戶端 ID 和用戶端機密。 # 限制及考量 以下是 Google Analytics 4 連接器的限制： + 對於核心報告實體，僅允許在請求中傳送 9 個維度欄位和 10 個指標欄位。如果超過允許的欄位數目，則請求將失敗，連接器將擲回錯誤訊息。 + 對於即時報告實體，僅允許在請求中傳送 4 個維度欄位。如果超過允許的欄位數目，則請求將失敗，連接器將擲回錯誤訊息。 + Google Analytics 4 是 Beta 版免費工具，因此新功能、實體增強功能、新增新欄位和取代現有欄位會定期更新。 + 核心報告欄位會動態填入，因此可隨時新增、取代和重新命名欄位，並對欄位實施新的限制。 + 預設的開始日期為 30 天，結束日期為昨天 (目前日期的前一天)，如果使用者已設定該值或者如果流程為遞增，則篩選運算式程式碼中會覆寫這些日期。 + 根據文件，如果請求中未傳遞限制，則即時報告實體會傳回 10,000 筆記錄，否則 API 會傳回每個請求最多 250,000 個資料列，無論您要求多少資料列。如需詳細資訊，請參閱 Google Analytics 文件中的 [Method: properties.runRealtimeReport](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport)。 + 即時報告實體不支援記錄型分區，因為其不支援分頁。此外，其不支援欄位型分區，因為所有欄位都不符合定義的條件。 + 因為在請求中傳遞的欄位數目有限制。我們正在指定的限制內設定預設維度和指標欄位。如果選擇「全選」，則僅擷取這些預定欄位中的資料。 + 核心報告 + 根據 SAAS 的限制 - 請求最多只能允許 9 個維度和最多 10 個指標 (也就是說，請求最多可包含 19 個欄位 (指標 \$1 維度))。 + 根據實作 - 如果使用者使用 SELECT\$1ALL 或選取的欄位超過 25 個，則預設欄位將傳入請求。 + 下列欄位被視為核心報告的預設欄位 - "country"、"city"、"eventName"、"cityId"、"browser"、"date"、"currencyCode"、"deviceCategory"、"transactionId"、active1DayUsers"、"active28DayUsers"、"active7DayUsers"、"activeUsers"、"averagePurchaseRevenue"、"averageRevenuePerUser"、"averageSessionDuration"、"engagedSessions"、"eventCount"、"engagementRate"。 + 即時報告 + 根據 SAAS 請求的限制，最多允許 4 個維度。 + 如果使用者選擇 SELECT\$1ALL 或選取的欄位超過 15 個，則預設欄位將傳入請求。 + 下列欄位被視為即時報告的預設欄位 - "country"、"deviceCategory"、"city"、"cityId"、"activeUsers"、"conversions"、"eventCount"、"screenPageViews"。 + 在核心報告實體中，如果日期欄位的分區和 startDate 的篩選條件同時存在。在這種情況下，dateRange 值會被 startDate 篩選條件值覆寫，但由於分區必須始終具有優先性，因此如果日期欄位的分區已存在，則會捨棄 startDate 篩選條件。 + 由於目前 cohortSpecs 也是核心報告請求內文的一部分，因此我們已增強目前的核心報告實體，以包含對 cohortSpec 屬性的支援。在 cohortSpecs 請求內文中，幾乎所有欄位都需要使用者輸入。為了解決此問題，我們已設定這些屬性/欄位的預設值，並視需要為使用者提供佈建以覆寫這些值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/googleanalytics-connector-limitations.html) + 也可以同時傳遞所有這些篩選條件，或者與其他篩選條件一起傳遞。 + 範例 1 - filterPredicate: startDate between "2023-05-09" and "2023-05-10" AND startOffset=1 AND endOffset=2 AND granularity="WEEKLY" + 範例 2 - filterPredicate: city=“xyz” AND startOffset=1 AND endOffset=2 AND granularity="WEEKLY" + 在 cohort 請求中： + 如果請求中傳遞 'cohortNthMonth'，則內部精細度值將設定為 "MONTHLY" + 同樣，如果傳遞 'cohortNthWeek'，則精細度值將設定為 "WEEKLY" + 此外，對於 'cohortNthDay'，精細度值將設定為 "DAILY"。如需詳細資訊，請參閱： + [ https://developers.google.com/analytics/devguides/reporting/data/v1/advanced ](https://developers.google.com/analytics/devguides/reporting/data/v1/advanced) + [ https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec ](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec) + 會為使用者提供佈建，以覆寫 dateRange 和精細度預設值。請參閱上面的表格。 # 在 AWS Glue Studio 中連線至 Google BigQuery **注意** 
 您可以使用 AWS Glue for Spark 從 AWS Glue 4.0 及更新版本中的 Google BigQuery 讀取和寫入資料表。若要使用 AWS Glue 任務程式設計方式設定 Google BigQuery，請參閱[BigQuery 連線](aws-glue-programming-etl-connect-bigquery-home.md)。
 AWS Glue Studio 提供視覺化介面來連線至 BigQuery、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行這些任務。 在 中建立與 Google BigQuery 的連線時 AWS Glue Studio，會建立統一的連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 您現在可以透過與 Google BigQuery 的統一連線，建立直接包含 Goolge BigQuery JSON 的機密，而不是使用特定格式的憑證 `{"credentials": "base64 encoded JSON"}` 建立機密：`{"type": "service-account", ...}`。 **Topics** + [建立 BigQuery 連線](creating-bigquery-connection.md) + [建立 BigQuery 來源節點](creating-bigquery-source-node.md) + [建立 BigQuery 目標節點](creating-bigquery-target-node.md) + [進階選項](#creating-bigquery-connection-advanced-options) # 建立 BigQuery 連線 若要從 連線至 Google BigQuery AWS Glue，您需要在 AWS Secrets Manager 秘密中建立和存放 Google Cloud Platform 登入資料，然後將該秘密與 Google BigQuery AWS Glue 連線建立關聯。 **設定連至 BigQuery 的連線：** 1. 在 Google Cloud Platform 中建立並識別相關資源： + 建立或識別 GCP 專案，其中應包含您要連線之 BigQuery 資料表。 + 啟用 BigQuery API。如需詳細資訊，請參閱 [Use the BigQuery Storage Read API to read table data](https://cloud.google.com/bigquery/docs/reference/storage/#enabling_the_api)。 1. 在 Google Cloud Platform 中建立和匯出服務帳戶憑證： 您可以使用 BigQuery 憑證精靈來加速此步驟：[Create credentials](https://console.cloud.google.com/apis/credentials/wizard?api=bigquery.googleapis.com)。 若要在 GCP 中建立服務帳戶，請依照 [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create) 中提供的教學課程進行操作。 + 在選取**專案**時，請選取包含您 BigQuery 資料表的專案。 + 在為您的服務帳戶選取 GCP IAM 角色時，請新增或建立角色，其會授予供執行 BigQuery 任務的適當許可，以讀取、寫入或建立 BigQuery 資料表。 若要為您的服務帳戶建立憑證，請依照 [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) 中提供的教學課程進行操作。 + 在選取金鑰類型時，請選取 **JSON**。 您現在應已下載 JSON 檔案，該檔案中包含您服務帳戶的憑證。其看起來與下列類似： ``` { "type": "service_account", "project_id": "*****", "private_key_id": "*****", "private_key": "*****", "client_email": "*****", "client_id": "*****", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "*****", "universe_domain": "googleapis.com" } ``` 1. 在 中 AWS Secrets Manager，使用您下載的登入資料檔案建立秘密。您可以選擇**純文字**索引標籤，並貼上 JSON 格式的檔案內容。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 1. 在 AWS Glue 資料目錄中，依照中的步驟建立連線[https://docs.aws.amazon.com/glue/latest/dg/console-connections.html](https://docs.aws.amazon.com/glue/latest/dg/console-connections.html)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Google BigQuery。 + 選取 **AWS 機密**時，請提供 *secretName*。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 *secretName* 的許可。 1. 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。 # 建立 BigQuery 來源節點 ## 必要先決條件 + BigQuery 類型 AWS Glue Data Catalog 連線 + 連線所使用的 Google BigQuery 登入資料的 AWS Secrets Manager 秘密。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您要讀取的資料表名稱和資料集，以及對應的 Google Cloud 專案。 ## 新增 BigQuery 資料來源 **新增**資料來源 – BigQuery** 節點：** 1. 選擇您 BigQuery 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 BigQuery 連線**。如需詳細資訊，請參閱 [Overview of using connectors and connections ](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 識別您要讀取的 BigQuery 資料，然後選擇 **BigQuery 來源**選項 + 選擇單一資料表 – 讓您可從資料表中提取所有資料。 + 輸入自訂查詢 – 讓您可藉由提供查詢來自訂要擷取的資料。 1. 描述您要讀取的資料 **(必要)** 將**父系專案**設定為包含資料表的專案，或設定為計費父系專案 (若相關)。 若您選擇單一資料表，請以下列格式將**資料表**設定為 Google BigQuery 資料表的名稱：`[dataset].[table]` 若您選擇查詢，請將其提供給**查詢**。在您的查詢中，請參考具有完整資料表名稱的資料表，格式為：`[project].[dataset].[tableName]`。 1. 提供 BigQuery 屬性 若您選擇單一資料表，您便無需提供其他屬性。 若您選擇查詢，則必須提供下列**自訂 Google BigQuery 屬性**： + 將 `viewsEnabled` 設定為 true。 + 將 `materializationDataset` 設定為資料集。透過 AWS Glue 連線提供的登入資料驗證的 GCP 主體必須能夠在此資料集中建立資料表。 # 建立 BigQuery 目標節點 ## 必要先決條件 + BigQuery 類型 AWS Glue Data Catalog 連線 + 連線所使用的 Google BigQuery 登入資料的 AWS Secrets Manager 秘密。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您要寫入的資料表名稱和資料集，以及對應的 Google Cloud 專案。 ## 新增 BigQuery 資料目標 **新增**資料目標 – BigQuery** 節點：** 1. 選擇您 BigQuery 資料目標的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 BigQuery 連線**。如需詳細資訊，請參閱 [Overview of using connectors and connections ](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 識別您要寫入的 BigQuery 資料表，然後選擇一個**寫入方法**。 + 直接 – 使用 BigQuery Storage Write API 直接寫入 BigQuery。 + 間接 – 寫入 Google Cloud Storage，然後複製至 BigQuery。 若您要間接寫入，請提供具有**暫時 GCS 儲存貯體**的目的地 GCS 位置。您將需要在 AWS Glue 連線中提供其他組態。如需詳細資訊，請參閱 [Using indirect write with Google BigQuery](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-connect-bigquery-home.html#aws-glue-programming-etl-connect-bigquery-indirect-write)。 1. 描述您要讀取的資料 **(必要)** 將**父系專案**設定為包含資料表的專案，或設定為計費父系專案 (若相關)。 若您選擇單一資料表，請以下列格式將**資料表**設定為 Google BigQuery 資料表的名稱：`[dataset].[table]` ## 進階選項 您可以在建立 BigQuery 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱《 AWS Glue 開發人員指南》中的 [ BigQuery 連線選項參考](https://docs.aws.amazon.com//glue/latest/dg/aws-glue-programming-etl-connect-bigquery-home.html)。 # 連線至 Google Search Console Google Search Console 是一個免費平台，可供網站擁有者監控 Google 如何檢視網站並最佳化其自然呈現。其中包括檢視參考網域、行動網站效能、豐富的搜尋結果，以及最高流量的查詢和頁面。如果您是 Google 搜尋主控台使用者，您可以 AWS Glue 連線至 Google 搜尋主控台帳戶。您可以使用 Google Search Console 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Google 搜尋主控台傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Google 搜尋主控台](google-search-console-support.md) + [包含用於建立和使用連線的 API 操作的政策](google-search-console-configuring-iam-permissions.md) + [設定 Google Search Console](google-search-console-configuring.md) + [設定 Google Search Console 連線](google-search-console-configuring-connections.md) + [從 Google Search Console 實體中讀取](google-search-console-reading-from-entities.md) + [Google Search Console 連線選項](google-search-console-connection-options.md) + [Google Search Console 限制](google-search-console-limitations.md) # AWS Glue 支援 Google 搜尋主控台 AWS Glue 支援 Google 搜尋主控台，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Google 搜尋主控台查詢資料。 **支援作為目標？** 否。 **支援的 Google Search Console API 版本** 支援下列 Google Search Console API 版本： + v3 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Google Search Console 您必須先符合下列要求，才能使用 從 Google 搜尋主控台 AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有 Google Search Console 帳戶。 + 您有一個 Google Cloud Platform 帳戶和 Google Cloud 專案。 + 在您的 Google Cloud 專案中，您已啟用 Google Search Console API。 + 在 Google Cloud 專案中，您已為外部使用者設定 OAuth 同意畫面。如需詳細資訊，請參閱 Google Cloud Platform 主控台說明中的[設定 OAuth 同意畫面](https://support.google.com/cloud/answer/10311615)。 + 在您的 Google Cloud 專案中，已設定 OAuth 2.0 用戶端 ID。請參閱[設定 OAuth 2.0](https://support.google.com/cloud/answer/6158849)，了解在對您的帳戶進行驗證呼叫時， AWS Glue 使用 安全存取資料的用戶端登入資料。 如果您符合這些要求，就可以 AWS Glue 連線到 Google 搜尋主控台帳戶。對於一般連線，您不需要在 Google Search Console 中執行任何其他操作。 # 設定 Google Search Console 連線 Google Search Console 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。授予類型會決定 如何與 Google 搜尋主控台 AWS Glue 通訊，以請求存取您的資料。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者仍然可以選擇在 Google 搜尋主控台中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Google 搜尋主控台，以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需為授權碼 OAuth 流程建立連線應用程式的公有 Google Search Console 文件，請參閱[使用 OAuth 2.0 存取 Google API](https://developers.google.com/identity/protocols/oauth2)。 若要設定 Google Search Console 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Google Search Console。 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`。 # 從 Google Search Console 實體中讀取 **必要條件** 您想要從中讀取的 Google Search Console 物件。將需要物件名稱。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 搜尋分析 | 是 | 是 | 否 | 是 | 否 | | 網站 | 否 | 否 | 否 | 是 | 否 | | 網站地圖 | 否 | 否 | 否 | 是 | 否 | **範例**： ``` googleSearchConsole_read = glueContext.create_dynamic_frame.from_options( connection_type="googlesearchconsole", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v3" } ``` **Google Search Console 實體和欄位詳細資訊**： Google Search Console 提供端點，可動態擷取支援實體的中繼資料。因此，運算子支援是在資料類型層級擷取的。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/google-search-console-reading-from-entities.html) **注意** 如需篩選條件有效值的更新清單，請參閱 [Google Search Console](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) API 文件。 欄位 `start_end_date` 是 `start_date` 和 `end_date` 的組合。 ## 分區查詢 不支援篩選條件型分區和記錄型分區。 # Google Search Console 連線選項 以下是 Google Search Console 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Google Search Console 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Google Search Console Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設值：「start\$1end\$1date 介於 <距目前日期 30 天前> 和 <昨天：即距目前日期 1 天前> 之間」。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設值：「start\$1end\$1date 介於 <距目前日期 30 天前> 和 <昨天：即距目前日期 1 天前> 之間」。用於讀取。完整的 Spark SQL 查詢。 + `INSTANCE_URL`(String) - 用於讀取。有效的 Google Search Console 執行個體 URL。 # Google Search Console 限制 以下是 Google Search Console 的限制或備註： + Google Search Console 會強制執行 API 的使用限制。如需詳細資訊，請參閱[用量限制](https://developers.google.com/webmaster-tools/limits)。 + `Search Analytics` 實體未傳遞篩選條件時，API 會加總所指定預設日期範圍內整個網站的所有點選、曝光、CTR 和其他資料，並將其顯示為單一記錄。 + 若要將資料細分為較小的區段，您需要將維度引入您的查詢。Dimensions 會告知 API 您希望如何分區資料。 + 例如，如果新增 `filterPredicate: dimensions="country"`，您會在網站在指定期間內接收流量的每個國家/地區取得一筆記錄。 + 傳遞多個維度的範例：`filterPredicate: dimensions="country" AND dimensions="device" AND dimensions="page"`。在這種情況下，您將在這三個維度的每個唯一組合的回應中取得一列。 + `start_end_date` 和 `dataState` 欄位已設定預設值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/google-search-console-limitations.html) # 連線至 Google Sheets Google Sheets 是一種線上試算表軟體，可讓您組織大量資料、建立自訂報告、自動化計算，以及與他人協作。如果您是 Google Sheets 使用者，您可以 AWS Glue 連線至 Google Sheets 帳戶。然後，您可以在 ETL 任務中使用 Google Sheets 作為資料來源。執行這些任務以在 Google Sheets AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Google Sheets](googlesheets-support.md) + [包含用於建立和使用連線的 API 操作的政策](googlesheets-configuring-iam-permissions.md) + [設定 Google Sheets](googlesheets-configuring.md) + [設定 Google Sheets 連線](googlesheets-configuring-connections.md) + [從 Google Sheets 實體中讀取](googlesheets-reading-from-entities.md) + [Google Sheets 連線選項](googlesheets-connection-options.md) + [設定 Google Sheets 的授權碼 OAuth 流程](googlesheets-oauth-authorization.md) + [Google Sheets 連接器限制](googlesheets-connector-limitations.md) # AWS Glue 支援 Google Sheets AWS Glue 支援 Google Sheets，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Google Sheets 查詢資料。 **支援作為目標？** 否。 **支援的 Google Sheets API 版本** Google Sheets API v4 和 Google Drive API v3 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Google Sheets 您必須先符合下列要求，才能使用 從 Google Sheets AWS Glue 傳輸： ## 最低需求 + 您有一個具有電子郵件和密碼的 Google Sheets 帳戶。 + 您的 Google Sheets 帳戶已啟用 API 存取。所有 Google Sheets API 的使用皆免費。 + 您的 Google Sheets 帳戶允許您安裝連線的應用程式。如果無法存取此功能，請聯絡您的 Google Sheets 管理員。 如果您符合這些要求，就可以 AWS Glue 連線到 Google Sheets 帳戶。 # 設定 Google Sheets 連線 若要設定 Google Sheet 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於 AuthorizationCode 授權類型： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**資料來源**時，請選取 Google Sheets。 1. 提供 Google Sheets 環境。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ **AUTHORIZATION\$1CODE 授權類型** 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Google Sheets，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Google Sheets 執行個體。 使用者可以選擇在 Google Sheets 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Google Sheets 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需詳細資訊，請參閱[有關為授權碼 OAuth 流程建立連線應用程式的公有 Google Sheets 文件](https://developers.google.com/workspace/guides/create-credentials)。 # 從 Google Sheets 實體中讀取 **先決條件** + 您要從中讀取的 Google SpreadSheet。您將需要試算表的 SpreadSheet ID 和 tabName。 **Google Sheets 實體和欄位詳細資訊：** | 實體 | 資料類型 | 支援的運算子 | | --- | --- | --- | | 試算表 | String | 不適用 (不支援篩選條件) | **範例** ``` googleSheets_read = glueContext.create_dynamic_frame.from_options( connection_type="googlesheets", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "{SpreadSheetID}#{SheetTabName}", "API_VERSION": "v4" } ``` **分區查詢** 僅對於「以記錄為基礎的分區」，如果您想利用 Spark 中的並行，可以提供 `NUM_PARTITIONS` 作為其他 Spark 選項。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 **`NUM_PARTITIONS` 的範例** ``` googlesheets_read = glueContext.create_dynamic_frame.from_options( connection_type="googlesheets", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "{SpreadSheetID}#{SheetTabName}", "API_VERSION": "v4", "NUM_PARTITIONS": "10" } ``` # Google Sheets 連線選項 以下是 Google Sheets 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Google Sheets 中的 `SpreadSheet ID` 和 `sheetTabName`。範例：`{SpreadSheetID}#{SheetTabName}`。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Google Sheets Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # 設定 Google Sheets 的授權碼 OAuth 流程 **先決條件** + 可讓您登入以使用 Google Sheets 應用程式的 Google 帳戶。在您的 Google 帳戶中，Google Sheets 包含您要傳輸的資料。 + Google Cloud Platform 帳戶和 Google Cloud 專案。如需詳細資訊，請參閱[建立 Google Cloud 專案](https://developers.google.com/workspace/guides/create-project)。 **若要設定您的 Google 帳戶並取得 OAuth 2.0 憑證，請執行以下操作：** 1. 設定 Google Cloud 專案後，在專案中啟用 Google Sheets API 和 Google Drive API。如需啟用這些 API 的步驟，請參閱《適用於 Google 雲端平台的 API 主控台說明》中的[啟用和停用 API](https://support.google.com/googleapi/answer/6158841)。 1. 接著，為外部使用者設定 OAuth 同意畫面。如需 OAuth 同意畫面的詳細資訊，請參閱《Google 雲端平台主控台說明》中的[設定 OAuth 同意畫面](https://support.google.com/cloud/answer/10311615#)。 1. 在 OAuth 同意畫面中，新增下列範圍： + [Google Sheets API 唯讀範圍](https://www.googleapis.com/auth/spreadsheets.readonly) + [Google Drive API 唯讀範圍](ttps://www.googleapis.com/auth/drive.readonly) 如需有關這些範圍的詳細資訊，請參閱 Google Identity 文件中的 [Google API 的 OAuth 2.0 範圍](https://developers.google.com/identity/protocols/oauth2/scopes)。 1. 產生 OAuth 2.0 用戶端 ID 和機密。如需建立此用戶端 ID 的步驟，請參閱《Google 雲端平台主控台說明》中的[設定 OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en#zippy=)。 OAuth 2.0 用戶端 ID 必須擁有一個或多個已授權的重新導向 URL。 重新導向 URL 的格式如下： + https://.console.aws.amazon.com/gluestudio/oauth 1. 請注意 OAuth 2.0 用戶端 ID 設定中的用戶端 ID 和用戶端機密。 # Google Sheets 連接器限制 以下是 Google Sheets 連接器的限制： + Google Sheets 連接器不支援篩選條件。因此，不支援基於篩選條件的分區。 + 在基於記錄的分區中，沒有依 SAAS 傳回確切記錄計數的佈建。因此，在某些情況下，可能會建立具有空白記錄的檔案。 + 由於 Google Sheets 連接器不支援基於篩選條件的分區，因此 `partitionField`、 `lowerbound` 和 `upperbound` 不是有效的連線選項。如果提供這些選項，預期 AWS Glue 任務會失敗。 + 請務必將工作表的第一列指定為標頭列，以避免資料處理問題。 + 如果未提供，若工作表包含第一列為空白的資料，標頭列將取代為 `Unnamed:1`、`Unnamed:2`、`Unnamed:3`...。 + 如果提供標頭列，空白資料欄名稱將取代為 `Unnamed:`。例如，如果標頭列為 `['ColumnName1', 'ColumnName2', '', '', 'ColumnName5', 'ColumnName6']`，則會變成 `['ColumnName1', 'ColumnName2', 'Unnamed:3', 'Unnamed:4', 'ColumnName5', 'ColumnName6'].` + Google Sheets 連接器不支援增量傳輸。 + Google Sheets 連接器僅支援字串資料類型。 + 工作表中的重複標頭會使用數字尾碼反覆重新命名。重新命名重複的標頭時，使用者提供的標頭名稱具有優先順序。例如，如果標頭列為 ["Name", "", "Name", null, "Unnamed:6", ""]，其會變更為：["Name", "Unnamed:2", "Name1", "Unnamed:4", "Unnamed:6", "Unnamed:61"]。 + Google Sheets 連接器不支援 tabName 的空格。 + 資料夾名稱不得含有下列特殊字元： + \$1 + / # 連線至 HubSpot HubSpot 的 CRM 平台具有行銷、銷售、內容管理和客戶服務所需的所有工具和整合。 + 行銷 Hub - 可協助您擴展流量、轉換更多訪客，以及大規模執行完整集客式行銷活動的行銷軟體。 + 銷售 Hub - 銷售 CRM 軟體，可協助您更深入了解潛在客戶、自動化您擁有的任務，以及更快地完成更多交易。 + 服務 Hub - 客戶服務軟體，可協助您與客戶建立聯繫、超越期望，並將其轉換為促進業務成長的推廣者。 + 營運 Hub - 可同步您的應用程式、清理和建立客戶資料，以及自動化程序的操作軟體，因此您的所有系統和團隊都能更順暢地運作。 **Topics** + [AWS Glue 支援 HubSpot](hubspot-support.md) + [包含用於建立和使用連線的 API 操作的政策](hubspot-configuring-iam-permissions.md) + [設定 HubSpot](hubspot-configuring.md) + [設定 HubSpot 連線](hubspot-configuring-connections.md) + [從 HubSpot 實體讀取](hubspot-reading-from-entities.md) + [寫入到 HubSpot 實體](hubspot-writing-to-entities.md) + [HubSpot 連線選項](hubspot-connection-options.md) + [HubSpot 連接器的限制和備註](hubspot-connector-limitations.md) # AWS Glue 支援 HubSpot AWS Glue 支援 HubSpot，如下所示： **支援作為來源？** 是 – 同步和非同步。您可以使用 AWS Glue ETL 任務從 HubSpot 查詢資料。 **支援作為目標？** 是。您可以使用 AWS Glue ETL 任務將資料寫入 HubSpot。 **支援的 HubSpot API 版本** 支援以下 HubSpot API 版本： + v1 +   v2 + v3 + v4 如需特定版本的實體支援，請參閱 [同步來源支援的實體](hubspot-reading-from-entities.md#sync-table) 和 [非同步來源支援的實體](hubspot-reading-from-entities.md#async-table)。 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 HubSpot 您必須先符合下列要求，才能使用 從 HubSpot AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有 HubSpot 帳戶。如需詳細資訊，請參閱[建立 HubSpot 帳戶](#hubspot-configuring-creating-hubspot-account)。 + 您的 HubSpot 帳戶已啟用 API 存取。 + 您的 HubSpot 開發人員帳戶下應該有應用程式，提供用戶端登入資料，在對您的帳戶進行身分驗證呼叫時 AWS Glue ，使用 安全地存取您的資料。如需詳細資訊，請參閱[建立 HubSpot 開發人員應用程式](#hubspot-configuring-creating-hubspot-developer-app)。 如果您符合這些要求，就可以 AWS Glue 連線到 HubSpot 帳戶。對於一般連線，您無需在 HubSpot 中執行任何其他動作。 ## 建立 HubSpot 帳戶 若要建立 HubSpot 帳戶，請執行以下操作： 1. 前往 [HubSpot CRM SignUp URL](https://app.hubspot.com/login)。 1. 輸入您的電子郵件地址，然後選擇**驗證電子郵件** (或者，您可以選擇註冊 Google、Microsoft 或 Apple 帳戶)。 1. 檢查您的收件匣是否有來自 HubSpot 的驗證碼。 1. 輸入 6 位數驗證碼，然後按一下**下一步**。 1. 輸入密碼，然後按一下**下一步**。 1. 輸入您的名字和姓氏，然後按一下**下一步**，或使用**註冊 Google **連結註冊。 1. 輸入您的產業，然後按一下**下一步**。 1. 輸入您的任務角色，然後按一下**下一步**。 1. 輸入貴公司名稱，然後按一下**下一步**。 1. 選取貴公司的規模 (在貴公司工作的員工人數)，然後按一下**下一步**。 1. 輸入貴公司網站，然後按一下**下一步**。 1. 選取您的資料應託管的位置 (美國或歐洲)，然後按一下**建立帳戶**。 1. 選取您帳戶建立的目的，然後按一下**下一步**。 1. 選擇**連接 Google 帳戶**，或選擇自行新增聯絡人，以將您的聯絡人與您的 HubSpot 帳戶連結。 1. 如果您選擇**連接 Google 帳戶**選項來連結聯絡人並開始使用 HubSpot 帳戶，請登入您的 Google 帳戶。 ## 建立 HubSpot 開發人員應用程式 應用程式開發人員帳戶旨在建立和管理應用程式、整合及開發人員測試帳戶。這些也是您可以建立和管理 App Marketplace 清單的地方。不過，應用程式開發人員帳戶及其關聯的測試帳戶不會連線到標準 HubSpot 帳戶。他們無法將資料或資產同步到另一個 HubSpot 帳戶或從中同步。若要取得用戶端 ID 和用戶端機密，您可以建立開發人員帳戶。 1. 前往 https://developers.hubspot.com/ 1. 選擇**建立開發人員帳戶**，並向下捲動。 1. 系統會要求您建立應用程式開發人員帳戶、私有應用程式帳戶或 CMS 開發人員沙盒帳戶。選擇**建立應用程式開發人員帳戶**。 1. 由於您已建立 HubSpot 帳戶，可以選擇**繼續此使用者**。 1. 按一下**開始上傳**。 1. 輸入您的任務角色，然後按一下**下一步**。 1. 為您的開發人員帳戶命名並按一下**下一步**，然後按一下**略過**。 1. 選擇 **Create App (建立應用程式)**。 1. 建立應用程式後，請選擇**驗證**。 1. 在「驗證」下，記下用戶端 ID 和用戶端機密。 1. 將區域特定的**重新導向 URL** 新增為 https:*//*.console.aws.amazon.com/gluestudio/oauth。例如，為 us-east-1 區域新增 https://us-east-1.console.aws.amazon.com/gluestudio/oauth。 1. 向下捲動並查找範圍。在標題「CRM」和「標準」下，必須選取兩種類型的範圍。 1. 新增下列範圍： ``` content automation oauth crm.objects.owners.read forms tickets crm.objects.contacts.write e-commerce crm.schemas.custom.read crm.objects.custom.read sales-email-read crm.objects.custom.write crm.objects.companies.write crm.lists.write crm.objects.companies.read crm.lists.read crm.objects.deals.read crm.objects.deals.write crm.objects.contacts.read ``` 1. 按一下**儲存**，您的開發帳戶現在即可使用。 1. 向上捲動以尋找**用戶端 ID**。 1. 在相同頁面上，按一下**顯示**以取得**用戶端機密**。 ## 建立 HubSpot 開發人員測試帳戶 在應用程式開發人員帳戶內，您可以建立開發人員測試帳戶來測試應用程式和整合，而不會影響任何真實的 HubSpot 資料。開發人員測試帳戶不會鏡像生產帳戶，而是可以存取企業版行銷、銷售、服務、CMS 和營運中樞的 90 天試用版，提供測試大多數 HubSpot 工具和 API 的能力。 1. 按一下**首頁**。 1. 按一下**建立測試帳戶**。 1. 按一下**建立應用程式測試帳戶**。 1. 新視窗隨即出現。輸入應用程式測試帳戶名稱，然後按一下**建立**。 您的應用程式測試帳戶現在已建立。 **注意** 開發人員帳戶與 API 整合等開發活動相關，而應用程式測試帳戶用於查看開發人員帳戶建立或提取的資料。 # 設定 HubSpot 連線 HubSpot 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。建立連線的使用者需要為 HubSpot 用戶端應用程式提供 OAuth 相關資訊，例如用戶端 ID 和用戶端機密。 AWS Glue 主控台會將使用者重新導向至 HubSpot，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 HubSpot 執行個體。 + 使用者仍然可以選擇在 HubSpot 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 HubSpot 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需為授權碼 OAuth 流建立連接應用程式的公有 HubSpot 文件，請參閱[公有應用程式](https://developers.hubspot.com/docs/api/creating-an-app)。 如需設定 HubSpot 連線，請執行以下操作： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：必須在 AWS Glue中建立連線機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 在選取**連線類型**時，選取 HubSpot。 1. 提供 HubSpot 環境。 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`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 HubSpot 實體讀取 **必要條件** 您要從中讀取的 HubSpot 物件。您將需要物件名稱，例如聯絡人或任務。下表顯示 Sync 來源支援的實體。 ## 同步來源支援的實體 | 實體 | API 版本 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | 行銷活動 | v1 | 否 | 是 | 否 | 是 | 否 | | 公司 | v3 | 是 | 是 | 是 | 是 | 是 | | 聯絡人 | v3 | 是 | 是 | 是 | 是 | 是 | | 聯絡人清單 | v1 | 否 | 是 | 否 | 是 | 否 | | 交易 | v3 | 是 | 是 | 是 | 是 | 是 | | CRM 管道 (交易管道) | v1 | 否 | 否 | 否 | 是 | 否 | | 電子郵件事件 | v1 | 否 | 是 | 否 | 是 | 否 | | 呼叫 | v3 | 是 | 是 | 是 | 是 | 是 | | 備註 | v3 | 是 | 是 | 是 | 是 | 是 | | 電子郵件 | v3 | 是 | 是 | 是 | 是 | 是 | | 會議 | v3 | 是 | 是 | 是 | 是 | 是 | | 任務​ | v3 | 是 | 是 | 是 | 是 | 是 | | 郵政郵件 | v3 | 是 | 是 | 是 | 是 | 是 | | 自訂物件 | v3 | 是 | 是 | 是 | 是 | 是 | | 表單 |   v2 | 否 | 否 | 否 | 是 | 否 | | 擁有者 | v3 | 否 | 是 | 否 | 是 | 否 | | 產品 | v3 | 是 | 是 | 是 | 是 | 是 | | 票證 | v3 | 是 | 是 | 是 | 是 | 是 | | 工作流程 | v3 | 否 | 否 | 否 | 是 | 否 | | 關聯 | v4 | 是 | 否 | 否 | 是 | 否 | | 關聯標籤 | v4 | 否 | 否 | 否 | 是 | 否 | **範例**： ``` hubspot_read = glueContext.create_dynamic_frame.from_options( connection_type="hubspot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "contact", "API_VERSION": "v3" } ``` ## 非同步來源支援的實體 | 實體 | API 版本 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | 公司 | v3 | 是 | 否 | 是 | 是 | 否 | | 聯絡人 | v3 | 是 | 否 | 是 | 是 | 否 | | 交易 | v3 | 是 | 否 | 是 | 是 | 否 | | 呼叫 | v3 | 是 | 否 | 是 | 是 | 否 | | 備註 | v3 | 是 | 否 | 是 | 是 | 否 | | 電子郵件 | v3 | 是 | 否 | 是 | 是 | 否 | | 會議 | v3 | 是 | 否 | 是 | 是 | 否 | | 任務​ | v3 | 是 | 否 | 是 | 是 | 否 | | 郵政郵件 | v3 | 是 | 否 | 是 | 是 | 否 | | 自訂物件 | v3 | 是 | 否 | 是 | 是 | 否 | | 產品 | v3 | 是 | 否 | 是 | 是 | 否 | | 票證 | v3 | 是 | 否 | 是 | 是 | 否 | **範例**： ``` hubspot_read = glueContext.create_dynamic_frame.from_options( connection_type="hubspot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "contact", "API_VERSION": "v3", "TRANSFER_MODE": "ASYNC" } ``` **HubSpot 實體和欄位詳細資訊**： **HubSpot API v4**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) **注意** 針對 `Associations` 物件，若要擷取兩個物件之間的關聯，您需要在建立 AWS Glue 任務時，透過強制性篩選條件提供 'from Id' （第一個物件的 ID)。在這種情況下，如果您想要擷取多個 ID 的關聯，則必須在 `where` 子句中提供多個 ID。例如：若要擷取聯絡人 ID '1' 和 '151' 的`Associations`，您需要提供一個篩選條件，如 `where id=1 AND id=151`。 **HubSpot API v3**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) 對於下列實體，HubSpot 會提供端點來動態擷取中繼資料，以便在每個實體的資料類型層級擷取運算子支援。 **注意** `DML_STATUS` 是在執行時期新增至每個記錄的虛擬欄位，以判斷其在同步模式中的狀態 (CREATED/UPDATED)。非同步模式不支援 `CONTAINS/LIKE` 運算子。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) **HubSpot API v2**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) **HubSpot API v1**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，接受 ISO 格式的值。 有效值的範例： ``` “2024-01-01T10:00:00.115Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 下表說明實體分區欄位支援詳細資訊： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html) 範例： ``` hubspot_read = glueContext.create_dynamic_frame.from_options( connection_type="hubspot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "company", "API_VERSION": "v3", "PARTITION_FIELD": "hs_object_id" "LOWER_BOUND": "50" "UPPER_BOUND": "16726619290" "NUM_PARTITIONS": "10" } ``` # 寫入到 HubSpot 實體 ## 先決條件 + 您要寫入到的 HubSpot 物件。將需要物件名稱，例如聯絡人或票證。 + HubSpot 連接器支援下列寫入操作： + INSERT + UPDATE + 使用 `UPDATE` 寫入操作時，必須提供 `ID_FIELD_NAMES` 選項來指定記錄的 ID 欄位。 ## 同步目的地的支援實體 | 實體 | API 版本 | 將支援為目的地連接器 | 可以插入 | 可以更新 | | --- | --- | --- | --- | --- | | 公司 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 聯絡人 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 交易 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 產品 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 呼叫 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 會議 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 備註 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 電子郵件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 任務​ | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 郵政郵件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 自訂物件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 票證 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) | | 關聯 | v4 | 是 | 是 (單一、大量) | 否 | | 關聯標籤 | v4 | 是 | 是 (單一、大量) | 是 (單一、大量) | **範例**： **INSERT 操作** ``` hubspot_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="hubspot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "contact", "API_VERSION": "v3", "WRITE_OPERATION": "INSERT" } ) ``` **UPDATE 操作** ``` hubspot_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="hubspot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "deal", "API_VERSION": "v3", "WRITE_OPERATION": "UPDATE", "ID_FIELD_NAMES": "hs_object_id" } ) ``` # HubSpot 連線選項 以下是 HubSpot 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。HubSpot 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 HubSpot Rest API 版本。例如：v1、v2、v3、v4。 + `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。用於讀取。要讀取的分區數目。 + `TRANSFER_MODE`(String) - 用於指示是否應在非同步模式下執行查詢。 + `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT 或 UPDATE。 + `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 的必要項目。 # HubSpot 連接器的限制和備註 以下是 HubSpot 連接器的限制或備註： + 任何指定查詢的搜尋端點總結果限制為 1 萬個。任何超過 1 萬筆記錄的分區區都會導致 400 錯誤。 + 連接器的其他重要限制如[限制](https://developers.hubspot.com/docs/api/crm/search#limitations)中所述。 + HubSpot 最多接受三個篩選陳述式。 + 目前，HubSpot 支援標準 HubSpot 物件 (例如聯絡人、公司、交易或票證) 與自訂物件之間的關聯。 + 對於免費帳戶：每個物件配對 (例如聯絡人和公司) 之間最多只能建立 10 個關聯類型。 + 對於超級管理員帳戶：每個物件配對之間最多只能建立 50 個關聯類型。 + 如需詳細資訊，請參閱[關聯 v4](https://developers.hubspot.com/docs/api/crm/) 和[建立和使用關聯標籤](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels)。 + 關聯中不存在 'Quote' 和 'Communications' 物件，因為連接器目前不對其進行支援。 + 對於非同步，SaaS 只會以遞增順序排序值。 + 對於 `Ticket` 實體，SaaS 不會以非同步模式傳回 `hs_object_id` 欄位。 # 連線至 Instagram Ads Instagram 是熱門的相片分享應用程式，可讓您與品牌、名人、思維領導者、朋友、家人等聯繫。其是一種相片分享和社交聯網服務。使用者可以拍攝相片或短片，並與其追隨者分享。Instagram 廣告是企業可以付費為 Instagram 使用者提供服務的貼文。 **Topics** + [AWS Glue 支援 Instagram 廣告](instagram-ads-support.md) + [包含用於建立和使用連線的 API 操作的政策](instagram-ads-configuring-iam-permissions.md) + [設定 Instagram Ads](instagram-ads-configuring.md) + [設定 Instagram Ads 連線](instagram-ads-configuring-connections.md) + [從 Instagram Ads 實體中讀取](instagram-ads-reading-from-entities.md) + [Instagram Ads 連線選項](instagram-ads-connection-options.md) + [Instagram Ads 連接器的限制和備註](instagram-ads-connector-limitations.md) # AWS Glue 支援 Instagram 廣告 AWS Glue 支援 Instagram 廣告，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Instagram Ads 查詢資料。 **支援作為目標？** 否。 **支援的 Instagram Ads API 版本** 支援以下 Instagram Ads API 版本： + v17.0 + v18.0 + v19.0 + v20.0 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Instagram Ads 您必須先符合下列要求，才能使用 從 Instagram 廣告 AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 可以透過 Facebook 間接存取 Instagram Standard 帳戶。 + 需要使用者身分驗證才能產生存取字符。 + Instagram Ads SDK 連接器將實作*使用者存取字符 OAuth* 流程。 + 我們使用 OAuth2.0 來驗證對 Instagram Ads 的 API 請求。此 Web 型身分驗證屬於多重要素驗證 (MFA) 架構，其是 2FA 的超集。 + 使用者需要授權許可，才能存取端點。為了存取使用者的資料，可透過[許可](https://developers.facebook.com/docs/permissions)和[功能](https://developers.facebook.com/docs/features-reference)來處理端點授權。 ## 取得 OAuth 2.0 憑證 若要取得 API 憑證，以便對執行個體進行已驗證的呼叫，請參閱 [Graph API](https://developers.facebook.com/docs/graph-api/)。 # 設定 Instagram Ads 連線 Instagram Ads 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者可以選擇在 Instagram Ads 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Instagram 廣告以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生存取字符。過期的系統使用者字符自產生或重新整理之日起 60 天內有效。若要建立連續性，開發人員應在 60 天內重新整理存取字符。否則會導致存取字符被沒收，並且需要開發人員獲取新的存取字符才能重新獲取 API 存取權。請參閱[重新整理存取字符](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)。 若要設定 Instagram Ads 連線： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Instagram Ads。 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. 提供使用者管理的用戶端應用程式用戶端 ID。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。選取的機密需要具有值為連線應用程式中用戶端機密的金鑰 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 Instagram Ads 實體中讀取 **必要條件** 您想要從中讀取的 Instagram Ads 物件。將需要物件名稱。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | 是 | 是 | 否 | 是 | 是 | | 廣告集 | 是 | 是 | 否 | 是 | 是 | | 廣告 | 是 | 是 | 否 | 是 | 是 | | 廣告創意 | 否 | 是 | 否 | 是 | 否 | | Insights - 帳戶 | 否 | 是 | 否 | 是 | 否 | | 廣告影像 | 是 | 是 | 否 | 是 | 否 | | Insights - 廣告 | 是 | 是 | 否 | 是 | 是 | | Insights - 廣告集 | 是 | 是 | 否 | 是 | 是 | | Insights - 行銷活動 | 是 | 是 | 否 | 是 | 是 | **範例**： ``` instagramAds_read = glueContext.create_dynamic_frame.from_options( connection_type="instagramads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0" } ``` ## Instagram Ads 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [行銷活動](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group) + [廣告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign) + [廣告](https://developers.facebook.com/docs/marketing-api/reference/adgroup) + [廣告創意](https://developers.facebook.com/docs/marketing-api/reference/ad-creative) + [廣告帳戶深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights) + [廣告影像](https://developers.facebook.com/docs/marketing-api/reference/ad-image) + [廣告深入分析](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/) + [廣告集深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights) + [行銷活動深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights) 如需詳細資訊，請參閱[行銷 API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)。 **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。 ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值範例： ``` "2022-01-01T00:00:00.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 有效值範例： ``` "2024-01-02T00:00:00.000Z" ``` + `NUM_PARTITIONS`：分區數目。 範例： ``` instagramADs_read = glueContext.create_dynamic_frame.from_options( connection_type="instagramads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0", "PARTITION_FIELD": "created_time" "LOWER_BOUND": "2022-01-01T00:00:00.000Z" "UPPER_BOUND": "2024-01-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # Instagram Ads 連線選項 以下是 Instagram Ads 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Instagram Ads 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Instagram Ads Graph API 版本。例如：v21。 + `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。用於讀取。要讀取的分區數目。 # Instagram Ads 連接器的限制和備註 以下是 Instagram Ads 連接器的限制或備註： + 應用程式的呼叫計數是使用者在滾動一小時時段 200 期間可以進行的呼叫次數乘以使用者數目。如需速率限制詳細資訊，請參閱[速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)與[商業使用案例速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)。 # 在 AWS Glue Studio 中連線至 Intercom Intercom 是互動作業系統，是您的企業和客戶之間的開放管道 (在產品內部、關鍵時刻，並始終尊重客戶的意願)，從而創造一種持續的對話，讓您充分利用客戶旅程中的每次互動。 **Topics** + [AWS Glue 對內部通訊的支援](intercom-support.md) + [包含用於建立和使用連線的 API 操作的政策](intercom-configuring-iam-permissions.md) + [設定 Intercom](intercom-configuring.md) + [設定 Intercom 連線](intercom-configuring-connections.md) + [從 Intercom 實體中讀取](intercom-reading-from-entities.md) + [Intercom 連線選項](intercom-connection-options.md) + [限制](intercom-limitations.md) + [建立新的 Intercom 帳戶並設定用戶端應用程式](intercom-new-account-creation.md) # AWS Glue 對內部通訊的支援 AWS Glue 支援內部通訊，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從內部通訊查詢資料。 **支援作為目標？** 否。 **支援的 Intercom API 版本** v2.5。如需特定版本的實體支援，請參閱 [從 Intercom 實體中讀取](intercom-reading-from-entities.md)。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策描述建立和使用連線所需的 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 Amazon CloudWatch Logs、IAM 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。 + [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接到的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。 # 設定 Intercom 您必須先符合下列要求，才能使用 從內部通訊 AWS Glue 傳輸： ## 最低需求 + 您擁有一個 Intercom 帳戶。如需詳細資訊，請參閱[建立新的 Intercom 帳戶並設定用戶端應用程式](intercom-new-account-creation.md)。 + 您的 Intercom 帳戶已啟用 API 存取。 + 您應該在內部通訊開發人員帳戶下擁有應用程式，提供用戶端登入資料，該登入資料可在對您的帳戶進行驗證呼叫時， AWS Glue 使用 安全地存取您的資料。如需詳細資訊，請參閱「Intercom - 新帳戶和用戶端應用程式建立步驟」。 如果您符合這些要求，就可以 AWS Glue 連線到您的內部通訊帳戶。 # 設定 Intercom 連線 Intercom 支援 OAuth 2 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Google Ads，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其內部通訊執行個體。 透過 AWS Glue 主控台建立連線時，使用者應提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至內部通訊以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需有關為授權碼 OAuth 流程建立連線應用程式的詳細資訊，請參閱 [Ads API](https://developers.intercom.com/building-apps/docs/setting-up-oauth)。 若要設定 Intercom 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於客戶管理的連線應用程式，機密應包含連線的應用程式存取字符、重新整理字符、用戶端 ID 和用戶端機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Intercom。 1. 提供 Intercom 環境。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Intercom 實體中讀取 **先決條件** + 您想要從中進行讀取的 Intercom 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | API\$1Version | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | 管理員 | v2.5 | 否 | 否 | 否 | 是 | 否 | | 公司 | v2.5 | 否 | 是 | 否 | 是 | 否 | | 對話 | v2.5 | 是 | 是 | 是 | 是 | 是 | | 資料屬性 | v2.5 | 否 | 否 | 否 | 是 | 否 | | 聯絡人 | v2.5 | 是 | 是 | 是 | 是 | 是 | | 客群 | v2.5 | 否 | 否 | 否 | 是 | 否 | | Tags (標籤) | v2.5 | 否 | 否 | 否 | 是 | 否 | | 團隊 | v2.5 | 否 | 否 | 否 | 是 | 否 | **範例** ``` Intercom_read = glueContext.create_dynamic_frame.from_options( connection_type="Intercom", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "company", "API_VERSION": "V2.5" } ) ``` **Intercom 實體和欄位詳細資訊** | 實體 | 欄位 | 資料類型 | 支援的運算子 | | --- | --- | --- | --- | | 管理員 | type | String | NA | | 管理員 | id | String | NA | | 管理員 | avatar | Struct | NA | | 管理員 | name | String | NA | | 管理員 | email | String | NA | | 管理員 | away\$1mode\$1enabled | Boolean | NA | | 管理員 | away\$1mode\$1reassign | Boolean | NA | | 管理員 | has\$1inbox\$1seat | Boolean | NA | | 管理員 | team\$1ids | 清單 | NA | | 管理員 | job\$1title | String | NA | | 公司 | type | String | NA | | 公司 | id | String | NA | | 公司 | app\$1id | String | NA | | 公司 | created\$1at | DateTime | NA | | 公司 | remote\$1created\$1at | DateTime | NA | | 公司 | updated\$1at | DateTime | NA | | 公司 | last\$1request\$1at | DateTime | NA | | 公司 | plan | Struct | NA | | 公司 | company\$1id | String | NA | | 公司 | name | String | NA | | 公司 | custom\$1attributes | Struct | NA | | 公司 | session\$1count | Integer | NA | | 公司 | monthly\$1spend | Integer | NA | | 公司 | user\$1count | Integer | NA | | 公司 | industry | String | NA | | 公司 | size | Integer | NA | | 公司 | website | String | NA | | 公司 | 標籤 | Struct | NA | | 公司 | segments | Struct | NA | | 聯絡人 | id | String | EQUAL\$1TO.NOT\$1EQUAL\$1TO | | 聯絡人 | type | String | NA | | 聯絡人 | workspace\$1id | String | NA | | 聯絡人 | external\$1id | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | role | String | EQUAL\$1TO.NOT\$1EQUAL\$1TO | | 聯絡人 | email | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | phone | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | name | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | avatar | String | NA | | 聯絡人 | owner\$1id | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | social\$1profiles | Struct | NA | | 聯絡人 | has\$1hard\$1bounced | Boolean | EQUAL\$1TO | | 聯絡人 | marked\$1email\$1as\$1spam | Boolean | EQUAL\$1TO | | 聯絡人 | unsubscribed\$1from\$1emails | Boolean | EQUAL\$1TO | | 聯絡人 | created\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | updated\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | signed\$1up\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | last\$1seen\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | last\$1replied\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | last\$1contacted\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | last\$1email\$1opened\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | last\$1email\$1clicked\$1at | DateTime | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 聯絡人 | language\$1override | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | browser | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | browser\$1version | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | 瀏覽器\$1語言 | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | os | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | location | Struct | NA | | 聯絡人 | location\$1country | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | location\$1region | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | location\$1city | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | android\$1app\$1name | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | android\$1app\$1version | String | NA | | 聯絡人 | android\$1device | String | NA | | 聯絡人 | android\$1os\$1version | String | NA | | 聯絡人 | android\$1sdk\$1version | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | android\$1last\$1seen\$1at | Date | NA | | 聯絡人 | ios\$1app\$1name | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | ios\$1app\$1version | String | NA | | 聯絡人 | ios\$1device | String | NA | | 聯絡人 | ios\$1os\$1version | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | ios\$1sdk\$1version | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 聯絡人 | ios\$1last\$1seen\$1at | DateTime | NA | | 聯絡人 | custom\$1attributes | Struct | NA | | 聯絡人 | 標籤 | Struct | NA | | 聯絡人 | notes | Struct | NA | | 聯絡人 | 公司 | Struct | NA | | 聯絡人 | unsubscribed\$1from\$1sms | Boolean | NA | | 聯絡人 | sms\$1consent | Boolean | NA | | 聯絡人 | opted\$1out\$1subscription\$1types | Struct | NA | | 聯絡人 | referrer | String | NA | | 聯絡人 | utm\$1campaign | String | NA | | 聯絡人 | utm\$1content | String | NA | | 聯絡人 | utm\$1medium | String | NA | | 聯絡人 | utm\$1source | String | NA | | 聯絡人 | utm\$1term | String | NA | | 對話 | type | String | NA | | 對話 | id | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | created\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | updated\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | source | Struct | NA | | 對話 | source\$1id | String | EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1type | String | EQUAL\$1TO, NOT\$1EQUAL\$1TO, | | 對話 | source\$1delivered\$1as | String | EQUAL\$1TO, NOT\$1EQUAL\$1TO, | | 對話 | source\$1subject | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1body | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1author\$1id | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1author\$1type | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1author\$1name | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1author\$1email | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | source\$1url | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | 聯絡人 | Struct | NA | | 對話 | 隊友 | Struct | NA | | 對話 | 標題 | String | NA | | 對話 | admin\$1assignee\$1id | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | team\$1assignee\$1id | Integer | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | custom\$1attributes | Struct | NA | | 對話 | 開啟 | Boolean | EQUAL\$1TO | | 對話 | state | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | 讀取 | Boolean | EQUAL\$1TO | | 對話 | waiting\$1since | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | snoozed\$1until | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | 標籤 | Struct | NA | | 對話 | first\$1contact\$1reply | Struct | NA | | 對話 | priority | String | EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | topics | Struct | NA | | 對話 | sla\$1applied | Struct | NA | | 對話 | conversation\$1rating | Struct | NA | | 對話 | conversation\$1rating\$1requested\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | conversation\$1rating\$1replied\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | conversation\$1rating\$1score | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | conversation\$1rating\$1remark | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | conversation\$1rating\$1contact\$1id | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | conversation\$1rating\$1admin\$1id | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | 統計資訊 | Struct | NA | | 對話 | statistics\$1time\$1to\$1assignment | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1time\$1to\$1admin\$1reply | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1time\$1to\$1first\$1close | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1time\$1to\$1last\$1close | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1median\$1time\$1to\$1reply | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1first\$1contact\$1reply\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1first\$1assignment\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1first\$1admin\$1reply\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1first\$1close\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1assignment\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1assignment\$1admin\$1reply\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1contact\$1reply\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1admin\$1reply\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1close\$1at | DateTime | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1last\$1closed\$1by\$1id | String | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO | | 對話 | statistics\$1count\$1reopens | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1count\$1assignments | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | statistics\$1count\$1conversation\$1parts | Integer | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN | | 對話 | conversation\$1parts | 清單 | NA | | 資料屬性 | id | Integer | NA | | 資料屬性 | type | String | NA | | 資料屬性 | 模型 | String | NA | | 資料屬性 | name | String | NA | | 資料屬性 | full\$1name | String | NA | | 資料屬性 | label | String | NA | | 資料屬性 | 描述 | String | NA | | 資料屬性 | data\$1type | String | NA | | 資料屬性 | options | 清單 | NA | | 資料屬性 | api\$1writable | Boolean | NA | | 資料屬性 | ui\$1writable | Boolean | NA | | 資料屬性 | 自訂 | Boolean | NA | | 資料屬性 | archived | Boolean | NA | | 資料屬性 | created\$1at | Boolean | NA | | 資料屬性 | updated\$1at | DateTime | NA | | 資料屬性 | admin\$1id | String | NA | | 客群 | type | String | NA | | 客群 | id | String | NA | | 客群 | name | String | NA | | 客群 | created\$1at | DateTime | NA | | 客群 | updated\$1at | DateTime | NA | | 客群 | person\$1type | String | NA | | 客群 | count | Integer | NA | | Tags (標籤) | type | String | NA | | Tags (標籤) | id | String | NA | | Tags (標籤) | name | String | NA | | 團隊 | type | String | NA | | 團隊 | id | String | NA | | 團隊 | name | String | NA | | 團隊 | admin\$1ids | 清單 | NA | **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示。 | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 聯絡人 | created\$1at, updated\$1at,last\$1seen\$1at | DateTime | | 對話 | id | Integer | | 對話 | created\$1at, updated\$1at | DateTime | **範例** ``` Intercom_read = glueContext.create_dynamic_frame.from_options( connection_type="Intercom", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversation", "API_VERSION": "V2.5", "PARTITION_FIELD": "created_at" "LOWER_BOUND": "2022-07-13T07:55:27.065Z" "UPPER_BOUND": "2022-08-12T07:55:27.065Z" "NUM_PARTITIONS": "2" } ) ``` # Intercom 連線選項 以下是 Intercom 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Intercom 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Intercom Rest API 版本。範例：v2.5。 + `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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - 使用者想要執行操作之執行個體的 URL。例如：[https://api.intercom.io](https://api.intercom.io)。 # 限制 以下是 Intercom 連接器的限制： + 使用公司實體時，最多可傳回 10,000 家公司。如需詳細資訊，請參閱[列出所有的公司 API](https://developers.intercom.com/docs/references/2.5/rest-api/companies/list-companies)。 + 套用排序依據時，**聯絡人**和**對話**實體都必須進行篩選。 + SaaS 提供商支援 MCA。不過，根據文件中提到的 API 速率限制，我們不會在 上託管 MCA， AWS Glue 因為這可能會影響其他工作負載，並可能導致資源爭用造成效能問題。 # 建立新的 Intercom 帳戶並設定用戶端應用程式 **建立 Intercom 帳戶** 1. 在 [Intercom URL](https://app.intercom.com/) 上進行選擇，並選擇頁面右上角的**開始我的免費試用**。 1. 選擇頁面右上角的**免費試用按鈕**。 1. 選擇需要的業務類型。 1. 在頁面上輸入要求的資訊。 1. 輸入所有資訊後，選擇**註冊**。 **建立 Intercom 開發人員應用程式** 若要取得**用戶端 ID** 和**用戶端機密**，可建立開發人員帳戶。 1. 導覽至 [https://app.intercom.com/](https://app.intercom.com/)。 1. 輸入電子郵件 ID 和密碼/使用 Google 註冊並登入。 1. 選擇左下角的**使用者設定檔**，並選擇設定。 1. 選擇**應用程式與整合**。 1. 選擇**應用程式與整合**下的**開發人員中心**索引標籤。 1. 選擇**新增應用程式**，並在此處建立應用程式。 1. 提供應用程式名稱，並選擇**建立**應用程式。 1. 在應用程式中，導覽至**身分驗證**區段。 1. 選擇**編輯**並新增重新導向 URI。將區域特定的重新導向 URL 新增為 `https://.console.aws.amazon.com/gluestudio/oauth`。例如，新增 `https://us-east-1.console.aws.amazon.com/gluestudio/oauth for the us-east-1 region`。 1. 在基本資訊區段中獲取產生的**用戶端 ID** 和**用戶端機密**。 # 連線至 Jira Cloud Jira Cloud 是由 Atlassian 開發的平台。平台包含問題追蹤產品，可協助團隊規劃和追蹤敏捷專案。身為 Jira Cloud 使用者，您的帳戶包含專案的資料，例如問題、工作流程和事件。您可以使用 AWS Glue 將 Jira Cloud 資料傳輸至特定 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Jira Cloud](jira-cloud-support.md) + [包含用於建立和使用連線的 API 操作的政策](jira-cloud-configuring-iam-permissions.md) + [設定 Jira Cloud](jira-cloud-configuring.md) + [設定 Jira Cloud 連線](jira-cloud-configuring-connections.md) + [從 Jira Cloud 實體中讀取](jira-cloud-reading-from-entities.md) + [Jira Cloud 連線選項](jira-cloud-connection-options.md) + [Jira Cloud 連接器的限制和備註](jira-cloud-connector-limitations.md) # AWS Glue 支援 Jira Cloud AWS Glue 支援 Jira Cloud，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Jira Cloud 查詢資料。 **支援作為目標？** 否。 **支援的 Jira Cloud API 版本** 支援下列 Jira Cloud API 版本： + v3 如需特定版本的實體支援，請參閱 [從 Jira Cloud 實體中讀取](jira-cloud-reading-from-entities.md)。 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Jira Cloud 您必須先符合下列要求，才能使用 AWS Glue 將資料從 Jira Cloud 傳輸到支援的目的地： ## 最低需求 以下是最低要求： + 您有一個 Atlassian 帳戶，可以在 Jira Cloud 中使用 Jira 軟體產品。如需詳細資訊，請參閱[建立 Jira Cloud 帳戶](#jira-cloud-configuring-creating-jira-cloud-account)。 + 您必須建立具有服務存取權 AWS 的帳戶 AWS Glue。 + 此應用程式提供用戶端登入資料，在對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱 Atlassian Developer 文件中的[啟用 OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-)。 如果您符合這些要求，就可以 AWS Glue 連線到 Jira Cloud 帳戶。 ## 建立 Jira Cloud 帳戶 若要建立 Jira Cloud 帳戶： 1. 導覽至 [Atlassian 註冊 URL](https://id.atlassian.com/signup)。 1. 輸入您的工作電子郵件和名稱，然後選擇**同意**。您會收到驗證電子郵件。 1. 驗證電子郵件後，可以建立密碼，然後選擇**註冊**。 1. 輸入名稱和密碼，然後選擇**註冊**。 1. 系統會將您重新導向至您需要輸入網站的頁面。輸入網站名稱，並選擇**同意**。 Atlassian Cloud 網站啟動之後，就可以根據專案類型偏好設定回答幾個問題來設定 Jira。 若要登入現有帳戶： 1. 導覽至 [Atlassian 登入 URL](https://id.atlassian.com/login) 並輸入憑證。 1. 輸入電子郵件和密碼，然後按一下**登入**。系統會重新導向至 Jira 儀表板。 ## 在 Jira Cloud 中建立應用程式 若要在 Jira Cloud 中建立應用程式，並從受管用戶端應用程式中獲取用戶端 ID 和用戶端機密： 1. 導覽至 [Jira Cloud URL](https://id.atlassian.com/login) 並輸入憑證。 1. 選擇**建立**並選取 **OAuth 2.0 整合**選項。 1. 輸入應用程式名稱，選中 **T&C**，然後選擇**建立**。 1. 導覽至左側功能表中的**發布**區段，然後選擇**編輯**。 1. 在**編輯發布控制項**區段中： 1. 選取**發布狀態**為**共用**。 1. 輸入廠商名稱。 1. 輸入**隱私權政策**的 URL。例如，https://docs.aws.amazon.com/glue/latest/dg/security-iam-awsmanpol.html 1. 輸入**服務條款**的 URL (選用)。 1. 輸入**客戶支援聯絡人**的 URL (選用)。 1. 從**個人資料宣告**中選取「是/否」，然後選擇**儲存變更**。 1. 導覽至各自應用程式左側功能表中的**許可**。 1. 對於 **Jira API**，選擇**新增**。新增之後，選擇**組態**選項。 1. 在**傳統範圍** > **Jira 平台 REST API** 區段下，選擇**編輯範圍**並檢查所有範圍。按一下 **Save (儲存)**。 1. 在**精細範圍**下，選擇**編輯範圍**，然後選取下列範圍： 1. 向下捲動並查找範圍。在標題「CRM」和「標準」下，必須選取兩種類型的範圍。 1. 新增下列範圍： ``` read:application-role:jira read:audit-log:jira read:avatar:jira read:field:jira read:group:jira read:instance-configuration:jira read:issue-details:jira read:issue-event:jira read:issue-link-type:jira read:issue-meta:jira read:issue-security-level:jira read:issue-security-scheme:jira read:issue-type-scheme:jira read:issue-type-screen-scheme:jira read:issue-type:jira read:issue.time-tracking:jira read:label:jira read:notification-scheme:jira read:permission:jira read:priority:jira read:project:jira read:project-category:jira read:project-role:jira read:project-type:jira read:project-version:jira read:project.component:jir read:project.property:jira read:resolution:jira read:screen:jira read:status:jira read:user:jira read:workflow-scheme:jira read:workflow:jira read:field-configuration:jira read:issue-type-hierarchy:jira read:webhook:jira ``` 1. 導覽至左側功能表中的**身分驗證**，然後選擇**新增**。 1. 輸入**回呼 URL**，例如 https://us-east-1.console.aws.amazon.com/gluestudio/oauth 1. 導覽至左側功能表中的**設定**，向下捲動以取得**身分驗證**詳細資訊。記下用戶端 ID 和機密。 # 設定 Jira Cloud 連線 Jira Cloud 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 AWS Glue 主控台會將使用者重新導向至 Jira Cloud，其中使用者必須登入並允許 AWS Glue 請求的許可存取其 Jira Cloud 執行個體。 + 使用者仍然可以選擇在 Jira Cloud 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Jira Cloud 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 Jira Cloud 文件，請參閱[啟用 OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-)。 若要設定 Jira Cloud 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：必須在 AWS Glue中建立連線機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Jira Cloud。 1. 提供 Jira Cloud 環境。 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`。 # 從 Jira Cloud 實體中讀取 **必要條件** 您想要從中讀取的 Jira Cloud 物件。需要物件名稱，例如稽核記錄或問題。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 稽核記錄 | 是 | 是 | 否 | 是 | 是 | | 問題 | 是 | 是 | 否 | 是 | 是 | | 問題欄位 | 否 | 否 | 否 | 是 | 否 | | 問題欄位組態 | 是 | 是 | 否 | 是 | 是 | | 問題連結類型 | 否 | 否 | 否 | 是 | 否 | | 問題通知結構描述 | 是 | 是 | 否 | 是 | 是 | | 問題安全結構描述 | 否 | 否 | 否 | 是 | 否 | | 問題類型結構描述 | 是 | 是 | 是 | 是 | 是 | | 問題類型螢幕結構描述 | 是 | 是 | 是 | 是 | 是 | | 問題類型 | 否 | 否 | 否 | 是 | 否 | | Jira 設定 | 是 | 否 | 否 | 是 | 否 | | Jira 進階設定 | 否 | 否 | 否 | 是 | 否 | | Jira 全域設定 | 否 | 否 | 否 | 是 | 否 | | 標籤 | 否 | 否 | 否 | 是 | 是 | | 我自己 | 是 | 否 | 否 | 是 | 否 | | 權限 | 否 | 否 | 否 | 是 | 否。 | | 專案 | 是 | 是 | 是 | 是 | 是 | | 專案類別 | 否 | 否 | 否 | 是 | 否 | | 專案類型 | 否 | 否 | 否 | 是 | 否 | | 伺服器資訊 | 否 | 否 | 否 | 是 | 否 | | 使用者 | 否 | 否 | 否。 | 是 | 否 | | 工作流程 | 是 | 是 | 是 | 是 | 是 | | 工作流程結構描述 | 否 | 是 | 否 | 是 | 是 | | 工作流程結構描述專案關聯 | 是 | 否 | 否 | 是 | 否 | | 工作流程狀態 | 否 | 否 | 否 | 是 | 否 | | 工作流程狀態類別 | 否 | 否 | 否 | 是 | 否 | **範例**： ``` jiracloud_read = glueContext.create_dynamic_frame.from_options( connection_type="JiraCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "audit-record", "API_VERSION": "v3" } ``` **Jira Cloud 實體和欄位詳細資訊**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/jira-cloud-reading-from-entities.html) ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `NUM_PARTITIONS`：分區數目。 範例： ``` jiraCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="JiraCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "issue", "API_VERSION": "v3", "NUM_PARTITIONS": "10" } ``` # Jira Cloud 連線選項 以下是 Jira Cloud 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Jira Cloud 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Jira Cloud Rest API 版本。例如：v3。 + `DOMAIN_URL`(String) - (必要) 您要使用的 Jira Cloud ID。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # Jira Cloud 連接器的限制和備註 以下是 Jira Cloud 連接器的限制或備註： + `Contains` 運算子不會使用 `String`資料類型的 `resourceName` 欄位。 + 根據預設，如果未套用明確的篩選條件，則只會爬取過去 30 天的問題。使用者可以透過指定自訂篩選條件來覆寫此預設篩選條件。 # 連線至 Kustomer Kustomer 是一個功能強大的客戶體驗平台，可將您更好地服務客戶所需的一切整合到一個易於使用的工具中。 **Topics** + [AWS Glue 支援 Kustomer](kustomer-support.md) + [包含用於建立和使用連線的 API 操作的政策](kustomer-configuring-iam-permissions.md) + [設定 Kustomer](kustomer-configuring.md) + [設定 Kustomer 連線](kustomer-configuring-connections.md) + [從 Kustomer 實體中讀取](kustomer-reading-from-entities.md) + [Kustomer 連線選項](kustomer-connection-options.md) + [Kustomer 限制](kustomer-connection-limitations.md) # AWS Glue 支援 Kustomer AWS Glue 支援 Kustomer，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Kustomer 查詢資料。 **支援作為目標？** 否。 **支援的 Kustomer API 版本** 支援下列 Kustomer 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 主控台的使用者。 # 設定 Kustomer 您必須先符合下列要求，才能使用 AWS Glue 將資料從 Kustomer 傳輸到支援的目的地： ## 最低需求 以下是最低要求： + 您有一個 Kustomer 帳戶，其中包含您要傳輸的資料。 + 在帳戶設定中，您已建立 API 金鑰。如需詳細資訊，請參閱[建立 API 金鑰](#kustomer-configuring-creating-an-api-key)。 + 您可以在建立連線 AWS Glue 時提供 API 金鑰給 。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Kustomer 帳戶。 ## 建立 API 金鑰 若要建立 API 金鑰，您將用來在 AWS Glue Studio 中建立 Kustomer 連接器的連線： 1. 使用您的憑證登入 [Kustomer 儀表板](https://amazon-appflow.kustomerapp.com/login)。 1. 選擇左側功能表中的**設定**圖示。 1. 展開**安全性**下拉式功能表，然後選取 **API 金鑰**。 1. 在「API 金鑰」建立頁面中，從右上角選取**新增 API 金鑰**。 1. 填入要建立之 API 金鑰的必填輸入。 + 名稱：API 金鑰的任何名稱。 + 角色：必須選取 'org'，Kustomer API 才能運作。 + 過期 (以天為單位)：您希望 API 金鑰有效的天數。如果符合您的使用案例，可以將其保留為**永不過期**。 1. 選擇**建立**。 1. 存放 API 金鑰 （權杖） 值以供進一步使用，以在 AWS Glue Studio 中建立 Kustomer 連接器的連線。 # 設定 Kustomer 連線 若要設定 Kustomer 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `apiKey` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 在**連線**下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Kustomer。 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`。 # 從 Kustomer 實體中讀取 **必要條件** 您要從中讀取的 Kustomer 物件。您將需要物件名稱，例如品牌或卡片。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 品牌 | 否 | 是 | 否 | 是 | 否 | | 卡片 | 否 | 是 | 否 | 是 | 否 | | 聊天設定 | 否 | 否 | 否 | 是 | 否 | | 公司 | 是 | 是 | 是 | 是 | 是 | | 對話 | 是 | 是 | 是 | 是 | 是 | | 客戶 | 是 | 是 | 是 | 是 | 是 | | 客戶搜尋已鎖定 | 否 | 是 | 否 | 是 | 否 | | 客戶搜尋位置 | 否 | 否 | 否 | 是 | 否 | | 電子郵件勾點 | 否 | 是 | 否 | 是 | 否 | | Web 勾點 | 否 | 是 | 否 | 是 | 否 | | KB 文章 | 否 | 是 | 否 | 是 | 否 | | KB 類別 | 否 | 是 | 否 | 是 | 否 | | KB 表單 | 否 | 是 | 否 | 是 | 否 | | KB 路由 | 否 | 是 | 否 | 是 | 否 | | KB 標籤 | 否 | 是 | 否 | 是 | 否 | | KB 範本 | 否 | 是 | 否 | 是 | 否 | | KB 主題 | 否 | 是 | 否 | 是 | 否 | | Klasses | 否 | 是 | 否 | 是 | 否 | | KViews | 否 | 是 | 否 | 是 | 否 | | 訊息 | 是 | 是 | 是 | 是 | 是 | | 備註 | 是 | 是 | 是 | 是 | 是 | | 通知 | 否 | 是 | 否 | 是 | 否 | **範例**： ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "brands", "API_VERSION": "v1" } ``` ## Kustomer 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [品牌](https://api.kustomerapp.com/v1/brands) + [卡片](https://api.kustomerapp.com/v1/cards) + [聊天設定](https://api.kustomerapp.com/v1/chat/settings) + [公司](https://api.kustomerapp.com/v1/companies) + [對話](https://api.kustomerapp.com/v1/conversations) + [客戶](https://api.kustomerapp.com/v1/customers) + [客戶搜尋已鎖定](https://api.kustomerapp.com/v1/customers/searches/pinned) + [客戶搜尋位置](https://api.kustomerapp.com/v1/customers/searches/positions) + [勾點電子郵件](https://api.kustomerapp.com/v1/hooks/email) + [勾點 Web](https://api.kustomerapp.com/v1/hooks/web) + [KB 文章](https://api.kustomerapp.com/v1/kb/articles) + [KB 類別](https://api.kustomerapp.com/v1/kb/categories) + [KB 表單]( https://api.kustomerapp.com/v1/kb/forms) + [KB 路由](https://api.kustomerapp.com/v1/kb/routes) + [KB 標籤](https://api.kustomerapp.com/v1/kb/tags) + [KB 範本](https://api.kustomerapp.com/v1/kb/templates) + [KB 主題](https://api.kustomerapp.com/v1/kb/themes) + [Klasses](https://api.kustomerapp.com/v1/klasses) + [Kviews](https://api.kustomerapp.com/v1/kviews) + [訊息](https://api.kustomerapp.com/v1/messages) + [備註](https://api.kustomerapp.com/v1/notes) + [通知](https://api.kustomerapp.com/v1/notifications) Kustomer API v1 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/kustomer-reading-from-entities.html) ## 分區查詢 **欄位型分區** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，接受 ISO 格式的值。 有效值範例： ``` "2023-01-15T11:18:39.205Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/kustomer-reading-from-entities.html) 範例： ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversation", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2023-01-15T11:18:39.205Z" "UPPER_BOUND": "2023-02-15T11:18:39.205Z" "NUM_PARTITIONS": "2" } ``` # Kustomer 連線選項 以下是 Kustomer 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Kustomer 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。要使用的 Kustomer 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。Kustomer 執行個體 URL。 # Kustomer 限制 以下是 Kustomer 的限制或備註： + 不支援 `Customer Searches` 實體，因為 Kustomer API 文件尚未為其宣告任何端點。 + 不支援對 `Klasses` 實體進行篩選和增量傳輸。 + 單一請求中的多個適用欄位可支援排序依據。 不過，對於某些組合，已觀察到 SaaS 終端的多個欄位的排序依據功能行為不一致。其無法預測，因為有可能顯示不正確排序結果的 'n' 個組合。例如： 對於 `Customers` 實體，按 `progressiveStatus desc, name asc` 排序不會產生正確的排序結果。其只會根據 `progressiveStatus` 順序排序。如果發現此類行為，可以使用單一欄位進行排序。 + `Conversations` 和 `Messages` 實體僅支援欄位 'id' 的排序依據作為查詢參數。例如：https://api.kustomerapp.com/v1/conversations?sort=desc (這會以遞減順序按照 'id' 對結果進行排序。) 此外，任何其他欄位上的篩選條件或排序會轉換為將 API 端點作為 POST 的 POST 請求內文 https://api.kustomerapp.com/v1/customers/search 若要允許在 `Conversations` 和 `Messages` 中依 'id' 排序，應該只存在依 id 排序，或在任何其他適用欄位存在任何其他篩選條件和/或排序依據。 + 無論是已篩選還是未篩選的請求，Kustomer 允許擷取最多 10K 筆記錄。由於此限制，持有超過 10K 筆記錄的任何實體都會遺失資料。可以執行兩種可能的解決方法，以部分緩解此問題： + 套用篩選條件來擷取一組特定記錄。 + 如果已套用的篩選條件具有超過 10K 筆記錄，請在新的後續請求中套用連續篩選條件值，或在篩選條件中套用範圍。例如： 第一個請求的 filterExpression：`modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z` 假設這會耗盡 10K 筆記錄限制。 可以使用 filterExpression 觸發另一個請求：`modifiedAt >= 2023-03-15T05:26:23.000Z` + 作為 SaaS 行為，Kustomer 中的 `CONTAINS` 運算子僅支援對完整字詞進行比對，而不是對字詞進行部分比對。例如："body CONTAINS 'test record'" 將比對 'body' 欄位中具有 'test' 的記錄。不過，"body CONTAINS 'test'" 不會比對 'body' 欄位中具有 'testAnotherRecord' 的記錄。 # 連線至 LinkedIn LinkedIn 是一種付費行銷工具，可透過各種贊助貼文和其他方法提供對 LinkedIn 社交網路的存取。LinkedIn 是一種強大的行銷工具，可讓 B2B 公司建置潛在客戶、線上辨識、共用內容等。 **Topics** + [AWS Glue 支援 LinkedIn](linkedin-support.md) + [包含用於建立和使用連線的 API 操作的政策](linkedin-configuring-iam-permissions.md) + [設定 LinkedIn](linkedin-configuring.md) + [設定 LinkedIn 連線](linkedin-configuring-connections.md) + [從 LinkedIn 實體中讀取](linkedin-reading-from-entities.md) + [LinkedIn 連線選項](linkedin-connection-options.md) + [建立 LinkedIn 帳戶](linkedin-create-account.md) + [限制](linkedin-connector-limitations.md) # AWS Glue 支援 LinkedIn AWS Glue 支援 LinkedIn，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 LinkedIn 查詢資料。 **支援作為目標？** 否。 **支援的 LinkedIn API 版本** ** 202406 (2024 年 6 月) ** # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 LinkedIn 您必須先符合下列要求，才能使用 從 LinkedIn AWS Glue 傳輸： ## 最低需求 + 您有一個 LinkedIn 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 LinkedIn 帳戶](linkedin-create-account.md)。 + 您的 LinkedIn 帳戶已啟用 API 存取。 + 您已在 LinkedIn 帳戶中建立 `OAuth2 API` 整合。此整合提供用戶端登入資料，在對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱[建立 LinkedIn 帳戶](linkedin-create-account.md)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 LinkedIn 帳戶。對於一般連線，不需要在 LinkedIn 中執行任何其他操作。 # 設定 LinkedIn 連線 LinkedIn 支援 OAuth2 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。使用者可以選擇在 LinkedIn 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 LinkedIn 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符會在建立後 60 天過期。可以使用重新整理字符來取得新的存取字符。 如需有關為 `Authorization Code OAuth` 流程建立連線應用程式的公有 LinkedIn 文件，請參閱[授權碼流程 (3 條腿的 OAuth)](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2024-07&tabs=HTTPS1)。 **設定 LinkedIn 連線** 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 + 對於 AWS 受管連線應用程式 – 使用一些暫時值清空秘密或秘密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections 下建立連線**： 1. 選取**連線類型**時，請選取 **LinkedIn**。 1. 提供 LinkedIn 環境。 1. 選取 AWS Glue 可擔任的 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`。 # 從 LinkedIn 實體中讀取 **先決條件** 您要從中讀取的 LinkedIn 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 廣告帳戶 | 是 | 是 | 是 | 是 | 否 | | 行銷活動 | 是 | 是 | 是 | 是 | 否 | | 行銷活動群組 | 是 | 是 | 是 | 是 | 否 | | 創意 | 是 | 是 | 是 | 是 | 否 | | 廣告分析 | 是 | 否 | 否 | 是 | 否 | | 廣告分析所有廣告帳戶 | 是 | 否 | 否 | 是 | 否 | | 廣告分析所有行銷活動 | 是 | 否 | 否 | 是 | 否 | | 廣告分析所有行銷活動群組 | 是 | 否 | 否 | 是 | 否 | | 廣告分析所有廣告創意 | 是 | 否 | 否 | 是 | 否 | | 共用統計資料 | 是 | 否 | 否 | 是 | 否 | | 頁面統計資料 | 是 | 否 | 否 | 是 | 否 | | 跟隨者統計資料 | 是 | 否 | 否 | 是 | 否 | **範例** ``` netsuiteerp_read = glueContext.create_dynamic_frame.from_options( connection_type="linkedin", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "adaccounts", "API_VERSION": "202406" } ) ``` **LinkedIn 實體和欄位詳細資訊** | **欄位資料類型** | **支援的篩選條件運算子** | | --- | --- | | String | = | | DateTime | BETWEEN, = | | 數值 | = | | Boolean | = | # LinkedIn 連線選項 以下是 LinkedIn 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。LinkedIn 中物件的名稱。例如，adAccounts。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 LinkedIn Rest API 版本。值為 202406，因為 LinkedIn 目前僅支援 202406 版。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為所選實體選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 LinkedIn 帳戶 **建立 LinkedIn 應用程式和 OAuth 憑證** 1. 導覽至 **LinkedIn 開發人員網路**頁面，並使用 LinkedIn 帳戶憑證登入。 1. 導覽至**我的應用程式**頁面，選擇**建立應用程式**以建立新的 LinkedIn 應用程式。 1. 在應用程式註冊表單中輸入以下詳細資訊： + **公司名稱** – 選取現有公司或建立新公司。 + **名稱** – 輸入應用程式名稱。 + **說明** – 輸入應用程式說明。 + **應用程式標誌** – 選取影像檔案作為應用程式標誌。 + **應用程式使用** – 選取應用程式的用途。 + **網站 URL** – 輸入包含應用程式詳細資訊的網站 URL。 + **業務電子郵件** – 輸入您的業務電子郵件地址。 + **業務電話** – 輸入您的業務電話號碼。 + **LinkedIn API 使用條款** – 閱讀並同意。 1. 完成應用程式註冊表單之後，選擇**提交**。 系統會將您重新導向至**身分驗證**頁面，其中會顯示身分驗證金鑰 (用戶端 ID 和用戶端機密) 以及其他相關詳細資訊。 1. 如果 Web 應用程式需要從使用者的 LinkedIn 帳戶中存取其電子郵件地址，請選取 `r_emailaddress` 許可。此外，可以為 LinkedIn 應用程式指定已授權的重新導向 URL。 **在 LinkedIn 帳戶中建立頁面** 1. 導覽至 [LinkedIn 開發人員產品](https://developer.linkedin.com/)。 1. 在 **LinkedIn 開發人員產品**頁面的右上角，選取**我的應用程式**。 1. 在**我的應用程式**頁面的右上角，選取**建立應用程式**。 1. 在**建立應用程式**頁面中，在**應用程式名稱**欄位輸入應用程式名稱。 1. 在 **LinkedIn 頁面**欄位中，輸入公司頁面名稱或 URL。 **注意** 如果沒有 LinkedIn 頁面，可以選取**建立新的 LinkedIn** 來建立一個。 1. 在**隱私權政策 URL** 欄位中，輸入隱私權政策 URL。 1. 選擇**上傳標誌**以上傳要在使用者使用您的應用程式進行授權時顯示的影像。 1. 在**法律協定**部分中，選取**我已閱讀並同意這些條款**。 1. 選擇**建立應用程式**。 將建立新應用程式，並可在**我的應用程式**索引標籤下使用。 **在 LinkedIn 中發布行銷活動廣告** 1. 登入 **Campaign Manager**。 1. 選擇現有的**行銷活動群組**，或選擇**建立**以建立新群組。 1. 選取您的目標。 1. 選取您的群組、預算和排程。 1. 建置目標受眾。 1. 選取廣告格式。 1. 選取預算和排程。 1. 設定廣告。 1. 檢閱並啟動。 # 限制 對於分析欄位 `ad_analytics_all_adAccounts`、`ad_analytics_all_campaigns`、`ad_analytics_all_campaign_groups` 和 `ad_analytics_all_adCreatives`，需要篩選條件才能擷取記錄。 # 連線至 Mailchimp Mailchimp 是一個全方位行銷平台，可協助您管理並與客戶、顧客和其他相關方溝通。其行銷方法著重於健全的聯絡管理實務、精心設計的電子郵件、獨特的自動化工作流程，以及強大的資料分析。如果您是 Mailchimp 使用者，您可以 AWS Glue 連線到您的 Mailchimp 帳戶。然後，您可以在 ETL 任務中使用 Mailchimp 作為資料來源。執行這些任務以在 Mailchimp AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Mailchimp](mailchimp-support.md) + [包含用於建立和使用連線的 API 操作的政策](mailchimp-configuring-iam-permissions.md) + [設定 Mailchimp](mailchimp-configuring.md) + [設定 Mailchimp 連線](mailchimp-configuring-connections.md) + [從 Mailchimp 實體中讀取](mailchimp-reading-from-entities.md) + [Mailchimp 連線選項](mailchimp-connection-options.md) + [建立 Mailchimp 帳戶](mailchimp-create-account.md) + [限制](mailchimp-connector-limitations.md) # AWS Glue 支援 Mailchimp AWS Glue 支援 Mailchimp，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Mailchimp 查詢資料。 **支援作為目標？** 否。 **支援的 Mailchimp API 版本** 3.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Mailchimp 您必須先符合下列要求，才能使用 從 Mailchimp AWS Glue 傳輸： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Mailchimp 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Mailchimp 帳戶](mailchimp-create-account.md)。 + 您必須使用 服務存取建立 AWS 帳戶 AWS Glue。 + 請確保已建立下列其中一個資源。這些資源提供登入資料， AWS Glue 用於在對您的帳戶進行驗證呼叫時安全地存取您的資料： + 支援 OAuth 2.0 身分驗證的開發人員應用程式。如需有關建立開發人員應用程式的詳細資訊，請參閱[建立 Mailchimp 帳戶](mailchimp-create-account.md)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Mailchimp 帳戶。對於一般連線，不需要在 Mailchimp 中執行任何其他操作。 # 設定 Mailchimp 連線 Mailchimp 支援以下兩種類型的身分驗證機制： + Mailchimp 支援 `AUTHORIZATION_CODE` 授權類型。 + 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用其。預設情況下，建立連線的使用者可能會依賴 AWS Glue 擁有的連線應用程式，在該應用程式中，除了其 Mailchimp 用戶端 ID 和用戶端機密之外，他們不需要提供任何 `OAuth` 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Mailchimp，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Mailchimp 執行個體。 + 使用者仍然可以選擇在 Mailchimp 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Mailchimp 以登入並授權 AWS Glue 存取其資源。 + 如需有關建立 `AUTHORIZATION_CODE OAuth` 流程連線應用程式的公有 Mailchimp 文件，請參閱[使用 OAuth 2 代表其他使用者存取資料](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/?msockid=141ebf9ffb4d619525c3ad27fad660d6)。 + **自訂授權** – 如需有關產生自訂授權所需 API 金鑰的公有 Mailchimp 文件，請參閱[關於 API 金鑰](https://mailchimp.com/en/help/about-api-keys/?msockid=310fd0fe09d16afe034fc5de08d76b01)。 若要設定 Mailchimp 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + `OAuth` 授權 – 針對客戶管理的連線應用程式：機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 + 自訂授權 – 針對客戶管理的連線應用程式：機密應包含以「api\$1key」做為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在**連線**下，選取**建立連線**。 1. 選取**資料來源**時，請選取 Mailchimp。 1. 提供 Mailchimp `instanceUrl`。 1. 選取 AWS Glue 可擔任的 IAM 角色，並具有下列動作的許可： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 選取「身分驗證類型」以連線至 Mailchimp： + 針對 `OAuth` 身分驗證 – 提供字符 URL，即您要連線之 Mailchimp 的使用者管理的用戶端應用程式 ClientId。 + 針對自訂身分驗證 – 選取身分驗證類型 CUSTOM 以連線至 Mailchimp。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為其他網路連線。 # 從 Mailchimp 實體中讀取 **先決條件** 您要從中讀取的 Mailchimp 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** + [濫用報告](https://mailchimp.com/developer/marketing/api/campaign-abuse/) + [自動化](https://mailchimp.com/developer/marketing/api/automation/list-automations/) + [行銷活動](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/) + [按一下詳細資訊](https://mailchimp.com/developer/marketing/api/link-clickers/) + [清單](https://mailchimp.com/developer/marketing/api/link-clickers/) + [成員](https://mailchimp.com/developer/marketing/api/list-segment-members/) + [公開的詳細資訊](https://mailchimp.com/developer/marketing/api/list-members/) + [客群](https://mailchimp.com/developer/marketing/api/list-segments/) + [存放](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/) + [已取消訂閱](https://mailchimp.com/developer/marketing/api/unsub-reports/) | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | |  自動化 | 是 | 是 | 是 | 是 | 是 | | 行銷活動 | 否 | 否 | 否 | 否 | 否 | | 清單 | 是 | 是 | 否 | 是 | 是 | | 檢舉濫用情況 | 否 | 是 | 否 | 是 | 是 | | 報告開啟 | 否 | 是 | 否 | 是 | 是 | | 報告點擊率 | 是 | 是 | 否 | 是 | 是 | | 報告取消訂閱 | 否 | 是 | 否 | 是 | 是 | | 區段 | 否 | 是 | 否 | 是 | 是 | | 細分市場成員 | 是 | 是 | 否 | 是 | 否 | | 商店 | 是 | 是 | 是 | 是 | 否 | **範例** ``` mailchimp_read = glueContext.create_dynamic_frame.from_options( connection_type="mailchimp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "stores", "INSTANCE_URL": "https://us14.api.mailchimp.com", "API_VERSION": "3.0" }) ``` **Mailchimp 實體和欄位詳細資訊** + [濫用報告](https://mailchimp.com/developer/marketing/api/campaign-abuse/) + [自動化](https://mailchimp.com/developer/marketing/api/automation/list-automations/) + [行銷活動](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/) + [按一下詳細資訊](https://mailchimp.com/developer/marketing/api/link-clickers/) + [清單](https://mailchimp.com/developer/marketing/api/link-clickers/) + [成員](https://mailchimp.com/developer/marketing/api/list-segment-members/) + [公開的詳細資訊](https://mailchimp.com/developer/marketing/api/list-members/) + [客群](https://mailchimp.com/developer/marketing/api/list-segments/) + [存放](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/) + [已取消訂閱](https://mailchimp.com/developer/marketing/api/unsub-reports/) ## 分區查詢 如果想要在 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`：分區數目。 下表說明實體分區欄位支援詳細資訊： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/mailchimp-reading-from-entities.html) 範例： ``` read_read = glueContext.create_dynamic_frame.from_options( connection_type="mailchimp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "automations", "API_VERSION": "3.0", "INSTANCE_URL": "https://us14.api.mailchimp.com", "PARTITION_FIELD": "create_time", "LOWER_BOUND": "2024-02-05T14:09:30.115Z", "UPPER_BOUND": "2024-06-07T13:30:00.134Z", "NUM_PARTITIONS": "3" } ``` # Mailchimp 連線選項 以下是 Mailchimp 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Mailchimp 中物件的名稱。 + `INSTANCE_URL`(String) - (必要) 有效的 Mailchimp 執行個體 URL。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Mailchimp Engage Rest API 版本。例如：3.0。 + `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。用於讀取。要讀取的分區數目。 # 建立 Mailchimp 帳戶 1. 導覽至 [Mailchimp 登入頁面](https://login.mailchimp.com/?locale=en)，輸入電子郵件 ID 和密碼，然後選擇**註冊**。 1. 從 Mailchimp 中開啟確認電子郵件，然後選擇確認連結以驗證您的帳戶。 **注意** 接收啟用電子郵件所需的時間可能有所不同。如果尚未收到啟用電子郵件，請檢查垃圾郵件資料夾，並閱讀我們的啟用電子郵件疑難排解秘訣。Mailchimp 會阻止來自角色型電子郵件地址的註冊，例如 [admin@pottedplanter.com](mailto:admin@pottedplanter.com) 或 [security@example.com](mailto:security@example.com)。 第一次登入帳戶時，Mailchimp 會要求提供必要資訊。Mailchimp 會使用此資訊來協助確保您的帳戶符合其使用條款，並提供與您和您公司需求相關的指引。 1. 輸入您的資訊，依照提示完成啟用程序，並開始使用新的 Mailchimp 帳戶。 **註冊 `OAuth2.0` 應用程式** 1. 導覽至 [Mailchimp 登入頁面](https://login.mailchimp.com/?locale=en)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 1. 選取右上角的**使用者**圖示，然後從下拉式功能表中選擇**帳戶和帳單**。 1. 選取**額外項目**，然後從下拉式功能表中選擇**已註冊的應用程式**。 1. 查找並選擇**註冊應用程式**。 1. 輸入下列詳細資訊： + **應用程式名稱** – 應用程式的名稱。 + **公司/組織** – 公司或組織的名稱。 + **應用程式網站** – 應用程式的網站。 + **重新導向 URI** – 重新導向 URI 模式是 URI 路徑 (或以逗號分隔的路徑清單)，Mailchimp 可以在登入流程完成時重新導向到該路徑 (如果請求)。例如 `https://ap-southeast-2\\.console\\.aws\\.amazon\\.com` 1. 選擇**建立**。 1. **用戶端 ID** 和**用戶端機密**現在可見。複製並儲存在安全位置。然後，選擇**完成**。 **注意** 「用戶端 ID」和「用戶端機密」字串是在使用 AppFlow 或 AWS Glue時用來建立此連接器連線的憑證。 **產生 API 金鑰** 1. 導覽至 [Mailchimp 登入頁面](https://login.mailchimp.com/?locale=en)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 1. 選取右上角的**使用者**圖示，然後從下拉式功能表中選擇**帳戶和帳單**。 1. 選取**額外項目**，然後從下拉式功能表中選擇 **API 金鑰**。 1. 選擇**建立金鑰**。 1. 輸入金鑰名稱，然後選擇**產生金鑰**。 下一頁會顯示產生的 API 金鑰。 1. 複製您的金鑰，安全存放，然後選擇**完成**。 # 限制 以下是 Mailchimp 連接器的限制： + 只有 `Campaigns`、`Automations`、`Lists`、`Open Details`、`Members` 和 `Segments` 實體支援篩選。 + 在 `DateTime` 資料類型欄位使用篩選條件時，必須以下列格式傳遞值：`yyyy-mm-ddThh:MM:ssZ` # 連線至 Microsoft Dynamics 365 CRM Microsoft Dynamics 365 是企業資源規劃和客戶關係管理智慧型商業應用程式的產品線。 **Topics** + [AWS Glue 支援 Microsoft Dynamics 365](microsoft-dynamics-365-support.md) + [包含用於建立和使用連線的 API 操作的政策](microsoft-dynamics-365-configuring-iam-permissions.md) + [設定 Microsoft Dynamics 365 CRM](microsoft-dynamics-365-configuring.md) + [設定 Microsoft Dynamics 365 CRM 連線](microsoft-dynamics-365-configuring-connections.md) + [從 Microsoft Dynamics 365 CRM 實體中讀取](microsoft-dynamics-365-reading-from-entities.md) + [Microsoft Dynamics 365 CRM 連線選項參考](microsoft-dynamics-365-connection-options.md) + [限制](microsoft-dynamics-365-connector-limitations.md) # AWS Glue 支援 Microsoft Dynamics 365 AWS Glue 支援 Microsoft Dynamics 365，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Microsoft Dynamics 365 查詢資料。 **支援作為目標？** 否。 **支援的 Microsoft Dynamics 365 CRM API 版本** v9.2。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Microsoft Dynamics 365 CRM 您必須先符合下列要求，才能使用 從 Microsoft Dynamics 365 CRM AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個具有用戶端 Id 和機密的 Microsoft Dynamics 365 CRM 開發人員帳戶。 + 您的 Microsoft Dynamics 365 CRM 帳戶擁有 API 存取權，具有有效授權。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Microsoft Dynamics 365 CRM 帳戶。對於一般連線，不需要在 Microsoft Dynamics 365 CRM 中執行任何其他操作。 # 設定 Microsoft Dynamics 365 CRM 連線 **AUTHORIZATION\$1CODE 授權類型** + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Microsoft Dynamics 365 CRM，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Microsoft Dynamics 365 CRM 執行個體。 + 使用者可以選擇在 Microsoft Dynamics 365 CRM 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Microsoft Dynamics 365 CRM 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需建立授權碼 OAuth 流程連線應用程式的公有 Microsoft Dynamics 365 CRM 文件，請參閱 \$1 Microsoft Learn。[Microsoft 應用程式註冊](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/authenticate-oauth#app-registration)。 Microsoft Dynamics 365 CRM 支援 OAuth2.0 身分驗證。 若要設定 Microsoft Dynamics 365 CRM 連線： 1. 在 中 AWS Secrets Manager，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 + 對於 AuthorizationCode 授權類型： 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式用戶端機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**資料來源**時，請選取 Microsoft Dynamics 365 CRM。 1. 選取您要連線之 Microsoft Dynamics 365 CRM 執行個體的 **INSTANCE\$1URL**。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 選取**字符 URL** 和**授權碼 URL** 以存取 Microsoft Dynamics 365 CRM 工作區。 1. 提供 Microsoft Dynamics 365 CRM 應用程式的**使用者管理的用戶端應用程式 ClientId**。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。選擇**下一步**。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Microsoft Dynamics 365 CRM 實體中讀取 **先決條件** + 您想要從中進行讀取的 Microsoft Dynamics 365 CRM 物件。將需要物件名稱，例如聯絡人或帳戶。下表顯示支援的實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 動態實體 | 是 | 是 | 是 | 是 | 是 | **範例** ``` dynamics365_read = glueContext.create_dynamic_frame.from_options( connection_type="microsoftdynamics365crm", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "dynamic_entity", "API_VERSION": "v9.2", "INSTANCE_URL": "https://{tenantID}.api.crm.dynamics.com" } ``` ## Microsoft Dynamics 365 CRM 實體和欄位詳細資訊 **具有動態中繼資料的實體：** Microsoft Dynamics 365 CRM 提供端點來動態擷取中繼資料。因此，對於動態實體，在資料類型層級獲得運算子支援。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/microsoft-dynamics-365-reading-from-entities.html) **分區查詢** Microsoft Dynamics 365 CRM 僅支援欄位型分區。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於 Datetime，接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。有效值的範例：`"2024-01-30T06:47:51.000Z"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： | 實體名稱 | 分區欄位 | DataType | | --- | --- | --- | | 動態實體 (標準實體) | 可查詢的動態 DateTime 欄位 | createdon, modifiedon | | 動態實體 (自訂實體) | createdon, modifiedon | createdon, modifiedon | **範例** ``` dynamics365_read = glueContext.create_dynamic_frame.from_options( connection_type="microsoftdynamics365crm", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "dynamic_entity", "API_VERSION": "v9.2", "instanceUrl": "https://{tenantID}.api.crm.dynamics.com" "PARTITION_FIELD": "createdon" "LOWER_BOUND": "2024-01-30T06:47:51.000Z" "UPPER_BOUND": "2024-06-30T06:47:51.000Z" "NUM_PARTITIONS": "10" } ``` # Microsoft Dynamics 365 CRM 連線選項參考 以下是 Microsoft Dynamics 365 CRM 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Microsoft Dynamics 365 CRM 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Microsoft Dynamics 365 CRM Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `INSTANCE_URL`(字串) - (必要) 有效的 Microsoft Dynamics 365 CRM 執行個體 URL，格式為：`https://{tenantID}.api.crm.dynamics.com` + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。範例：`2024-01-30T06:47:51.000Z`。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。範例：`2024-06-30T06:47:51.000Z`。 # 限制 以下是 Microsoft Dynamics 365 CRM 連接器的限制： + 在 Microsoft Dynamics 365 CRM 中，不支援記錄型分區，因為其不支援位移參數，因此不支援記錄型分區。 + 分頁設定為每頁最多 500 筆記錄，以避免由於資料大小和速率限制組合而導致 SaaS 的內部伺服器例外狀況。 + [有關分頁的 SaaS 文件](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/query/page-results?view=dataverse-latest) + [有關速率限制的 SaaS 文件](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/api-limits?tabs=sdk) + Microsoft Dynamics 365 CRM 僅在所有實體的父欄位中支援 `order by`。子欄位中不支援 `order by`。 + 同時支援 ASC 和 DESC 方向。 + 支援多個欄位中的 `order by`。 + 在 `aadusers` 標準實體的「createddatetime」欄位中進行篩選時，會從 SaaS 擲回一個不良請求錯誤，即使其支援篩選。由於中繼資料的動態特性，沒有具體標識任何其他實體存在類似問題，也不明確根本原因。因此，無法處理。 + 複雜物件類型 (例如 Struct、List 和 Map) 不支援篩選。 + 可從回應中擷取的許多欄位已在動態中繼資料回應中將 `isRetrievable` 標記為 `false`。為了避免資料遺失，將所有欄位的 `isRetrievable` 設為 `true`。 + 當滿足下列條件時，所有實體都將支援欄位型分區： + DateTime 可查詢欄位應存在於標準實體中，或自訂實體的 `createdon` 和 `modifiedon` 欄位中 (系統產生的欄位)。 + 系統產生的欄位或任何 SaaS 中繼資料 API 的可為 Null 的屬性都沒有唯一標識，但通常的做法是，只有預設可用的欄位是可篩選且不可為 Null。因此，上述欄位選取條件被視為 null 安全，如果可篩選，則符合分區資格。 # 連線至 Microsoft Teams Microsoft Teams 是 Microsoft 365 內的協作工作空間，可作為工作空間對話、協作團隊合作、視訊聊天和文件共用的中央中樞，全都是為了在統一的工具套件中協助工作者提高生產力而設計。 **Topics** + [AWS Glue 支援 Microsoft Teams](microsoft-teams-support.md) + [包含用於建立和使用連線的 API 操作的政策](microsoft-teams-configuring-iam-permissions.md) + [設定 Microsoft Teams](microsoft-teams-configuring.md) + [設定 Microsoft Teams 連線](microsoft-teams-configuring-connections.md) + [從 Microsoft Teams 實體中讀取](microsoft-teams-reading-from-entities.md) + [Microsoft Teams 連線選項參考](microsoft-teams-connection-options.md) + [限制](microsoft-teams-connector-limitations.md) + [建立新的 Microsoft Teams 帳戶：](#microsoft-teams-account-creation) # AWS Glue 支援 Microsoft Teams AWS Glue 支援 Microsoft Teams，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Microsoft Teams 查詢資料。 **支援作為目標？** 否。 **支援的 Microsoft Teams API 版本** v1。如需特定版本的實體支援，請參閱「來源的支援實體」。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Microsoft Teams 您必須先符合下列要求，才能使用 從 Microsoft Teams AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Microsoft Teams 開發人員帳戶。如需詳細資訊，請參閱[建立新的 Microsoft Teams 帳戶：](connecting-to-microsoft-teams.md#microsoft-teams-account-creation)。 + 您應該已在 Microsoft 帳戶中設定 OAuth2 應用程式，該應用程式提供用戶端 ID 和秘密登入資料， AWS Glue 用於在對您的帳戶進行驗證呼叫時安全地存取您的資料。如需詳細資訊，請參閱[建立新的 Microsoft Teams 帳戶：](connecting-to-microsoft-teams.md#microsoft-teams-account-creation)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Microsoft Teams 帳戶。對於一般連線，不需要在 Microsoft Teams 中執行任何其他操作。 # 設定 Microsoft Teams 連線 Microsoft Teams 支援以下兩種類型的身分驗證機制： 1. OAuth 身分驗證：Microsoft Teams 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。預設情況下，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式，在該應用程式中，除了 Microsoft Teams 執行個體之外，他們不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Microsoft Teams，其中使用者必須登入並允許 AWS Glue 請求的許可存取其 Microsoft Teams 執行個體。 + 使用者可以選擇在 Microsoft Teams 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Microsoft Teams 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符的作用時間為一小時，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需建立授權碼 OAuth 流程連線應用程式的公有 Microsoft Teams 文件，請參閱 \$1 Microsoft Learn。[在 Microsoft 身分平台 Microsoft Graph 上註冊應用程式](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。 若要設定 Microsoft Teams 連線： 1. 在 中 AWS Secrets Manager，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於 OAuth 驗證： + 對於客戶管理的連線應用程式，機密應包含以 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作為金鑰的連線應用程式消費者機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在「資料連線」下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Microsoft Teams。 1. 提供您的 Microsoft Teams **租用戶 ID**。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 提供 Microsoft Teams 應用程式的使用者管理的用戶端應用程式用戶端 Id。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。選擇**下一步**。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Microsoft Teams 實體中讀取 **先決條件** + 您想要從中進行讀取的 Microsoft Teams 物件。將需要物件名稱，例如團隊或頻道訊息。下表顯示支援的實體。 **來源的支援實體** API 1.0 版支援所有實體。 | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 團隊 | 否 | 否 | 否 | 是 | 否 | | 團隊成員 | 是 | 是 | 否 | 是 | 是 | | Groups (群組) | 是 | 是 | 是 | 是 | 是 | | 群組成員 | 是 | 是 | 否 | 是 | 否 | | 頻道 | 是 | 否 | 否 | 是 | 是 | | 頻道訊息 | 否 | 是 | 否 | 是 | 否 | | 頻道訊息回覆 | 否 | 是 | 否 | 是 | 否 | | 頻道標籤 | 是 | 否 | 否 | 是 | 否 | | 聊天 | 是 | 是 | 是 | 是 | 是 | | 行事曆事件 | 是 | 是 | 是 | 是 | 是 | **範例** ``` MicrosoftTeams_read = glueContext.create_dynamic_frame.from_options( connection_type="MicrosoftTeams", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "company", "API_VERSION": "v1.0" } ``` ## Microsoft Teams 實體和欄位詳細資訊 實體清單： + 團隊：[https://docs.microsoft.com/en-us/graph/api/user-list-joinedteams?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/user-list-joinedteams?view=graph-rest-1.0) + 團隊成員：[https://docs.microsoft.com/en-us/graph/api/team-list-members?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/team-list-members?view=graph-rest-1.0) + 群組：[https://docs.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0) + 群組成員：[https://docs.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0) + 頻道：[https://docs.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0) + 頻道訊息：[https://docs.microsoft.com/en-us/graph/api/channel-list-messages?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list-messages?view=graph-rest-1.0) + 頻道訊息回覆：[https://docs.microsoft.com/en-us/graph/api/chatmessage-list-replies?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/chatmessage-list-replies?view=graph-rest-1.0) + 頻道標籤：[https://docs.microsoft.com/en-us/graph/api/channel-list-tabs?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list-tabs?view=graph-rest-1.0) + 聊天：[https://docs.microsoft.com/en-us/graph/api/chat-list?view=graph-rest-1.0]( https://docs.microsoft.com/en-us/graph/api/chat-list?view=graph-rest-1.0) + 行事曆事件：[https://docs.microsoft.com/en-us/graph/api/group-list-events?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list-events?view=graph-rest-1.0) **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 團隊成員 | visibleHistoryStartDateTime | DateTime | | Groups (群組) | createdDateTime | DateTime | | 頻道 | createdDateTime | DateTime | | 聊天 | createdDateTime、lastModifiedDateTime | DateTime | | 行事曆事件 | createdDateTime、lastModifiedDateTime、originalStart | DateTime | **範例** ``` microsoftteams_read = glueContext.create_dynamic_frame.from_options( connection_type="MicrosoftTeams", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "group", "API_VERSION": "v1.0", "PARTITION_FIELD": "createdDateTime" "LOWER_BOUND": "2022-07-13T07:55:27.065Z" "UPPER_BOUND": "2022-08-12T07:55:27.065Z" "NUM_PARTITIONS": "2" } ``` # Microsoft Teams 連線選項參考 以下是 Microsoft Teams 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Microsoft Teams 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Microsoft Teams Rest API 版本。範例：v1.0。 + `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。用於讀取。要讀取的分區數目。 # 限制 以下是 Microsoft Teams 連接器的限制： + Microsoft Teams API 傳回的記錄數目少於「聊天」和「團隊成員」實體指定的記錄數目。會向 Microsoft Teams 支援部門報告此問題，且正在進行調查。 ## 建立新的 Microsoft Teams 帳戶： 1. 導覽至 Microsoft Teams 的首頁 [https://account.microsoft.com/account/](https://account.microsoft.com/account/)，然後選擇**登入**。 1. 選擇**建立一個！**。 1. 輸入建立帳戶所需的資訊，然後建立新的帳戶。 1. 導覽至 Microsoft Teams 網站 ([ https://www.microsoft.com/en-in/microsoft-teams/log-in](https://www.microsoft.com/en-in/microsoft-teams/log-in))。 1. 使用您剛建立的 Microsoft 帳戶註冊。 1. 成功註冊 Teams 後，導覽至 [https://account.microsft.com/services](https://account.microsft.com/services)。 1. 選擇**試用 Microsoft 365**。 1. 啟用下面其中一個 Microsoft 365 或 Microsoft Teams 訂閱，以存取 Microsoft Teams 連接器的所有必要功能： + Microsoft Teams 基本版 + Microsoft 365 Business + Microsoft 365 商務基本版 + Microsoft 365 商務標準版 + Microsoft 365 商務進階版 **建立受管用戶端應用程式：** 1. 若要建立受管應用程式，您需要在 Microsoft Entra (先前稱為 Azure Active Directory) 上註冊新的 OAuth 應用程式： 1. 登入 [Microsoft Entra 管理中心](https://entra.microsoft.com)。 1. 如果您可存取多個租用戶，請使用頂部功能表的「設定」圖示，來切換至您要從「型錄 \$1 訂閱」功能表註冊應用程式的租用戶。 1. 導覽至「身分」>「應用程式」>「應用程式註冊」，然後選取**新註冊**。 1. 輸入應用程式的顯示名稱。 1. 在「支援的帳戶類型」區段中指定誰可以使用應用程式。若要讓此應用程式成為全域，請選取「任何組織型錄中的帳戶」或「任何組織型錄和個人 Microsoft 帳戶中的帳戶」。 1. 輸入重新導向 URI `https://{region}.console.aws.amazon.com/appflow/oauth`。例如，對於 `us-west-2 region`，新增 `https://us-west-2.console.aws.amazon.com/appflow/oauth`。您可以為要使用的不同區域新增多個 URL。 1. 註冊應用程式。 1. 請注意用戶端 ID 以供日後使用。 1. 在「基本」區段中選擇**新增憑證或機密**。 1. 選擇**新的用戶端機密**。 1. 輸入描述和到期持續時間。 1. 複製並儲存用戶端機密以供日後使用。 1. 在左側功能表清單中，選取 **API 許可**。 1. 選擇**新增許可**。 1. 選取 "Microsoft Graph"。 1. 選取「委派許可」。 1. 檢查下列所有許可： + User.Read + Offline\$1access + User.Read.All + User.ReadWrite.All + TeamsTab.ReadWriteForTeam + TeamsTab.ReadWriteForChat + TeamsTab.ReadWrite.All + TeamsTab.Read.All + TeamSettings.ReadWrite.All + TeamSettings.Read.All + TeamMember.ReadWrite.All + TeamMember.Read.All + Team.ReadBasic.All + GroupMember.ReadWrite.All + GroupMember.Read.All + Group.ReadWrite.All + Group.Read.All + Directory.ReadWrite.All + Directory.Read.All + Directory.AccessAsUser.All + Chat.ReadWrite + Chat.ReadBasic + Chat.Read + ChannelSettings.ReadWrite.All + ChannelSettings.Read.All + ChannelMessage.Read.All + Channel.ReadBasic.All 1. 選擇**新增許可**。您的應用程式現在已成功設定。您可以使用用戶端 ID 和用戶端機密來建立新的連線。如需詳細資訊，請參閱 [https://learn.microsoft.com/en-us/graph/auth-register-app-v2](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。 # 連線至 Mixpanel Mixpanel 是一種功能強大的即時分析平台，可協助公司衡量和最佳化使用者參與度。Mixpanel 是用於追蹤客戶行為的應用程式。可讓您追蹤使用者如何與您的產品互動，並使用互動式報告分析此資料，只需按幾下滑鼠即可查詢和視覺化結果。身為 Mixpanel 使用者，您可以 AWS Glue 連線至您的 Mixpanel 帳戶。然後，您可以在 ETL 任務中使用 Mixpanel 作為資料來源。執行這些任務以在 Mixpanel AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Mixpanel](Mixpanel-support.md) + [包含用於建立和使用連線的 API 操作的政策](mixpanel-configuring-iam-permissions.md) + [設定 Mixpanel](mixpanel-configuring.md) + [設定 Mixpanel 連線](mixpanel-configuring-connections.md) + [從 Mixpanel 實體中讀取](mixpanel-reading-from-entities.md) + [Mixpanel 連線選項](mixpanel-connection-options.md) + [建立 Mixpanel 帳戶並設定用戶端應用程式](mixpanel-create-account.md) + [限制](mixpanel-connector-limitations.md) # AWS Glue 支援 Mixpanel AWS Glue 支援 Mixpanel，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Mixpanel 查詢資料。 **支援作為目標？** 否。 **支援的 Mixpanel API 版本** 2.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Mixpanel 您必須先符合下列要求，才能使用 從 Mixpanel AWS Glue 傳輸： ## 最低需求 + 您擁有一個 Mixpanel 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Mixpanel 帳戶](mixpanel-create-account.md)。 + 您的 Mixpanel 帳戶已啟用 API 存取。企業版、無限制版、開發人員版和高效版預設會啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Mixpanel 帳戶。對於一般連線，不需要在 Mixpanel 中執行任何其他操作。 # 設定 Mixpanel 連線 Mixpanel 支援 `BasicAuth` 的使用者名稱和密碼。基本身分驗證是一種簡單的身分驗證方法，其中用戶端會直接提供登入資料以存取受保護的資源。 AWS Glue 能夠使用使用者名稱和密碼來驗證 Mixpanel APIs。 如需有關 `BasicAuth` 流程的公有 Mixpanel 文件，請參閱 [Mixpanel 服務帳戶](https://developer.mixpanel.com/reference/service-accounts)。 若要設定 Mixpanel 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於基本身分驗證，機密應包含以 `USERNAME` 和 `PASSWORD` 作為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections 下建立連線**： 1. 選取**連線類型**時，請選取 **Mixpanel**。 1. 提供您要連線的 Mixpanel 的 `INSTANCE_URL`。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Mixpanel 實體中讀取 **先決條件** 您必須擁有一個要從中讀取資料的 Mixpanel 物件，例如 `Funnels`、`Retention`、或 `Retention Funnels`。此外，您將需要知道物件名稱。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 漏斗圖 | 是 | 否 | 否 | 是 | 否 | | Retention | 是 | 否 | 否 | 是 | 否 | | 區隔 | 是 | 否 | 否 | 是 | 否 | | 分段總和 | 是 | 否 | 否 | 是 | 否 | | 分段平均值 | 是 | 否 | 否 | 是 | 否 | | 群體 | 是 | 否 | 否 | 是 | 否 | | 聯絡 | 否 | 是 | 否 | 是 | 否 | | 事件 | 是 | 否 | 否 | 是 | 否 | | 事件頂端 | 是 | 否 | 否 | 是 | 否 | | 事件名稱 | 是 | 否 | 否 | 是 | 否 | | 事件屬性 | 是 | 否 | 否 | 是 | 否 | | 事件屬性頂端 | 是 | 否 | 否 | 是 | 否 | | 事件屬性值 | 是 | 否 | 否 | 是 | 否 | | 註釋 | 是 | 否 | 否 | 是 | 否 | | 設定檔事件活動 | 是 | 否 | 否 | 是 | 否 | **範例** ``` mixpanel_read = glueContext.create_dynamic_frame.from_options( connection_type="mixpanel", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "/cohorts/list?project_id=2603353", "API_VERSION": "2.0", "INSTANCE_URL": "https://www.mixpanel.com/api/app/me" } ``` **Mixpanel 實體和欄位詳細資訊** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/mixpanel-reading-from-entities.html) # Mixpanel 連線選項 以下是 Mixpanel 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Mixpanel 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Mixpanel Rest API 版本。例如，V2.0。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Mixpanel 帳戶並設定用戶端應用程式 **建立 Mixpanel 帳戶** 1. 導覽至 [Mixpanel 首頁/](https://mixpanel.com/)。 1. 在 **Mixpanel** 首頁中，選擇頁面右上角的**註冊**。 1. 在**開始使用**頁面中，完成下列動作： + 在指定欄位中輸入電子郵件地址。 + 選取必要的核取方塊以同意條款。 + 選擇**開始使用**以繼續。 成功完成後，會收到驗證電子郵件。 1. 檢查電子郵件收件匣是否有驗證訊息，開啟電子郵件，並依照指示來驗證您的電子郵件地址。 1. 在驗證頁面中，選擇**驗證電子郵件**以完成電子郵件驗證。 1. 在**命名您的組織**頁面中，輸入組織名稱，然後選擇**下一步**。 1. 在**您的第一個專案**頁面中，輸入專案詳細資訊，然後選擇**建立**。 1. 在下一頁中，選擇**讓我們開始**完成帳戶的建立。 **登入 Mixpanel 帳戶** 1. 導覽至 [Mixpanel 登入頁面/](https://mixpanel.com/login/)。 1. 輸入電子郵件地址，然後選擇**繼續**。 1. 檢查電子郵件收件匣是否有驗證訊息，開啟電子郵件，並依照指示來驗證您的電子郵件地址。 1. 在下一頁中，選擇**登入**按鈕以登入您的帳戶。 **購買 Mixpanel 計劃** 1. 在 Mixpanel 頁面中，選取位於頁面右上角的**設定**圖示。 1. 從選項清單中，選取**計劃詳細資訊和帳單**。 1. 在**計劃詳細資訊和帳單**頁面中，選取**升級或修改**。 1. 在下一頁中，選取您要購買的計劃。 這會完成帳戶建立和計劃購買程序。 **建立使用者名稱和用戶端機密 (註冊您的應用程式)** 1. 在 Mixpanel 頁面中，選取位於頁面右上角的**設定**圖示。 1. 從選項清單中，選取**專案設定**。 1. 在**專案設定**頁面中，選取**服務帳戶**，然後選取**新增服務帳戶**。 1. 從**服務帳戶**下拉式清單中，選取**服務帳戶或輸入要建立的名稱**，新增**專案角色**，指定**過期日**，然後選取**新增**。 **重要** 完成上一個步驟後，以下頁面會顯示服務帳戶的機密金鑰。請務必儲存服務帳戶的機密金鑰。在此時間點之後，您將無法再次存取其。 # 限制 以下是 Mixpanel 連接器的限制： + 對於 `Segmentation Numeric` 實體，如果找不到強制篩選條件的數值資料，則 Mixpanel API 會擲回 `400 (Bad Request)` 錯誤。我們將此視為防止流程失敗的 `OK` 回應。 + 可查詢欄位 `limit` 已從支援的實體中移除，因為： + 由於被解譯為 SDK 的限制功能而導致錯誤 + 篩選條件沒有實際用途 + 限制功能實作現在涵蓋同等功能 + 由於缺少從 SaaS 平台進行分區所需的運算子 (`>=`、`<=`、`<`、`>`、`between`)，因此不支援欄位型分區。雖然其支援 `between` 運算子，但其支援此運算子的欄位無法擷取。因此，不滿足欄位型分區的條件。 + 由於沒有佈建來取得支援分頁的實體的 'offset' 值，因此無法支援 Mixpanel 的記錄型分區。 + `Cohorts` 實體僅支援 `CreatedDate/Time` 欄位並且沒有欄位來識別 `UpdatedDate/Time`，因此無法識別 `DML_Status`。此外，沒有端點可以識別已刪除的記錄。因此，不支援 CDC。 + 若要為下列實體執行 AWS Glue 任務，需要強制篩選條件。如需實體名稱及其所需的篩選條件，請參閱下表。 **實體名稱和所需的篩選條件** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/mixpanel-connector-limitations.html) # 連線至 Monday Monday.com 是一種多樣化的工作作業系統，可簡化專案管理和團隊協作。其具有可自訂的工作流程、視覺化儀表板和自動化工具來提高生產力。使用者可以在一個整合的平台中追蹤任務、管理資源並進行有效通訊。 **Topics** + [AWS Glue 星期一的 支援](monday-support.md) + [包含用於建立和使用連線的 API 操作的政策](monday-configuring-iam-permissions.md) + [設定 Monday](monday-configuring.md) + [設定 Monday 連線](monday-configuring-connections.md) + [從 Monday 實體中讀取](monday-reading-from-entities.md) + [Monday 連線選項參考](monday-connection-options.md) + [限制](monday-connector-limitations.md) + [建立新的 Monday 帳戶：](#monday-account-creation) # AWS Glue 星期一的 支援 AWS Glue 支援週一，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從星期一查詢資料。 **支援作為目標？** 否。 **支援的 Monday API 版本** v2。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Monday 您必須先符合下列要求，才能使用 從星期一 AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Monday 開發人員帳戶。如需詳細資訊，請參閱[建立新的 Monday 帳戶：](connecting-to-monday.md#monday-account-creation)。 + 您的 Monday 開發人員帳戶已啟用 API 存取。試用期內，所有可用的 Monday API 無需額外費用。試用期結束後，需要購買訂閱才能建立和存取資料。如需詳細資訊，請參閱 [Monday 的授權頁面](https://developer.monday.com/api-reference/reference/about-the-api-reference)以取得詳細資訊。 如果您符合這些要求，就可以 AWS Glue 連線到您的星期一帳戶。對於一般連線，不需要在 Monday 中執行任何其他操作。 # 設定 Monday 連線 Monday 支援以下兩種類型的身分驗證機制： 1. OAuth 身分驗證：Monday 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。預設情況下，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式，在該應用程式中，除了 Monday 執行個體 URL 之外，他們不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至星期一，其中使用者必須登入並允許 AWS Glue 請求的許可存取其星期一執行個體。 + 使用者應該選擇在星期一建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至星期一以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符的作用時間為一小時，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需詳細資訊，請參閱[有關為 AUTHORIZATION\$1CODE OAuth 流程建立連線應用程式的文件](https://developers.Monday.com/docs/api/v1/Oauth)。 1. 自訂驗證： + 如需產生自訂授權所需 API 金鑰的公有 Monday 文件，請參閱 [https://developer.monday.com/api-reference/docs/authentication\$1api-token-permissions](https://developer.monday.com/api-reference/docs/authentication#api-token-permissions)。 若要設定 Monday 連線： 1. 在 中 AWS Secrets Manager，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於 OAuth 驗證： + 對於客戶管理的連線應用程式，機密應包含以 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作為金鑰的連線應用程式消費者機密。 1. 對於自訂身分驗證： + 對於客戶管理的連線應用程式，機密應包含以 `personalAccessToken` 作為金鑰的連線應用程式消費者機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在「資料連線」下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Monday。 1. 提供 Monday **instanceURL**。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 選取身分驗證類型以連線至 Monday + 對於 OAuth 驗證：提供您要連線之 Monday 的**字符 URL** 和**使用者管理的用戶端應用程式 ClientId**。 + 對於自訂身分驗證：選取身分驗證類型 **CUSTOM** 以連線至 Monday。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。選擇**下一步**。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Monday 實體中讀取 **先決條件** + 您要從中讀取的 Monday 物件。請參閱以下支援的實體表格，以檢查可用實體。 **來源的支援實體** 實體清單： + 帳戶：[https://developer.monday.com/api-reference/docs/account\$1queries](https://developer.monday.com/api-reference/docs/account#queries) + 電路板：[https://developer.monday.com/api-reference/docs/boards\$1queries](https://developer.monday.com/api-reference/docs/boards#queries) + 欄位：[https://developer.monday.com/api-reference/docs/columns\$1queries](https://developer.monday.com/api-reference/docs/columns#queries) + 文件：[https://developer.monday.com/api-reference/docs/docs\$1queries](https://developer.monday.com/api-reference/docs/docs#queries) + 文件區塊：[https://developer.monday.com/api-reference/docs/blocks\$1queries](https://developer.monday.com/api-reference/docs/blocks#queries) + 檔案：[https://developer.monday.com/api-reference/docs/files\$1queries](https://developer.monday.com/api-reference/docs/files#queries) + 資料夾：[https://developer.monday.com/api-reference/docs/folders\$1queries](https://developer.monday.com/api-reference/docs/folders#queries) + 群組：[https://developer.monday.com/api-reference/docs/groups\$1queries](https://developer.monday.com/api-reference/docs/groups#queries) + 項目：[https://developer.monday.com/api-reference/docs/items\$1queries](https://developer.monday.com/api-reference/docs/items#queries) + 子項目：[https://developer.monday.com/api-reference/docs/subitems\$1queries](https://developer.monday.com/api-reference/docs/subitems#queries) + 標籤：[https://developer.monday.com/api-reference/docs/tags-queries\$1queries](https://developer.monday.com/api-reference/docs/tags-queries#queries) + 團隊：[https://developer.monday.com/api-reference/docs/teams\$1queries](https://developer.monday.com/api-reference/docs/teams#queries) + 更新：[https://developer.monday.com/api-reference/docs/updates\$1queries](https://developer.monday.com/api-reference/docs/updates#queries) + 使用者：[https://developer.monday.com/api-reference/docs/users\$1queries](https://developer.monday.com/api-reference/docs/users#queries) + 工作區：[https://developer.monday.com/api-reference/docs/workspaces\$1queries](https://developer.monday.com/api-reference/docs/workspaces#queries) | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 帳戶 | 否 | 否 | 否 | 是 | 否 | | 電路板 | 是 | 是 | 否 | 是 | 否 | | 資料欄 | 否 | 否 | 否 | 是 | 否 | | 文件 | 是 | 是 | 否 | 是 | 否 | | 文件區塊 | 否 | 是 | 否 | 是 | 否 | | 檔案 | 是 | 否 | 否 | 是 | 否 | | Groups (群組) | 否 | 否 | 否 | 是 | 否 | | 項目 | 是 | 是 | 否 | 是 | 否 | | 子項目 | 否 | 否 | 否 | 是 | 否 | | Tags (標籤) | 是 | 否 | 否 | 是 | 是 | | 團隊 | 是 | 否 | 否 | 是 | 否 | | 更新 | 否 | 是 | 否 | 是 | 否 | | 使用者 | 是 | 是 | 否 | 是 | 否 | | 工作區 | 是 | 是 | 否 | 是 | 否 | | 資料夾 | 是 | 是 | 否 | 是 | 否 | **範例** ``` monday_read = glueContext.create_dynamic_frame.from_options( connection_type="monday", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "account", "API_VERSION": "v2" } ``` # Monday 連線選項參考 以下是 Monday 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Monday 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。要使用的 Monday Rest API 版本。範例：v2。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 限制 以下是 Monday 連接器的限制： + 動態中繼資料回應與文件存在某些衝突，如下所述： + 群組、資料欄實體支援篩選操作，但其在動態中繼資料端點中不存在，因此會保留為不可篩選的實體。 + 動態端點包含大約 15000 多行，並在單一回應中傳回所有實體的中繼資料，由於欄位平均需要 10 秒才能載入，因此在執行任務時需要額外的時間。 + 如需 Monday 速率限制，請參閱下表。動態實體回應資料的巨大規模會導致明顯的延遲，欄位平均需要 10 秒才能載入。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/monday-connector-limitations.html) ## 建立新的 Monday 帳戶： 1. 導覽至 Monday 的首頁 [https://monday.com/](https://monday.com/)，然後選擇**登入**。 1. 系統會將您重新導向至登入頁面。在頁面底部，選擇**上傳**。 1. 輸入電子郵件地址，然後選擇**繼續**。或者，您可以使用 Google 登入。 1. 輸入所需的詳細資訊，然後選擇**繼續**。 1. 完成問卷問題，並遵循步驟完成帳戶建立程序。 **註冊 OAuth 應用程式：** 1. 登入您的 monday.com 帳戶。按一下螢幕左下角的頭像 (圖片圖示)。 1. 選擇**開發人員**。 1. 選擇**建立應用程式**。 1. 完成名稱和描述的必要欄位。 1. 導覽至右側出現的 "OAuth" 區段，新增範圍，然後選擇「儲存功能」。 1. 導覽至範圍旁邊的「重新導向 URL」索引標籤，新增重新導向 URL，然後選擇「儲存功能」。 1. 在**重新導向 URL** 索引標籤下，提供應用程式的 URL。這應該是 https://\$1region-code\$1.console.aws.amazon.com/appflow/oauth。例如，如果您使用的是 `us-east-1 `，則可以新增 `https://us-east-1.console.aws.amazon.com/appflow/oauth`。 1. 應用程式現在已準備好可供使用。您可以在「基本資訊」區段中找到您的憑證。記下您的用戶端 ID 和用戶端機密字串。這些字串用於使用 AppFlow 連接器與此應用程式建立連線。 **產生個人存取字符：** 目前，monday.com 僅提供我們的 V2 API 字符，這些字符都是個人字符。若要存取 API 字符，您可以根據使用者層級使用兩種方法之一。管理員使用者可以利用這兩種方法來取得 API 字符。成員使用者可以從「開發人員」索引標籤存取 API 字符。 Admins - 如果您是 monday.com 帳戶的管理員使用者，可以從 "Admin" 索引標籤存取您的 API 字符，步驟如下： 1. 登入您的 monday.com 帳戶。按一下螢幕左下角的頭像 (圖片圖示)。 1. 從產生的功能表中選取「管理」(這需要您擁有管理員許可)。 1. 導覽至 "API" 區段並產生「API V2 字符」。您可以複製字符並使用其。 開發人員 - 如果您是 monday.com 帳戶的成員使用者，可以從「開發人員」索引標籤存取您的 API 字符，步驟如下： 1. 登入您的 monday.com 帳戶。按一下螢幕左下角的頭像 (圖片圖示)。 1. 從產生的功能表中選取「開發人員」。 1. 在頂端功能表中，選擇「開發人員」下拉式功能表。在名為「我的存取字符」的下拉式功能表上，選取第一個選項。 # 在 AWS Glue Studio 中連線至 MongoDB AWS Glue 會提供 MongoDB 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 MongoDB、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 **Topics** + [建立 MongoDB 連線](creating-mongodb-connection.md) + [建立 MongoDB 來源節點](creating-mongodb-source-node.md) + [建立 MongoDB目標節點](creating-mongodb-target-node.md) + [進階選項](#creating-mongodb-connection-advanced-options) # 建立 MongoDB 連線 **先決條件：** + 如果您的 MongoDB 執行個體位於 Amazon VPC 中，請設定 Amazon VPC 以允許您的 AWS Glue 任務與 MongoDB 執行個體通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 AWS Glue 將在執行任務時使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 MongoDB 執行個體與此位置之間的網路流量。根據您的網路配置，這可能需要變更安全群組規則、網路 ACL、NAT 閘道及對等連線。 **設定連至 MongoDB 的連線：** 1. 或者，在 中 AWS Secrets Manager，使用您的 MongoDB 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *mongodbUser* 值來建立 `username` 金鑰對。 在選取**鍵/值組**時，請使用 *mongodbPass* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便未來在 AWS Glue中使用。 + 選取**連線類型**時，請選取 **MongoDB** 或 **MongoDB Atlas**。 + 選取 **MongoDB URL** 或 **MongoDB Atlas URL** 時，請提供 MongoDB 執行個體的主機名稱。 MongoDB URL 會以 `mongodb://mongoHost:mongoPort/mongoDBname` 格式提供。 MongoDB Atlas URL 會以 `mongodb+srv://mongoHost/mongoDBname` 格式提供。 + 如果您選擇建立 Secrets Manager 秘密，請選擇 AWS Secrets Manager **憑證類型**。 然後，在 **AWS 密碼**中提供 *secretName*。 + 如果您選擇提供**使用者名稱和密碼**，請提供 *mongodbUser* 和 *mongodbPass*。 1. 在下列情況中，您可能需要其他組態： + 對於 Amazon VPC AWS 中託管於 的 MongoDB 執行個體 + 您需要提供 Amazon VPC 連線資訊給定義 MongoDB 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 建立 a AWS Glue MongoDB 連線後，您必須先執行下列步驟，才能執行 AWS Glue 任務： + 在視覺化編輯器中使用 AWS Glue 任務時，您必須提供任務的 Amazon VPC 連線資訊，才能連線至 MongoDB。在 Amazon VPC 中識別合適的位置，並將其提供給 AWS Glue MongoDB 連線。 + 如果您選擇建立 Secrets Manager 秘密，請授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 *secretName* 的許可。 # 建立 MongoDB 來源節點 ## 必要先決條件 + A AWS Glue MongoDB 連線，如上節所述：[建立 MongoDB 連線](creating-mongodb-connection.md)。 + 如果您選擇建立 Secrets Manager 密碼，請針對任務授予適當的權限，以讀取連線所使用的密碼。 + 您想要讀取的 MongoDB 集合。您將需要集合的識別資訊。 MongoDB 集合由資料庫名稱與集合名稱 *mongodbName*、*mongodbCollection* 識別。 ## 新增 MongoDB 資料來源 **新增**資料來源 – MongoDB** 節點：** 1. 選擇 MongoDB 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 MongoDB 連線**。如需詳細資訊，請參閱前一 [建立 MongoDB 連線](creating-mongodb-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇**資料庫**。輸入 *mongodbName*。 1. 選擇**集合**。輸入 *mongodbCollection*。 1. 選擇**分割程式**、**分割區大小 (MB)** 及**分割區金鑰**。如需有關分割區參數的詳細資訊，請參閱 ["connectionType": "mongodb" as Source](aws-glue-programming-etl-connect-mongodb-home.md#etl-connect-mongodb-as-source)。 1. 在**自訂 MongoDB 屬性**中，視需要輸入參數和值。 # 建立 MongoDB目標節點 ## 必要先決條件 + A AWS Glue MongoDB 連線，使用 AWS Secrets Manager 秘密設定，如上節所述：[建立 MongoDB 連線](creating-mongodb-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 MongoDB 資料表 *tableName*。 ## 新增 MongoDB 資料目標 **新增**資料目標 – MongoDB** 節點：** 1. 選擇 MongoDB 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 MongoDB 連線**。如需詳細資訊，請參閱前一 [建立 MongoDB 連線](creating-mongodb-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇**資料庫**。輸入 *mongodbName*。 1. 選擇**集合**。輸入 *mongodbCollection*。 1. 選擇**分割程式**、**分割區大小 (MB)** 及**分割區金鑰**。如需有關分割區參數的詳細資訊，請參閱 ["connectionType": "mongodb" as Source](aws-glue-programming-etl-connect-mongodb-home.md#etl-connect-mongodb-as-source)。 1. 選擇**重試寫入** (如有需要)。 1. 在**自訂 MongoDB 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 MongoDB 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[MongoDB 連線選項參考](aws-glue-programming-etl-connect-mongodb-home.md#aws-glue-programming-etl-connect-mongodb)。 # 連線至 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，以確保資料一致性。 # 在 AWS Glue Studio 中連線至 OpenSearch Service AWS Glue 會提供 Amazon OpenSearch Service 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 Amazon OpenSearch Service、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。此功能與 OpenSearch Service Serverless 不相容。 AWS Glue Studio 會為 Amazon OpenSearch Service 建立統一連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 **Topics** + [建立 OpenSearch Service 連線](creating-opensearch-connection.md) + [建立 OpenSearch Service 來源節點](creating-opensearch-source-node.md) + [建立 OpenSearch Service 目標節點](creating-opensearch-target-node.md) + [進階選項](#creating-opensearch-connection-advanced-options) # 建立 OpenSearch Service 連線 **先決條件：** + 依照 Amazon OpenSearch Service 文件中的說明，識別您想要讀取的網域端點 *aosEndpoint* 和連接埠 *aosPort* 或建立資源。如需有關建立網域的詳細資訊，請參閱《Amazon OpenSearch Service 文件》中的[建立和管理 Amazon OpenSearch Service 網域](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)。 Amazon OpenSearch Service 網域端點將會顯示下列預設格式：https://search-*domainName*-*unstructuredIdContent*.*region*.es.amazonaws.com。如需有關識別網域端點的詳細資訊，請參閱《Amazon OpenSearch Service 文件》中的[建立和管理 Amazon OpenSearch Service 網域](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)。 識別或產生您網域的 HTTP 基本身分驗證憑證 *aosUser* 和 *aosPassword*。 **設定 OpenSearch Service 的連線：** 1. 在 中 AWS Secrets Manager，使用您的 OpenSearch Service 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *aosUser* 值來建立 `USERNAME` 金鑰對。 + 在選取**鍵/值組**時，請使用 *aosPassword* 值來建立 `PASSWORD` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便未來在 AWS Glue中使用。 + 選取**連線類型**時，請選取 OpenSearch Service。 + 選取網域端點時，請提供 *aosEndpoint*。 + 選取連接埠時，請提供 *aosPort*。 + 選取 **AWS 機密**時，請提供 *secretName*。 # 建立 OpenSearch Service 來源節點 ## 必要先決條件 + A AWS Glue OpenSearch Service 連線，使用 AWS Secrets Manager 秘密設定，如上節所述：[建立 OpenSearch Service 連線](creating-opensearch-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要讀取的 OpenSearch Service 索引 *aosIndex*。 ## 新增 OpenSearch Service 資料來源 **新增 **資料來源 – OpenSearch Service** 節點：** 1. 選擇 OpenSearch Service 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 OpenSearch Service 連線**。如需詳細資訊，請參閱前一 [建立 OpenSearch Service 連線](creating-opensearch-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 提供您想要讀取的**索引**。 1. 您可以選擇提供**查詢** (OpenSearch 查詢)，以產生更特定的結果。如需有關寫入 OpenSearch 查詢的詳細資訊，請諮詢 [從 OpenSearch Service 索引讀取](aws-glue-programming-etl-connect-opensearch-home.md#aws-glue-programming-etl-connect-opensearch-read)。 1. 在**自訂 OpenSearch Service 屬性**中，視需要輸入參數和值。 # 建立 OpenSearch Service 目標節點 ## 必要先決條件 + A AWS Glue OpenSearch Service 連線，使用 AWS Secrets Manager 秘密設定，如上節所述：[建立 OpenSearch Service 連線](creating-opensearch-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 OpenSearch Service 索引 *aosIndex*。 ## 新增 OpenSearch Service 資料目標 **新增 **資料目標 – OpenSearch Service** 節點：** 1. 選擇 OpenSearch Service 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 OpenSearch Service 連線**。如需詳細資訊，請參閱前一 [建立 OpenSearch Service 連線](creating-opensearch-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 提供您想要讀取的**索引**。 1. 在**自訂 OpenSearch Service 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 OpenSearch Service 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[OpenSearch Service 連線](aws-glue-programming-etl-connect-opensearch-home.md)。 # 連線至 Okta Okta API 是 Okta 的程式設計介面，用於管理大型或複雜的 Okta 帳戶和行銷活動。如果您是 Okta 使用者，您可以 AWS Glue 連線到您的 Okta 帳戶。然後，您可以在 ETL 任務中使用 Okta 作為資料來源。執行這些任務以在 Okta AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Okta](okta-support.md) + [包含用於建立和使用連線的 API 操作的政策](okta-configuring-iam-permissions.md) + [設定 Okta](okta-configuring.md) + [設定 Okta 連線](okta-configuring-connections.md) + [從 Okta 實體中讀取](okta-reading-from-entities.md) + [Okta 連線選項參考](okta-connection-options.md) + [Okta 新帳戶和開發人員應用程式建立步驟](okta-create-account.md) + [限制](okta-connector-limitations.md) # AWS Glue 支援 Okta AWS Glue 支援 Okta，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Okta 查詢資料。 **支援作為目標？** 否。 **支援的 Okta API 版本** v1。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Okta 您必須先符合下列要求，才能使用 AWS Glue 往返 Okta 傳輸資料： ## 最低需求 + 您擁有一個 Okta 帳戶。如需有關建立帳戶的詳細資訊，請參閱[Okta 新帳戶和開發人員應用程式建立步驟](okta-create-account.md)。 + 您的 Okta 帳戶已啟用 API 存取。 + 您已在 Okta 帳戶中建立 OAuth2 API 整合。此整合提供用戶端登入資料，在對您的帳戶進行驗證呼叫時， AWS Glue 會使用 安全地存取您的資料。如需詳細資訊，請參閱建立用戶端應用程式和 OAuth2.0 憑證的步驟：Okta 新帳戶和開發人員應用程式建立步驟 + 您擁有一個具有 OktaApiToken 的 Okta 帳戶。請參閱 [Okta 文件](https://developer.okta.com/docs/guides/create-an-api-token/main/#create-the-token)。 如果您符合這些要求，就可以 AWS Glue 連線到 Okta 帳戶。對於一般連線，不需要在 Okta 中執行任何其他操作。 # 設定 Okta 連線 Okta 支援兩種類型的身分驗證機制： + OAuth 驗證：Okta 支援 `AUTHORIZATION_CODE` 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Okta，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Okta 執行個體。 + 使用者可以選擇在 Okta 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Okta 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需詳細資訊，請參閱[有關為授權碼 OAuth 流程建立連線應用程式的公有 Okta 文件](https://developers.google.com/workspace/guides/create-credentials)。 + 自訂驗證： + 如需有關產生自訂授權所需 API 金鑰的公有 Okta 文件，請參閱 [Okta 文件](https://developer.okta.com/docs/guides/create-an-api-token/main/#create-the-token)。 若要設定 Okta 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於 OAuth 驗證： + 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 對於自訂身分驗證： + 對於客戶管理的連線應用程式，機密應包含以 `OktaApiToken` 作為金鑰的連線應用程式消費者機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在**連線**下，選擇建立連線。 1. 選取**資料來源**時，請選取 Okta。 1. 提供 Okta 子網域。 1. 選取 Okta 帳戶的 Okta 網域 URL。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 選取身分驗證類型以連線至資料來源。 1. 對於 OAuth2 身分驗證類型，請提供 Okta 應用程式的**使用者管理的用戶端應用程式 ClientId**。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Okta 實體中讀取 **先決條件** + 您要從中讀取的 Okta 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 應用程式 | 是 | 是 | 否 | 是 | 否 | | Devices | 是 | 是 | 否 | 是 | 是 | | Groups (群組) | 是 | 是 | 是 | 是 | 是 | | 使用者 | 是 | 是 | 是 | 是 | 是 | | 使用者類型 | 否 | 否 | 否 | 是 | 否 | **範例** ``` okta_read = glueContext.create_dynamic_frame.from_options( connection_type="Okta", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "applications", "API_VERSION": "v1" } ``` **Okta 實體和欄位詳細資訊** 實體清單： + 應用程式：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/) + 裝置：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/) + 群組：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/) + 使用者：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/) + 使用者類型：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/) **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 **範例** ``` okta_read = glueContext.create_dynamic_frame.from_options( connection_type="okta", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "lastUpdated", "API_VERSION": "v1", "PARTITION_FIELD": "lastMembershipUpdated" "LOWER_BOUND": "2022-08-10T10:28:46.000Z" "UPPER_BOUND": "2024-08-10T10:28:46.000Z" "NUM_PARTITIONS": "10" } ``` # Okta 連線選項參考 以下是 Okta 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Okta 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您要使用的 Okta Rest API 版本。範例：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。用於讀取。要讀取的分區數目。 # Okta 新帳戶和開發人員應用程式建立步驟 在 Okta 上建立開發人員帳戶，以存取 Okta API。免費 Okta 開發人員帳戶可提供存取權，讓您存取 Okt API 所需的大多數關鍵開發人員功能。 **若要在 Okta 上建立開發人員帳戶** 1. 導覽至 [https://developer.okta.com/signup/](https://console.cloud.google.com)。 1. 輸入帳戶資訊電子郵件、名字、姓氏和國家/區域。選擇**我不是機器人**，然後選擇**註冊**。 1. 驗證郵件會傳送到您註冊的郵件 ID。您將在電子郵件中收到用來啟用 Okta 開發人員帳戶的連結。選擇 **Activate (啟用)**。 1. 系統會將您重新導向至密碼重設頁面。輸入兩次新密碼，然後選擇**重設密碼**。 1. 系統會將您重新導向至 Okta 開發人員帳戶儀表板。 **若要建立用戶端應用程式和 OAuth 2.0 憑證** 1. 在開發人員儀表板中，選擇建立應用程式整合。 ![\[螢幕擷取畫面會顯示「建立 OAuth 用戶端 ID」頁面和「已授權的重新導向 URI」區段。可在此新增 URI，並在需要時選擇「新增 URI」。完成後，選擇「建立」。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/create-client-app-step-1.png) 1. **建立新的應用程式整合**視窗隨即出現，並顯示各種登入方法。選取 **OIDC –OpenID Connect**。 1. 向下捲動至「應用程式類型」區段。選取為 **Web 應用程式**，然後選擇**下一步**。 1. 在「新 Web 應用程式整合」畫面中，填入下列資訊： + 應用程式整合名稱 - 輸入應用程式的名稱。 + 授權類型 - 從清單中選擇**授權碼**和**重新整理字符**。 + 登入重新導向 URI - 選擇**新增 URI** 並新增 `https://{regioncode}.console.aws.amazon.com/appflow/oauth`。例如，如果您使用的是 `us-west-2 (Oregon)` ，則可以新增 `https://us-east-1.console.aws.amazon.com/appflow/oauth`。 + 受控存取 - 視需要將應用程式指派給使用者群組，然後選擇**儲存**。 1. 會產生用戶端 ID 和用戶端機密。 # 限制 以下是 Okta 連接器的限制： + 對於「應用程式」實體，只能套用一個篩選條件。如果套用的篩選條件超過 1 個，則會傳回 400 Bad Request 錯誤，並附上錯誤摘要 –「無效的搜尋條件」。 + 只有搜尋查詢才支援排序依據。例如 ` http://dev-15940405.okta.com/api/v1/groups?search=type e.q. "OKTA_GROUP"&sortBy=lastUpdated&sortOrder=asc ` # 連線至 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.) 欄位的值。 # 連線至 Monday Pendo 為使用者互動資料提供了豐富的資料存放區。客戶會將此資料傳輸到 ， AWS 以便與其他產品資料聯結、執行其他分析和儀表板加入，並在他們選擇時設定提醒。 **Topics** + [AWS Glue 支援 Pendo](pendo-support.md) + [包含用於建立和使用連線的 API 操作的政策](pendo-configuring-iam-permissions.md) + [設定 Pendo](pendo-configuring.md) + [設定 Pendo 連線](pendo-configuring-connections.md) + [從 Pendo 實體中讀取](pendo-reading-from-entities.md) + [Pendo 連線選項](pendo-connection-options.md) + [限制](pendo-connector-limitations.md) # AWS Glue 支援 Pendo AWS Glue 支援 Pendo，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Pendo 查詢資料。 **支援作為目標？** 否。 **支援的 Pendo API 版本** v1 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Pendo 您必須先符合下列要求，才能使用 從 Pendo AWS Glue 傳輸： ## 最低需求 + 您擁有一個具有 `apiKey` 的 Pendo 帳戶，且已啟用 `write access`。 + 您的 Pendo 帳戶具有包含有效授權的 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Pendo 帳戶。對於一般連線，不需要在 Pendo 中執行任何其他操作。 # 設定 Pendo 連線 Pendo 支援自訂身分驗證。 如需有關產生自訂授權所需 API 金鑰的公有 Pendo 文件，請參閱[身分驗證 – Pendo REST API 文件](https://engageapi.pendo.io/?bash#getting-started) 若要設定 Pendo 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： + 對於客戶管理的連線應用程式，機密應包含以 `apiKey` 作為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**資料來源**時，請選取 Pendo。 1. 提供您要連線的 PayPal 執行個體的 `instanceUrl`。 1. 選取 AWS Glue 可擔任的 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`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為其他網路連線。 # 從 Pendo 實體中讀取 **先決條件** 您要從中讀取的 Pendo 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** + [功能](https://developers.pendo.io/docs/?bash#feature) + [指南](https://developers.pendo.io/docs/?bash#guide) + [頁面](https://developers.pendo.io/docs/?bash#page) + [報告](https://developers.pendo.io/docs/?bash#report) + [報告資料](https://developers.pendo.io/docs/?bash#return-report-contents-as-array-of-json-objects) + [訪客](https://developers.pendo.io/docs/?bash#visitor) + [帳戶](https://developers.pendo.io/docs/?bash#entities) + [事件](https://developers.pendo.io/docs/?bash#events-grouped) + [特徵事件](https://developers.pendo.io/docs/?bash#events-grouped) + [指南事件](https://developers.pendo.io/docs/?bash#events-ungrouped) + [頁面事件](https://developers.pendo.io/docs/?bash#events-grouped) + [輪詢事件 ](https://developers.pendo.io/docs/?bash#events-ungrouped) + [追蹤事件](https://developers.pendo.io/docs/?bash#events-grouped) | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 功能 | 否 | 否 | 否 | 是 | 否 | | 指南 | 否 | 否 | 否 | 是 | 否 | | 頁面 | 否 | 否 | 否 | 是 | 否 | | 報告 | 否 | 否 | 否 | 是 | 否 | | 報告資料 | 否 | 否 | 否 | 是 | 否 | | 訪客 (彙總 API) | 是 | 否 | 是 | 是 | 否 | | 帳戶 (彙總 API) | 是 | 否 | 是 | 是 | 否 | | 事件 (彙總 API) | 是 | 否 | 是 | 是 | 否 | | 特徵事件 (彙總 API) | 是 | 否 | 是 | 是 | 是 | | 指南事件 (彙總 API) | 是 | 否 | 是 | 是 | 是 | | 帳戶 (彙總 API) | 是 | 否 | 是 | 是 | 是 | | 頁面事件 (彙總 API) | 是 | 否 | 是 | 是 | 是 | | 輪詢事件 (彙總 API) | 是 | 否 | 是 | 是 | 是 | | 追蹤事件 (彙總 API) | 是 | 否 | 是 | 是 | 是 | **範例** ``` Pendo_read = glueContext.create_dynamic_frame.from_options( connection_type="glue.spark.Pendo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "feature", "API_VERSION": "v1", "INSTANCE_URL": "instanceUrl" } ``` ## 分區查詢 如果想要在 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`：分區數目。 下表說明實體分區欄位支援詳細資訊： | 實體名稱 | | --- | | 事件 | | 特徵事件 | | 指南事件 | | 頁面事件 | | 輪詢事件 | | 追蹤事件 | 範例： ``` pendo_read = glueContext.create_dynamic_frame.from_options( connection_type="glue.spark.pendo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "event", "API_VERSION": "v1", "INSTANCE_URL": "instanceUrl" "NUM_PARTITIONS": "10", "PARTITION_FIELD": "appId" "LOWER_BOUND": "4656" "UPPER_BOUND": "7788" } ``` # Pendo 連線選項 以下是 Pendo 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Pendo 中的物件名稱。 + `INSTANCE_URL`(String) - (必要) 具有下列允許值的有效 Pendo 執行個體 URL： + [預設](https://app.pendo.io/) + [歐洲](https://app.eu.pendo.io/) + [US1](https://us1.app.pendo.io/) + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Pendo Engage Rest API 版本。例如：3.0。 + `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。用於讀取。要讀取的分區數目。 # 限制 以下是 Pendo 連接器的限制： + Pendo 中不支援分頁。 + 僅彙總 API 物件 (`Account`、`Event`、`Feature Event`、`Guide Events`、`Page Event`、`Poll Event`、`Track Event` 和 `Visitor`) 支援篩選 + DateTimeRange 是彙總 API 物件的強制性篩選參數 (`Event`、`Feature Event`、`Guide Events`、`Page Event`、`Poll Event,`、`Track Event`) + dayRange 時段會四捨五入至時區中時段的開始。例如，如果提供的篩選條件為 `2023-01-12T07:55:27.065Z`，則此時段將四捨五入至該時段的開始，也就是 `2023-01-12T00:00:00Z`。 # 連線至 Pipedrive Pipedrive 是一種銷售管道 CRM，旨在協助小型企業管理潛在客戶、追蹤銷售活動和完成更多交易。Pipedrive 可讓小型企業中的銷售團隊：簡化流程，並將銷售資料合併到一個統一的 CRM 銷售工具中。如果您是 Pipedrive 使用者，您可以 AWS Glue 連線至 Pipedrive 帳戶。然後，您可以在 ETL 任務中使用 Pipedrive 作為資料來源。執行這些任務以在 Pipedrive AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Pipedrive](pipedrive-support.md) + [包含用於建立和使用連線的 API 操作的政策](pipedrive-configuring-iam-permissions.md) + [設定 Pipedrive](pipedrive-configuring.md) + [設定 Pipedrive 連線](pipedrive-configuring-connections.md) + [從 Pipedrive 實體中讀取](pipedrive-reading-from-entities.md) + [Pipedrive 連線選項參考](pipedrive-connection-options.md) + [限制](pipedrive-connector-limitations.md) # AWS Glue 支援 Pipedrive AWS Glue 支援 Pipedrive，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Pipedrive 查詢資料。 **支援作為目標？** 否。 **支援的 Pipedrive API 版本** v1。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Pipedrive 您必須先符合下列要求，才能使用 從 Pipedrive AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個 Pipedrive 帳戶。 + 您的 Pipedrive 帳戶已啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Pipedrive 帳戶。對於一般連線，不需要在 Pipedrive 中執行任何其他操作。 # 設定 Pipedrive 連線 Pipedrive 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。預設情況下，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式，在該應用程式中，除了 Pipedrive 執行個體 URL 之外，他們不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Pipedrive，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Pipedrive 執行個體。 + 使用者應選擇在 Pipedrive 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Pipedrive 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符的作用時間為一小時，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需詳細資訊，請參閱[有關為 AUTHORIZATION\$1CODE OAuth 流程建立連線應用程式的文件](https://developers.pipedrive.com/docs/api/v1/Oauth)。 若要設定 Pipedrive 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於客戶管理的連線應用程式，機密應包含以 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作為金鑰的連線應用程式消費者機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在「資料連線」下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Pipedrive。 1. 提供您的 Pipedrive **instanceURL**。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 提供您要連線之 Pipedrive 的使用者管理的用戶端應用程式 ClientId。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。選擇**下一步**。 1. 提供**連線名稱**，然後選擇**下一步**。 1. 在下一頁中選擇**建立連線**。系統會要求您登入 Pipedrive。提供使用者名稱和密碼，然後選擇**登入**。 1. 登入後，請選擇**繼續前往應用程式**。現在連線已準備好可供使用。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Pipedrive 實體中讀取 **先決條件** + 您要從中讀取的 Pipedrive 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 活動 | 是 | 是 | 否 | 是 | 是 | | 活動類型 | 否 | 否 | 否 | 是 | 否 | | 呼叫日誌 | 否 | 否 | 否 | 是 | 否 | | 貨幣 | 是 | 是 | 否 | 是 | 否 | | 交易 | 是 | 是 | 是 | 是 | 是 | | 潛在客戶 | 是 | 是 | 是 | 是 | 否 | | 潛在客戶來源 | 否 | 是 | 否 | 是 | 否 | | 潛在客戶標籤 | 否 | 否 | 否 | 否 | 否 | | 備註 | 是 | 是 | 是 | 是 | 是 | | 組織 | 是 | 是 | 否 | 是 | 是 | | 許可集 | 是 | 否 | 否 | 是 | 否 | | 人物 | 是 | 是 | 是 | 是 | 是 | | 管道 | 否 | 是 | 否 | 是 | 否 | | 產品 | 是 | 是 | 否 | 是 | 是 | | 角色 | 否 | 是 | 否 | 是 | 否 | | 階段 | 是 | 是 | 否 | 是 | 否 | | 使用者 | 否 | 否 | 否 | 是 | 否 | **範例** ``` pipedrive_read= glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1" } ``` **Pipedrive 實體和欄位詳細資訊** 實體清單： + 活動：[https://developers.pipedrive.com/docs/api/v1/Activities](https://developers.pipedrive.com/docs/api/v1/Activities) + 活動類型：[https://developers.pipedrive.com/docs/api/v1/ActivityTypes](https://developers.pipedrive.com/docs/api/v1/ActivityTypes) + 呼叫日誌：[https://developers.pipedrive.com/docs/api/v1/CallLogs](https://developers.pipedrive.com/docs/api/v1/CallLogs) + 貨幣：[https://developers.pipedrive.com/docs/api/v1/Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies) + 交易：[https://developers.pipedrive.com/docs/api/v1/Deals](https://developers.pipedrive.com/docs/api/v1/Deals) + 潛在客戶：[https://developers.pipedrive.com/docs/api/v1/Leads](https://developers.pipedrive.com/docs/api/v1/Leads) + 潛在客戶來源：[https://developers.pipedrive.com/docs/api/v1/LeadSources](https://developers.pipedrive.com/docs/api/v1/LeadSources) + 潛在客戶標籤：[https://developers.pipedrive.com/docs/api/v1/LeadLabels](https://developers.pipedrive.com/docs/api/v1/LeadLabels) + 備註：[https://developers.pipedrive.com/docs/api/v1/Notes](https://developers.pipedrive.com/docs/api/v1/Notes) + 組織：[https://developers.pipedrive.com/docs/api/v1/Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations) + 許可集：[https://developers.pipedrive.com/docs/api/v1/PermissionSets](https://developers.pipedrive.com/docs/api/v1/PermissionSets) + 人員：[https://developers.pipedrive.com/docs/api/v1/Persons](https://developers.pipedrive.com/docs/api/v1/Persons) + 管道：[https://developers.pipedrive.com/docs/api/v1/Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines) + 產品：[https://developers.pipedrive.com/docs/api/v1/Products](https://developers.pipedrive.com/docs/api/v1/Products) + 角色：[https://developers.pipedrive.com/docs/api/v1/Roles](https://developers.pipedrive.com/docs/api/v1/Roles) + 階段：[https://developers.pipedrive.com/docs/api/v1/Stages](https://developers.pipedrive.com/docs/api/v1/Stages) + 使用者：[https://developers.pipedrive.com/docs/api/v1/Users](https://developers.pipedrive.com/docs/api/v1/Users) | 實體 | 資料類型 | 支援的運算子 | | --- | --- | --- | | 活動、交易、備註、組織、人員和產品。 | Date | '=' | | | Integer | '=' | | | String | '=' | | | Boolean | '=' | ## 分區查詢 在 Pipedrive 中，只有「活動」實體的一個欄位 (due\$1date) 支援欄位型分區。其是「日期」欄位。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 **範例** ``` pipedrive_read = glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1", "PARTITION_FIELD": "due_date" "LOWER_BOUND": "2023-09-07T02:03:00.000Z" "UPPER_BOUND": "2024-05-07T02:03:00.000Z" "NUM_PARTITIONS": "10" } ``` # Pipedrive 連線選項參考 以下是 Pipedrive 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Pipedrive 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Pipedrive Rest API 版本。範例：v1。 + `INSTANCE_URL`(String) - (必要) 使用者想要執行操作之執行個體的 URL。範例：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。用於讀取。要讀取的分區數目。 # 限制 以下是 Pipedrive 連接器的限制： + Pipedrive 僅支援一個實體的欄位型分區 (活動)。 + 對於活動、交易、備註、人員、組織和產品實體，Pipedrive 支援記錄型分區。 + 在交易實體中，如果使用無效的篩選條件值，則作為篩選條件的狀態欄位將傳回所有記錄。 + 在交易實體中，不支援使用多個欄位進行排序。 + 為了取得效能資料，我們使用本機 AWS 帳戶。不過，由於本機重新整理存取權杖的限制，處理 1 GB 資料 AWS Glue 的任務會失敗。因此，我們已使用 179 MB 的資料最佳化效能測試，上述結果是以此最佳化為基礎。不過，我們觀察到，隨著分區數目的增加，相較於單一分區，SaaS 端點需要更多時間。我們已針對此行為諮詢 Pipedrive 支援團隊，他們告知我們 Pipedrive 正在默默地限流請求並延遲回應。因此，使用大型資料集執行 AWS Glue 任務或多次呼叫相同的 API 端點時，可能會導致 Pipedrive API 實作導致逾時問題。不過，隨著分區數目的增加，連接器和 shim 回應時間會如預期減少。 # 連線至 Productboard Productboard 是產品管理系統，可協助產品團隊更快地將正確的產品推向市場。超過 3,000 家以產品為主導的現代公司 (例如 Zendesk、UiPath 和 Microsoft)，使用 Productboard 來了解使用者的真實需求、排定後續建置內容的優先順序，並凝聚團隊共識，圍繞藍圖協同發力。 **Topics** + [AWS Glue 支援 Productboard](productboard-support.md) + [包含用於建立和使用連線的 API 操作的政策](productboard-configuring-iam-permissions.md) + [設定 Productboard](productboard-configuring.md) + [設定 Productboard 連線](productboard-configuring-connections.md) + [從 Productboard 實體中讀取](productboard-reading-from-entities.md) + [Productboard 連線選項](productboard-connection-options.md) + [建立 Productboard 帳戶](productboard-create-account.md) + [限制](productboard-connector-limitations.md) # AWS Glue 支援 Productboard AWS Glue 支援 Productboard，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Productboard 查詢資料。 **支援作為目標？** 否。 **支援的 Productboard API 版本** v1 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Productboard 您必須先符合下列要求，才能使用 從 Productboard AWS Glue 傳輸： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Productboard 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Productboard 帳戶](productboard-create-account.md)。 + 您必須使用 服務存取建立 AWS 帳戶 AWS Glue。 + 您擁有 Productboard 帳戶的身分驗證詳細資訊 - 如果想要使用自訂身分驗證，則為 JWT 字符，如果想要使用 OAuth2.0，則為用戶端 ID 和機密。 + 如果使用者想要使用 `OAuth2.0`，請遵循[如何透過 OAuth2 與 Productboard 整合 - 開發人員文件](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation)的說明，[向 Productboard 註冊應用程式](https://app.productboard.com/oauth2/applications/new)並設定應用程式。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Productboard 帳戶。對於一般連線，不需要在 Productboard 中執行任何其他操作。 # 設定 Productboard 連線 Productboard 支援自訂身分驗證和 `OAuth2.0`。對於 `OAuth2.0`，Productboard 支援 `AUTHORIZATION_CODE` 授權類型。 + 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。根據預設，建立連線的使用者可能會依賴 AWS Glue 擁有的連線應用程式，除了其產品面板用戶端 ID 和用戶端秘密之外，不需要提供任何`OAuth`相關資訊。 AWS Glue 主控台會將使用者重新導向至 Productboard，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Productboard 執行個體。 + 使用者仍然可以選擇在 Productboard 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Productboard 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關為 `AUTHORIZATION_CODE OAuth` 流程建立連線應用程式的公有 Productboard 文件，請參閱[如何透過 OAuth2 與 Productboard 整合 - 開發人員文件](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation)。 若要設定 Productboard 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於 `OAuth` 驗證 – 針對客戶管理的連線應用程式：機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 + 對於 `Custom auth` – 針對客戶管理的連線應用程式：機密應包含以 `access_token` 作為金鑰的連線應用程式 `JWT token`。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**資料來源**時，請選取 Productboard。 1. 選取 AWS Glue 可擔任的 IAM 角色，並具有下列動作的許可： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 選取身分驗證類型以連線至資料來源： + 對于 `OAuth` 驗證 – 提供 Productboard 應用程式的 `Token URL` 和 `User Managed Client Application ClientId`。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為其他網路連線。 # 從 Productboard 實體中讀取 **先決條件** 您要從中讀取的 Productboard 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** + [濫用報告](https://productboard.com/developer/marketing/api/campaign-abuse/) + [自動化](https://productboard.com/developer/marketing/api/automation/list-automations/) + [行銷活動](https://productboard.com/developer/marketing/api/campaigns/list-campaigns/) + [按一下詳細資訊](https://productboard.com/developer/marketing/api/link-clickers/) + [清單](https://productboard.com/developer/marketing/api/link-clickers/) + [成員](https://productboard.com/developer/marketing/api/list-segment-members/) + [公開的詳細資訊](https://productboard.com/developer/marketing/api/list-members/) + [客群](https://productboard.com/developer/marketing/api/list-segments/) + [存放](https://productboard.com/developer/marketing/api/ecommerce-stores/list-stores/) + [已取消訂閱](https://productboard.com/developer/marketing/api/unsub-reports/) | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 功能 | 是 | 是 | 否 | 是 | 是 | | 元件 | 否 | 是 | 否 | 是 | 否 | | 產品 | 否 | 是 | 否 | 是 | 否 | | 功能狀態 | 否 | 是 | 否 | 是 | 是 | | 自訂欄位定義 | 否 | 是 | 否 | 是 | 否 | | 自訂欄位值 | 是 | 是 | 否 | 是 | 否 | **範例** ``` Productboard_read = glueContext.create_dynamic_frame.from_options( connection_type="Productboard", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "feature", "API_VERSION": "1" } ``` **Productboard 實體和欄位詳細資訊** + [功能](https://developer.productboard.com/#tag/features) + [元件](https://developer.productboard.com/#tag/components) + [功能狀態](https://developer.productboard.com/#tag/statuses) + [產品](https://developer.productboard.com/#tag/products) + [自訂欄位定義](https://developer.productboard.com/#tag/hierarchyEntitiesCustomFields) + [自訂欄位值](https://developer.productboard.com/#tag/hierarchyEntitiesCustomFieldsValues) # Productboard 連線選項 以下是 Productboard 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Productboard 中物件的名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Productboard Engage Rest API 版本。例如：3.0。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Productboard 帳戶 1. 導覽至 [Productboard 註冊頁面](https://app.productboard.com/)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 1. 在**帳戶名稱**欄位中，輸入 Productboard 帳戶的名稱，然後選取**我同意隱私權政策**核取方塊。 1. 在**現在建立工作區**頁面的**工作區 URL** 欄位中，輸入新工作區的 URL。然後選擇**繼續**前往下一頁，並提供剩餘的詳細資訊。 這會建立試用帳戶。試用帳戶可免費使用 15 天。試用期到期後，可以購買付費計劃。請記下您的電子郵件地址、密碼和工作區 URL。您將來需要此資訊來存取帳戶。」 **註冊 `OAuth2.0` 應用程式** 1. 導覽至 [Productboard 登入頁面](https://login.productboard.com/?locale=en)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 1. 選取右上角的**使用者**圖示，然後從下拉式功能表中選擇**帳戶和帳單**。 1. 選取**額外項目**，然後從下拉式功能表中選擇**已註冊的應用程式**。 1. 查找並選擇**註冊應用程式**。 1. 輸入下列詳細資訊： + **應用程式名稱** – 應用程式的名稱。 + **公司/組織** – 公司或組織的名稱。 + **應用程式網站** – 應用程式的網站。 + **重新導向 URI** – 重新導向 URI 模式是 URI 路徑 (或以逗號分隔的路徑清單)，Productboard 可以在登入流程完成時重新導向到該路徑 (如果請求)。例如 `https://ap-southeast-2\\.console\\.aws\\.amazon\\.com` 1. 選擇**建立**。 1. **用戶端 ID** 和**用戶端機密**現在可見。複製並儲存在安全位置。然後，選擇**完成**。 **注意** 「用戶端 ID」和「用戶端機密」字串是在使用 AppFlow 或 AWS Glue時用來建立此連接器連線的憑證。 **擷取 CustomAuth 憑證** 1. 導覽至 [Productboard 登入頁面](https://app.productboard.com/)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 您會被重新導向至首頁。 1. 在首頁中，導覽至**工作區設定** > **整合** > **公有 API** > **存取字符**。 **注意** 如果**公有 API** 區段不可見，您的帳戶可能位於基礎計劃中。存取 API 字符至少需要專業計劃。計劃功能和名稱可能會有所變更。如需有關套件的詳細資訊，請參閱 [Productboard 定價](https://www.productboard.com/pricing/)。 1. 選擇 **＋** 以產生新字符，並確保安全存放以供日後參考。 **建立 `OAuth2.0` 憑證** 若要使用 Productboard 連接器進行 `OAuth2.0` 身分驗證，您需要在 Productboard 平台上註冊應用程式，並產生 `Client ID` 和 `Client Secret`。 1. 導覽至 [Productboard 登入頁面](https://app.productboard.com/)，輸入電子郵件 ID 和密碼，然後選擇**登入**。 1. 若要向 Productboard 帳戶註冊新的 OAuth2 應用程式，請導覽至 [Producboard](to register new OAuth2 application with your Productboard account) 頁面。 1. 完成必要欄位，並針對要存取的每個實體選取必要的範圍。 **注意** 您已選擇下列四個範圍，六個支援的實體需要這些範圍。 1. **重新導向 URL** 必須具有下列格式：`https://ap-southeast-2\\.console\\.aws\\.amazon\\.com` **注意** Appflow 重新導向 URL 可能會有所變更。一旦可用，請更新 AWS Glue 平台URLs。 1. **用戶端 ID** 和**用戶端機密**現在可見。複製並儲存在安全位置。 1. 遵循[如何透過 OAuth2 與 Productboard 整合](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation)開發人員文件中的步驟來設定和驗證 `OAuth2`。 # 限制 以下是 Productboard 連接器的限制： + Productboard 不支援欄位型或記錄型分區。 # 連線至 QuickBooks QuickBooks 是一款針對中小型企業的領先會計應用程式。QuickBooks 會計應用程式可追溯至 20 世紀 80 年代，是 Intuit 的首批產品之一，因此最初是桌面軟體。今天，QuickBooks 提供數個會計和商業金融應用程式作為可安裝的軟體和以雲端為基礎的 SaaS 軟體。身為 QuickBooks 使用者，您可以 AWS Glue 連線至 QuickBooks 帳戶。然後，您可以在 ETL 任務中使用 QuickBooks 作為資料來源。執行這些任務以在 QuickBooks AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 QuickBooks](quickbooks-support.md) + [包含用於建立和使用連線的 API 操作的政策](quickbooks-configuring-iam-permissions.md) + [設定 QuickBooks](quickbooks-configuring.md) + [設定 QuickBooks 連線](quickbooks-configuring-connections.md) + [從 QuickBooks 實體中讀取](quickbooks-reading-from-entities.md) + [QuickBooks 連線選項](quickbooks-connection-options.md) + [QuickBooks 連接器的限制和備註](quickbooks-connector-limitations.md) # AWS Glue 支援 QuickBooks AWS Glue 支援 QuickBooks，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 QuickBooks 查詢資料。 **支援作為目標？** 否。 **支援的 QuickBooks API 版本** 支援以下 QuickBooks API 版本： + v3 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 QuickBooks 您必須先符合下列要求，才能使用 從 QuickBooks AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 QuickBooks 帳戶。 + 您的 QuickBooks 帳戶已啟用 API 存取。 如需詳細資訊，請參閱 QuickBooks 文件中的下列主題： + [建立 Intuit 帳戶](https://quickbooks.intuit.com/learn-support/en-us/help-article/account-management/create-intuit-user-account/L62kSFEOM_US_en_US) + [建立並開始開發您的應用程式](https://developer.intuit.com/app/developer/qbo/docs/get-started/start-developing-your-app) 如果您符合這些要求，就可以 AWS Glue 連線到 QuickBooks 帳戶。對於一般連線，不需要在 QuickBooks 中執行任何其他操作。 # 設定 QuickBooks 連線 QuickBooks 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。授予類型會決定 如何與 QuickBooks AWS Glue 通訊，以請求存取您的資料。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者仍然可以選擇在 QuickBooks 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 QuickBooks 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 QuickBooks 文件，請參閱[設定 OAuth 2.0](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0)。 若要設定 QuickBooks 連線： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 QuickBooks。 1. 提供您要連線之 QuickBooks 執行個體的執行個體 URL 和公司 ID。 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`。 # 從 QuickBooks 實體中讀取 **必要條件** 您要從中讀取的 QuickBooks 物件。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 帳戶 | 是 | 是 | 是 | 是 | 是 | | 帳單 | 是 | 是 | 是 | 是 | 是 | | 公司資訊 | 否 | 否 | 否 | 是 | 否 | | 客戶 | 是 | 是 | 是 | 是 | 是 | | 員工 | 是 | 是 | 是 | 是 | 是 | | 預估 | 是 | 是 | 是 | 是 | 是 | | 發票 | 是 | 是 | 是 | 是 | 是 | | 項目 | 是 | 是 | 是 | 是 | 是 | | 付款 | 是 | 是 | 是 | 是 | 是 | | Preferences (偏好設定) | 否 | 否 | 否 | 是 | 否 | | 損益 | 是 | 否 | 否 | 是 | 否 | | 稅務局 | 是 | 是 | 是 | 是 | 是 | | 廠商 | 是 | 是 | 是 | 是 | 是 | **範例**： ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v3" } ``` **QuickBooks 實體和欄位詳細資訊**： 如需實體和欄位詳細資訊的更多資訊，請參閱： + [帳戶](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account) + [帳單](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/bill) + [公司資訊](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/companyinfo) + [客戶](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/customer) + [員工](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/employee) + [預估](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/estimate) + [發票](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice) + [Item (項目)](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/item) + [付款](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/payment) + [Preferences (偏好設定)](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/preferences) + [損益](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/profitandloss) + [稅務局](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/taxagency) + [廠商](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/vendor) ## 分區查詢 **欄位型分區**： 在 QuickBooks 中，Integer 和 DateTime 資料類型欄位支援欄位型分區。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-05-07T02:03:00.00Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "REALMID": "12345678690123456789", "ENTITY_NAME": "Account", "API_VERSION": "v3", "PARTITION_FIELD": "MetaData_CreateTime" "LOWER_BOUND": "2023-09-07T02:03:00.000Z" "UPPER_BOUND": "2024-05-07T02:03:00.000Z" "NUM_PARTITIONS": "10" } ``` **記錄型分區**： 原始查詢會分區為 Spark 任務可同時執行的子查詢的 `NUM_PARTITIONS` 數目： + `NUM_PARTITIONS`：分區數目。 範例： ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "REALMID": "1234567890123456789", "ENTITY_NAME": "Bill", "API_VERSION": "v3", "NUM_PARTITIONS": "10" } ``` # QuickBooks 連線選項 以下是 QuickBooks 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。QuickBooks 中的物件名稱。 + `INSTANCE_URL`(String) - (必要) 有效的 QuickBooks 執行個體 URL。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 QuickBooks Rest API 版本。 + `REALM_ID`(String) - 一個 ID，其識別您在其中傳送請求的個別 QuickBooks 線上公司。 + `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。用於讀取。要讀取的分區數目。 # QuickBooks 連接器的限制和備註 以下是 QuickBooks 連接器的限制或備註： + 在 `taxAgency` API 中，按篩選排序未按預期運作。 # 連線至 REST API AWS Glue 可讓您設定可用於連線至 AWS Glue 任何 REST API 型資料來源的 AWS Glue ConnectionType。這可以用作 ETL 任務中的資料來源。您可以執行這些任務，在 REST API 型資料來源 AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 REST API](rest-api-support.md) + [政策包含用於註冊連線類型和建立/使用連線的 API 操作](rest-api-configuring-iam-permissions.md) + [設定 REST API ConnectionType](rest-api-configuring.md) + [設定 REST API 連線](rest-api-configuring-connections.md) + [教學課程：建立 REST API ConnectionType 和 Connection](rest-api-example.md) + [限制](rest-api-limitations.md) # AWS Glue 支援 REST API AWS Glue 支援 REST API，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 REST API 型資料來源查詢資料。 **支援作為目標？** 否。 # 政策包含用於註冊連線類型和建立/使用連線的 API 操作 下列範例 IAM 政策說明在 AWS Glue ETL 任務中註冊、建立、管理和使用 REST API 連線所需的許可。如果您要建立新角色，請建立包含下列項目的政策： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:RegisterConnectionType", "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:CreateConnection", "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 主控台的使用者。 如果在建立 REST API 連線時提供網路選項，IAM 角色也必須包含下列動作： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` # 設定 REST API ConnectionType 您必須先符合下列要求，才能使用 從 REST API 型資料來源 AWS Glue 傳輸資料： ## 最低需求 以下是最低需求： + 您已設定並註冊 AWS Glue REST API 連線類型。請參閱[連線至 REST APIs](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html)。 + 如果使用 OAuth2 用戶端登入資料、授權碼或 JWT，請相應地設定用戶端應用程式。 如果您符合這些要求，就可以 AWS Glue 連線到 REST API 型資料來源。一般而言，REST API 端不需要其他組態。 # 設定 REST API 連線 若要設定 AWS Glue REST API 連接器，您需要設定 AWS Glue 連線類型。此連線類型包含 REST 資料來源如何操作和解譯身分驗證、請求、回應、分頁、驗證和實體/中繼資料等事物之屬性的詳細資訊。如需 AWS Glue REST 連線類型所需屬性的完整清單，請參閱 [ RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DescribeConnectionType.html) API 和[連線至 REST APIs](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html) 的步驟。 建立 REST API 連接器時，需要下列政策才能允許相關動作： ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:RegisterConnectionType", "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:CreateConnection", "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` # 教學課程：建立 REST API ConnectionType 和 Connection **連線至 Foo REST API** 我們將為 Foo AWS Glue REST API 建立 REST API ConnectionType 和對應的 AWS Glue 連線。此 API 具有下列屬性 （可從 REST API 文件擷取）。 + **執行個體 URL**：https：//https://foo.cloud.com/rest/v1。 + **身分驗證類型**：OAuth2 （用戶端登入資料）。 + **REST 方法**：GET。 + **分頁類型**：在請求的查詢參數中放置屬性 "limit" 和 "offset" 的位移。 + **支援的實體**： + **長條**：相對路徑 【/bar.json】。 + **Baz**：相對路徑 【/baz.json】。 取得所有詳細資訊後，我們可以開始建立與 Foo REST API 的 AWS Glue 連線。 **若要建立 REST API 連線**： 1. 使用 API、CLI 或 SDK 呼叫 RegisterConnectionType API， AWS Glue 在 中建立 REST AWS API 連線類型。這將在 中建立新的 ConnectionType 資源 AWS Glue。 ``` { "ConnectionType": "REST-FOO-CONNECTOR", "IntegrationType": "REST", "Description": "AWS Glue Connection Type for the FOO REST API", "ConnectionProperties": { "Url": { "Name": "Url", "Required": true, "DefaultValue": "https://foo.cloud.com/rest/v1", "PropertyType": "USER_INPUT" } }, "ConnectorAuthenticationConfiguration": { "AuthenticationTypes": ["OAUTH2"], "OAuth2Properties": { "OAuth2GrantType": "CLIENT_CREDENTIALS" } }, "RestConfiguration": { "GlobalSourceConfiguration": { "RequestMethod": "GET", "ResponseConfiguration": { "ResultPath": "$.result", "ErrorPath": "$.error.message" }, "PaginationConfiguration": { "OffsetConfiguration": { "OffsetParameter": { "Key": "offset", "PropertyLocation": "QUERY_PARAM" }, "LimitParameter": { "Key": "limit", "PropertyLocation": "QUERY_PARAM", "DefaultValue": "50" } } } }, "ValidationEndpointConfiguration": { "RequestMethod": "GET", "RequestPath": "/bar.json?offset=1&limit=10" }, "EntityConfigurations": { "bar": { "SourceConfiguration": { "RequestMethod": "GET", "RequestPath": "/bar.json", "ResponseConfiguration": { "ResultPath": "$.result", "ErrorPath": "$.error.message" } }, "Schema": { "name": { "Name": "name", "FieldDataType": "STRING" }, "description": { "Name": "description", "FieldDataType": "STRING" }, "id": { "Name": "id", "FieldDataType": "STRING" }, "status": { "Name": "status", "FieldDataType": "STRING" } } } } } } ``` 1. 在 AWS Secrets Manager 中建立秘密。秘密應該包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`做為金鑰的已連線應用程式消費者秘密。 **注意** 您必須在 中為每個連線建立秘密 AWS Glue 1. 使用 API、CLI 或 SDK 呼叫 CreateConnection AWS API 來建立 AWS Glue 連線。 1. 參考步驟 1 中的 REST 連線類型名稱做為「ConnectionType」。 1. 提供 InstanceUrl 和在 ConnectionType 註冊程序期間定義的任何其他 ConnectionProperties。 AWS Glue ConnectionType 1. 從設定的身分驗證類型中選擇。REST API Foo 使用 OAuth2 搭配 ClientCredentials 授予類型。 1. 提供已設定的 **SecretArn** 和其他 **AuthenticationProperties**。例如，我們已將 `OAUTH2` 設定為 AuthenticationType，因此我們會在 CreateConnectionInput 中設定「OAuth2Properties」。這將需要屬性，例如「OAuth2GrantType」、「TokenUrl」和「OAuth2ClientApplication」。 1. 提出 CreateConnection 請求以建立 AWS Glue 連線。 ``` { "ConnectionInput": { "Name": "ConnectionFooREST", "ConnectionType": "REST-FOO-CONNECTOR", "ConnectionProperties": {}, "ValidateCredentials": true, "AuthenticationConfiguration": { "AuthenticationType": "OAUTH2", "SecretArn": "arn:aws:secretsmanager:::secret:", "OAuth2Properties": { "OAuth2GrantType": "CLIENT_CREDENTIALS", "TokenUrl": "https://foo.cloud.com/oauth/token", "OAuth2ClientApplication": { "UserManagedClientApplicationClientId": "your-managed-client-id" } } } } } ``` # 限制 以下是 REST API 連接器的限制 + REST API 連接器只能透過 AWS API、CLI 或 SDK 使用。您無法透過主控台設定 REST 連接器。 + AWS Glue REST ConnectionType 只能設定為從 REST API 型資料來源讀取資料。連線只能在 AWS Glue ETL 任務中用作 SOURCE。 + 不支援篩選和分割。 + 不支援欄位選擇。 # 連線至 Salesforce Salesforce 提供客戶關係管理 (CRM) 軟體，可協助您進行銷售、客戶服務、電子商務等。如果您是 Salesforce 使用者，您可以 AWS Glue 連線至您的 Salesforce 帳戶。然後，您可以在 ETL 任務中使用 Salesforce 作為資料來源或目的地。執行這些任務以在 Salesforce AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue Salesforce 的 支援](salesforce-support.md) + [包含用於建立和使用連線的 API 操作的政策](salesforce-configuring-iam-permissions.md) + [設定 Salesforce](salesforce-configuring.md) + [套用系統管理員設定檔](#salesforce-configuring-apply-system-admin-profile) + [設定 Salesforce 連線](salesforce-configuring-connections.md) + [從 Salesforce 中讀取](salesforce-reading-from-entities.md) + [寫入到 Salesforce](salesforce-writing-to.md) + [Salesforce 連線選項](salesforce-connection-options.md) + [Salesforce 連接器的限制](salesforce-connector-limitations.md) + [設定 Salesforce 的授權碼流程](salesforce-setup-authorization-code-flow.md) + [設定 Salesforce 的 JWT Bearer OAuth 流程](salesforce-setup-jwt-bearer-oauth.md) # AWS Glue Salesforce 的 支援 AWS Glue 支援 Salesforce，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Salesforce 查詢資料。 **支援作為目標？** 是。您可以使用 AWS Glue ETL 任務將記錄寫入 Salesforce。 **支援的 Salesforce API 版本** 支援下列 Salesforce API 版本 + v58.0 + v59.0 + v60.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例 IAM 政策說明在 AWS Glue ETL 任務中建立、管理和使用 Salesforce 連線所需的許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "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 主控台的使用者。 如果在建立 Salesforce 連線時提供網路選項，IAM 角色也必須包含下列動作： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 如需了解零 ETL Salesforce 連線，請參閱 [零 ETL 先決條件](https://docs.aws.amazon.com/glue/latest/dg/zero-etl-prerequisites.html)。 如需了解零 ETL Salesforce 連線，請參閱 [零 ETL 先決條件](https://docs.aws.amazon.com/glue/latest/dg/zero-etl-prerequisites.html)。 # 設定 Salesforce 您必須先符合下列要求，才能使用 AWS Glue 往返 Salesforce 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Salesforce 帳戶。 + 您的 Salesforce 帳戶已啟用 API 存取。企業版、無限制版、開發人員版和高效版預設會啟用 API 存取。 如果您符合這些需求，就可以 AWS Glue 連線到您的 Salesforce 帳戶。 會使用 AWS 受管連線應用程式 AWS Glue 來處理剩餘的需求。 ## Salesforce 的 AWS 受管連線應用程式 AWS 受管連線應用程式可協助您在較少的步驟中建立 Salesforce 連線。在 Salesforce 中，連線的應用程式是授權外部應用程式的架構 AWS Glue，例如使用 OAuth 2.0 存取您的 Salesforce 資料。若要使用 AWS 受管連線應用程式，請使用 AWS Glue 主控台建立 Salesforce 連線。當您設定連線時，請將 **OAuth 授予類型**設定為**授權碼**，並勾選**使用 AWS 受管用戶端應用程式的**方塊。 儲存連線時，系統會將您重新導向至 Salesforce，以登入和核准對 Salesforce 帳戶的 AWS Glue 存取。 ## 套用系統管理員設定檔 在 Salesforce 中，依照步驟套用系統管理員設定檔： 1. 在 Salesforce 中，導覽至**設定 > 連線應用程式 > 連線應用程式 OAuth 用途**。 1. 在連線的應用程式清單中，尋找 AWS Glue 並選擇**安裝**。如有需要，請選擇**解除封鎖**。 1. 導覽至**設定 > 管理連線應用程式**，然後選擇 AWS Glue。在 OAuth 政策下，選擇**已預先授權管理員核准的使用者**，然後選取**系統管理員**設定檔。此動作 AWS Glue 限制只有具有系統管理員設定檔的使用者才能存取 。 ## 套用系統管理員設定檔 在 Salesforce 中，依照步驟套用系統管理員設定檔： 1. 在 Salesforce 中，導覽至**設定 > 連線應用程式 > 連線應用程式 OAuth 用途**。 1. 在連線的應用程式清單中，尋找 AWS Glue 並選擇**安裝**。如有需要，請選擇**解除封鎖**。 1. 導覽至**設定 > 管理連線應用程式**，然後選擇 AWS Glue。在 OAuth 政策下，選擇**已預先授權管理員核准的使用者**，然後選取**系統管理員**設定檔。此動作 AWS Glue 限制只有具有系統管理員描述檔的使用者才能存取 。 # 設定 Salesforce 連線 若要設定 Salesforce 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於 JWT\$1TOKEN 授權類型 - 機密應包含具有其值的 JWT\$1TOKEN 金鑰。 1. 對於 AuthorizationCode 授權類型： 1. 對於 AWS 受管連線應用程式，必須提供空白秘密或具有一些暫時值的秘密。 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式 `Consumer Secret`。 1. 注意：必須在 AWS Glue中建立連線機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Salesforce。 1. 提供您要連線之 Salesforce 執行個體的 INSTANCE\$1URL。 1. 提供 Salesforce 環境。 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. 選取要用於連線的 OAuth2 授權類型。授予類型會決定 如何與 Salesforce AWS Glue 通訊，以請求存取您的資料。您的選擇會影響您在建立連線之前必須滿足的要求。可以選擇下列其中一種類型： + **JWT\$1BEARER 授權類型**：此授權類型適用於自動化案例，因為其允許預先建立具有 Salesforce 執行個體中特定使用者許可的 JSON Web Token (JWT)。建立者可以控制 JWT 的有效期。 AWS Glue 能夠使用 JWT 來取得用於呼叫 Salesforce APIs存取字符。 此流程要求使用者已在其 Salesforce 執行個體中建立連線應用程式，以便為使用者簽發 JWT 型存取字符。 如需有關為 JWT Bear OAuth 流程建立連線應用程式的資訊，請參閱[伺服器與伺服器整合的 OAuth 2.0 JWT Bear 流程](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm)。若要使用 Salesforce 連線應用程式設定 JWT Bear 流程，請參閱 [設定 Salesforce 的 JWT Bearer OAuth 流程](salesforce-setup-jwt-bearer-oauth.md)。 + **AUTHORIZATION\$1CODE 授權類型**：此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。根據預設，建立連線的使用者可能需要連線 AWS Glue 的應用程式 (AWS Glue 受管用戶端應用程式），除了其 Salesforce 執行個體 URL 之外，不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Salesforce，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Salesforce 執行個體。 使用者仍然可以選擇在 Salesforce 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Salesforce 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需為授權碼 OAuth 流程建立連線應用程式的資訊，請參閱 [設定 Salesforce 的授權碼流程](salesforce-setup-authorization-code-flow.md)。 1. 選取`secretName`您要用於此連線的 AWS Glue ，以存放 OAuth 2.0 權杖。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 如果提供網路選項，請同時為 IAM 角色授權下列許可： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ ## 使用 CLI 設定 Salesforce AWS 連線 您可以使用 CLI 建立 Salesforce AWS 連線： ``` aws glue create-connection --connection-input \ "{\"Name\": \"salesforce-conn1\",\"ConnectionType\": \"SALESFORCE\",\"ConnectionProperties\": {\"ROLE_ARN\": \"arn:aws:iam::123456789012:role/glue-role\",\"INSTANCE_URL\": \"https://example.my.salesforce.com\"},\"ValidateCredentials\": true,\"AuthenticationConfiguration\": {\"AuthenticationType\": \"OAUTH2\",\"SecretArn\": \"arn:aws:secretsmanager:us-east-1:123456789012:secret:salesforce-conn1-secret-IAmcdk\",\"OAuth2Properties\": {\"OAuth2GrantType\": \"JWT_BEARER\",\"TokenUrl\": \"https://login.salesforce.com/services/oauth2/token\"}}}" \ --endpoint-url https://glue.us-east-1.amazonaws.com \ --region us-east-1 ``` # 從 Salesforce 中讀取 **必要條件** 您想要從中讀取的 Salesforce Object。將需要物件名稱，例如 `Account` 或 `Case` 或 `Opportunity`。 **範例**： ``` salesforce_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforce", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v60.0" } ) ``` ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於「日期」或「時間戳記」欄位，連接器接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "TIMESTAMP \"1707256978123\"" "TIMESTAMP '2018-01-01 00:00:00.000 UTC'" "TIMESTAMP \"2018-01-01 00:00:00 Pacific/Tahiti\"" "TIMESTAMP \"2018-01-01 00:00:00\"" "TIMESTAMP \"-123456789\" Pacific/Tahiti" "TIMESTAMP \"1702600882\"" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 + `TRANSFER_MODE`：支援兩種模式：`SYNC` 和 `ASYNC`。預設值為 `SYNC`。設為 `ASYNC` 時，將使用 Bulk API 2.0 查詢來處理。 範例： ``` salesforce_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforce", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v60.0", "PARTITION_FIELD": "SystemModstamp", "LOWER_BOUND": "TIMESTAMP '2021-01-01 00:00:00 Pacific/Tahiti'", "UPPER_BOUND": "TIMESTAMP '2023-01-10 00:00:00 Pacific/Tahiti'", "NUM_PARTITIONS": "10", "TRANSFER_MODE": "ASYNC" } ) ``` ## FILTER\$1PREDICATE 選項 **FILTER\$1PREDICATE**：其是可選參數。此選項用於查詢篩選條件。 **FILTER\$1PREDICATE** 的範例： ``` Case 1: FILTER_PREDICATE with single criterion Examples: LastModifiedDate >= TIMESTAMP '2025-04-01 00:00:00 Pacific/Tahiti' LastModifiedDate <= TIMESTAMP "2025-04-01 00:00:00" LastModifiedDate >= TIMESTAMP '2018-01-01 00:00:00.000 UTC' LastModifiedDate <= TIMESTAMP "-123456789 Pacific/Tahiti" LastModifiedDate <= TIMESTAMP "1702600882" Case 2: FILTER_PREDICATE with multiple criteria Examples: LastModifiedDate >= TIMESTAMP '2025-04-01 00:00:00 Pacific/Tahiti' AND Id = "0012w00001CotGiAAJ" LastModifiedDate >= TIMESTAMP "1702600882" AND Id = "001gL000002i26MQAQ" Case 3: FILTER_PREDICATE single criterion with LIMIT Examples: LastModifiedDate >= TIMESTAMP "1702600882" LIMIT 2 Case 4: FILTER_PREDICATE with LIMIT Examples: LIMIT 2 ``` # 寫入到 Salesforce **先決條件** 您想要寫入到的 Salesforce sObject。將需要物件名稱，例如 `Account` 或 `Case` 或 `Opportunity`。 Salesforce 連接器支援四種寫入操作： + INSERT + UPSERT (更新插入) + UPDATE + DELETE 使用 `UPSERT` 寫入操作時，必須提供 `ID_FIELD_NAMES` 選項來指定記錄的外部 ID 欄位。 也可以新增連線選項： + `TRANSFER_MODE`：支援兩種模式：`SYNC` 和 `ASYNC`。預設值為 `SYNC`。設為 `ASYNC` 時，將使用 Bulk API 2.0 Ingest 來處理。 + `FAIL_ON_FIRST_ERROR`：預設值為 `FALSE`，這表示即使有一些寫入記錄失敗， AWS Glue 任務仍會繼續處理所有資料。設為 時`TRUE`，如果有任何失敗的寫入記錄， AWS Glue 任務將會失敗，而且不會繼續處理。 **範例** ``` salesforce_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="salesforce", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v60.0", "WRITE_OPERATION": "INSERT", "TRANSFER_MODE": "ASYNC", "FAIL_ON_FIRST_ERROR": "true" } ) ``` # Salesforce 連線選項 Salesforce 連接器支援下列連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Salesforce 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Salesforce Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 提供篩選條件述詞時，僅支援 `AND` 運算子。目前不支援其他運算子，例如 `OR` 和 `IN`。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 + `IMPORT_DELETED_RECORDS`(String) - 預設：FALSE。用於讀取。在查詢時取得刪除記錄。 + `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT、UPDATE、UPSERT、DELETE。 + `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 和 UPSERT 的必要項目。 # Salesforce 連接器的限制 以下是 Salesforce 連接器的限制： + 我們僅支援 Spark SQL，不支援 Salesforce SOQL。 + 不支援任務書籤。 + Salesforce 欄位名稱皆會區分大小寫。寫入到 Salesforce 時，資料必須符合 Salesforce 中定義的欄位大小寫。 # 設定 Salesforce 的授權碼流程 請參閱 Salesforce 公有文件，以啟用 OAuth 2.0 授權碼流程。 若要設定連線的應用程式： 1. 啟動**啟用 OAuth 設定**核取方塊。 1. 在**回呼 URL** 文字欄位中，輸入 AWS Glue的一個或多個重新導向 URL。 重新導向 URL 的格式如下： https://*region*.console.aws.amazon.com/gluestudio/oauth 在此 URL 中，*region* 是您 AWS Glue 用來從 Salesforce 傳輸資料的 AWS 區域的程式碼。例如，美國東部 (維吉尼亞北部) 區域的代碼為 `us-east-1`。對於該區域，URL 如下： https://us-east-1.console.aws.amazon.com/gluestudio/oauth 如需 AWS Glue 支援 AWS 的區域及其代碼，請參閱《 *AWS 一般參考*》中的[AWS Glue 端點和配額](https://docs.aws.amazon.com/general/latest/gr/glue.html)。 1. 啟動**需要 Web 伺服器流程機密**核取方塊。 1. 在**可用的 OAuth 範圍**清單中，新增下列範圍： + 透過 API 管理使用者資料 (api) + 存取自訂許可 (custom\$1permissions) + 存取身分 URL 服務 (id、設定檔、電子郵件、地址、電話) + 存取唯一使用者識別符 (openid) + 隨時執行請求 (refresh\$1token, offline\$1access) 1. 將連線應用程式的重新整理字符政策設定為**重新整理字符在撤銷之前有效**。否則，當重新整理字符過期時，任務會失敗。如需有關如何檢查和編輯重新整理字符政策的詳細資訊，請參閱 Salesforce 文件中的[管理連線應用程式的 OAuth 存取政策](https://help.salesforce.com/articleView?id=connected_app_manage_oauth.htm)。 # 設定 Salesforce 的 JWT Bearer OAuth 流程 請參閱 Salesforce 公有文件，了解 [OAuth 2.0 JSON Web 字符](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm)的伺服器到伺服器整合。 在 Salesforce 中建立 JWT 並適當設定連線應用程式後，您可以使用 Secrets Manager Secret 中設定的 `JWT_TOKEN` 金鑰來建立新的 Salesforce 連線。建立連線時，將 OAuth 授權類型設定為 **JWT Bearer 字符**。 # 連線至 Salesforce Marketing Cloud Salesforce Marketing Cloud 是一家為電子郵件、行動裝置、社交和線上行銷提供行銷自動化和分析軟體的供應商。其還提供諮詢和實作服務。身為 Salesforce Marketing Cloud 使用者，您可以 AWS Glue 連線至 Salesforce Marketing Cloud 帳戶。然後，您可以在 ETL 任務中使用 Salesforce Marketing Cloud 作為資料來源或目的地。執行這些任務，以在 Salesforce Marketing Cloud AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Salesforce Marketing Cloud](salesforce-marketing-cloud-support.md) + [包含用於建立和使用連線的 API 操作的政策](salesforce-marketing-cloud-configuring-iam-permissions.md) + [設定 Salesforce Marketing Cloud](salesforce-marketing-cloud-configuring.md) + [設定 Salesforce Marketing Cloud 連線](salesforce-marketing-cloud-configuring-connections.md) + [從 Salesforce Marketing Cloud 實體中讀取](salesforce-marketing-cloud-reading-from-entities.md) + [寫入到 Salesforce Marketing Cloud 實體](salesforce-marketing-cloud-writing-to-entities.md) + [Salesforce Marketing Cloud 連線選項](salesforce-marketing-cloud-connection-options.md) + [Salesforce Marketing Cloud 連接器的限制和備註](salesforce-marketing-cloud-connector-limitations.md) # AWS Glue 支援 Salesforce Marketing Cloud AWS Glue 支援 Salesforce Marketing Cloud，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Salesforce Marketing Cloud 查詢資料。 **支援作為目標？** 否。 **支援的 Salesforce Marketing Cloud API 版本** 支援下列 Salesforce Marketing Cloud 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 主控台的使用者。 # 設定 Salesforce Marketing Cloud 您必須先符合下列要求，才能使用 從 Salesforce Marketing Cloud AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Salesforce Marketing Cloud 帳戶。如需詳細資訊，請參閱[建立 Salesforce Marketing Cloud 帳戶](#salesforce-marketing-cloud-configuring-creating-salesforce-marketing-cloud-account)。 + 您的 Salesforce Marketing Cloud 帳戶已啟用 API 存取。企業版、無限制版、開發人員版和高效版預設會啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到 Salesforce Marketing Cloud 帳戶。對於一般連線，您不需要在 Salesforce Marketing Cloud 中執行任何其他操作。 ## 建立 Salesforce Marketing Cloud 帳戶 對於 Salesforce Marketing Cloud，您需要聯絡廠商以建立帳戶。如果您或您的公司與 Salesforce 有關聯，請聯絡 Salesforce 客戶經理來請求 Salesforce Marketing Cloud 授權。或者，可以請求聯絡 Salesforce 代表，如下所示： 1. 前往 https://www.salesforce.com/in/products/marketing-cloud/overview/ 並選擇**註冊**。 1. 選取頁面右上角的**聯絡我們**連結。 1. 在表單中輸入必要資訊，然後選擇**聯絡方式**。 Salesforce 代表將與您聯絡，討論您的需求。 ## 建立專案和 OAuth 2.0 憑證 若要取得專案和 OAuth 2.0 憑證： 1. 使用您的使用者名稱和密碼登入 [Salesforce Marketing Cloud 執行個體](https://mc.login.exacttarget.com/hub-cas/login)，並使用您註冊的手機號碼進行驗證。 1. 按一下右上角的設定檔，然後前往**設定**。 1. 在**平台工具**下，選擇**應用程式**，然後選擇**已安裝的套件**。 ![\[\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/sfmc-platform-tools.png) 1. 在**已安裝的套件**頁面中，按一下右上角的**新增**。提供套件的名稱和說明。 儲存套件。儲存套件之後，可以檢視套件詳細資訊。 1. 在套件的**詳細資訊**頁面的**元件**區段下，選擇**新增元件**。 ![\[\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/sfmc-add-component.png) 1. 將**元件類型**選取為「API 整合」，然後按一下**下一步**。 1. 將**整合類型**選取為「伺服器到伺服器」(具有用戶端憑證 OAuth 授權類型)，然後按一下**下一步**。 1. 根據您的需求新增範圍，然後按一下**儲存**。 # 設定 Salesforce Marketing Cloud 連線 Salesforce Marketing Cloud 支援 OAuth2 的 CLIENT CREDENTIALS 授權類型。 + 此授予類型被視為 2 邊 OAuth 2.0，因為用戶端使用它來取得使用者內容外的存取權杖。 AWS Glue 能夠使用用戶端 ID 和用戶端秘密來驗證您定義的自訂服務提供的 Salesforce Marketing Cloud APIs。 + 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。 + 此授權類型會產生短期存留的存取字符，且可以透過呼叫身分端點來續約。 + 如需具有用戶端憑證的 OAuth 2.0 的公有 Salesforce Marketing Cloud 文件，請參閱[設定增強型套件的開發環境](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/mc-dev-setup-enhanced.html)。 若要設定 Salesforce Marketing Cloud 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須在 中建立連線的秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Salesforce Marketing Cloud。 1. 提供您要連線的 Salesforce Marketing Cloud 的 `Subdomain Endpoint`。 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`。 # 從 Salesforce Marketing Cloud 實體中讀取 **必要條件** 您想要從中讀取的 Salesforce Marketing Cloud 物件。您將需要物件名稱，例如 `Activity` 或 `Campaigns`。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 介面 | 可以篩選 | 支援限制 | 支援排序依據 | 支援 SELECT \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | 事件通知回呼 | REST | 否 | 否 | 否 | 是 | 否 | | Seed-List | REST | 否 | 是 | 否 | 是 | 否 | | 設定 | REST | 是 | 是 | 否 | 是 | 否 | | 網域驗證 | REST | 是 | 是 | 是 | 是 | 否 | | 物件巢狀標籤 | REST | 是 | 否 | 否 | 是 | 否 | | 聯絡 | REST | 否 | 是 | 否 | 是 | 否 | | 事件通知訂閱 | REST | 否 | 否 | 否 | 是 | 否 | | 簡訊 | REST | 否 | 是 | 否 | 是 | 否 | | 活動 | SOAP | 否 | 否 | 否 | 是 | 是 | | Bounce Event | SOAP | 否 | 否 | 否 | 是 | 是 | | Click Event | SOAP | 否 | 否 | 否 | 是 | 是 | | Content Area | SOAP | 否 | 否 | 否 | 是 | 是 | | Data Extension | SOAP | 否 | 是 | 否 | 是 | 是 | | Email | SOAP | 否 | 是 | 否 | 是 | 是 | | Forwarded Email Event | SOAP | 否 | 是 | 否 | 是 | 是 | | Forward Email OptInEvent | SOAP | 否 | 是 | 否 | 是 | 是 | | 連結 | SOAP | 否 | 是 | 否 | 是 | 是 | | Link Send | SOAP | 否 | 是 | 否 | 是 | 是 | | 清單 | SOAP | 否 | 是 | 否 | 是 | 是 | | List Subscriber | SOAP | 否 | 是 | 否 | 是 | 是 | | Not Sent Event | SOAP | 否 | 是 | 否 | 是 | 是 | | Open Event | SOAP | 否 | 是 | 否 | 是 | 是 | | 傳送 | SOAP | 否 | 是 | 否 | 是 | 是 | | Sent Event | SOAP | 否 | 是 | 否 | 是 | 是 | | Subscriber | SOAP | 否 | 是 | 否 | 是 | 是 | | Survey Event | SOAP | 否 | 是 | 否 | 是 | 是 | | Unsub Event | SOAP | 否 | 是 | 否 | 是 | 是 | | 稽核事件 | REST | 否 | 是 | 是 | 是 | 否 | | 行銷活動 | REST | 否 | 是 | 是 | 是 | 否 | | 互動 | REST | 否 | 是 | 是 | 是 | 否 | | 內容資產 | REST | 否 | 是 | 是 | 是 | 否 | **REST 的範例**： ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **SOAP 的範例**： ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Activity", "API_VERSION": "v1", "INSTANCE_URL": "https://**********************.soap.marketingcloudapis.com" } ) ``` **Salesforce Marketing Cloud 實體和欄位詳細資訊**： 下表說明 Salesforce Marketing Cloud 實體。存在具有靜態中繼資料的 REST 實體和具有動態中繼資料的 SOAP 實體。 **具有靜態中繼資料的 REST 實體**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html) **具有動態中繼資料的 SOAP 實體**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html) ## 分區查詢 在 Salesforce Marketing Cloud 中，Integer 和 DateTime 資料類型欄位支援欄位型分區。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於時間戳記欄位，接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` “2024-05-07T02:03:00.00Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "ListSubscriber", "API_VERSION": "v1", "PARTITION_FIELD": "CreatedDate", "LOWER_BOUND": "2023-09-07T02:03:00.000Z", "UPPER_BOUND": "2024-05-07T02:03:00.000Z", "NUM_PARTITIONS": "10" } ) ``` # 寫入到 Salesforce Marketing Cloud 實體 **先決條件** + 您想要寫入到的 Salesforce Marketing 物件。需要指定物件的名稱，例如 `List`、`Campaigns` 或下表中列出的任何其他實體。 + Salesforce Marketing Cloud 連接器支援三種寫入操作： + INSERT + UPSERT (更新插入) + UPDATE 使用 `UPDATE` 和 `UPSERT` 寫入操作時，必須提供 `ID_FIELD_NAMES` 選項，以指定記錄的外部 ID 欄位。 **目的地支援的實體**： | 實體 | Priority | 介面 (REST、SOAP 等） | 可以插入 | 可以更新 | 可以更新插入 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | P0 | REST | Y- 單一 | Y- 單一 | N | | 內容資產 | P0 | REST | Y- 單一、大量 | Y- 單一 | N | | 聯絡 | P1 | REST | Y- 單一 | Y- 單一 | N | | 網域驗證 | P1 | REST | Y- 單一 | Y- 單一、大量 | N | | 事件通知回呼 | P1 | REST | Y- 單一 | Y- 單一 | N | | 事件通知訂閱 | P1 | REST | Y- 單一 | Y- 單一 | N | | 簡訊 | P1 | REST | Y- 單一 | N | N | | 物件巢狀標籤 | P2 | REST | Y- 單一 | Y- 單一 | N | | Seed-List | P1 | REST | Y- 單一 | Y- 單一 | N | | 設定 | P1 | REST | Y- 單一 | Y- 單一 | N | | Data Extension | P0 | SOAP | Y- 單一 | Y- 單一 | Y- 單一 | | Email | P0 | SOAP | Y- 單一 | Y- 單一 | N | | 清單 | P0 | SOAP | Y- 單一 | Y- 單一 | N | | 傳送 | P0 | SOAP | Y- 單一 | N | N | | Subscriber | P0 | SOAP | Y- 單一 | Y- 單一 | N | **REST 的 INSERT 操作範例**： ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "writeOperation" : "INSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **SOAP 的 INSERT 操作範例**： ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "List", "API_VERSION": "v1", "writeOperation" : "INSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **REST 的 UPDATE 操作範例**： ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "writeOperation" : "UPDATE", "ID_FIELD_NAMES": "id", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **SOAP 的 UPDATE 操作範例**： ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "List", "API_VERSION": "v1", "writeOperation" : "UPDATE", "ID_FIELD_NAMES": "id", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **SOAP 的 UPSERT 操作範例**： ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "DataExtension/Insert-***E/6*******3", "API_VERSION": "v1", "writeOperation" : "UPSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` # Salesforce Marketing Cloud 連線選項 以下是 Salesforce Marketing Cloud 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Salesforce Marketing Cloud 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Salesforce Marketing Cloud Rest 和 SOAP 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。用於讀取。要讀取的分區數目。 + `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT、UPDATE、UPSERT。 + `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 和 UPSERT 是必要項目。 # Salesforce Marketing Cloud 連接器的限制和備註 以下是 Salesforce Marketing Cloud 連接器的限制或備註： + 在 DateTime 資料類型欄位中使用篩選條件時，需要傳遞格式為 "yyyy-mm-ddThh：MM：ssZ" 的值。 + 在「資料預覽」中，「布林資料類型」值為空白。 + 對於 SOAP 實體，最多可以定義兩個篩選條件，對於 REST 實體，只能定義一個篩選條件，這會限制使用篩選條件測試分區。 + 從 SaaS 端觀察到多種非預期行為：`linksend` 實體中的 `Link.Alias` 欄位不支援 CONTAINS 運算子 (例如 `Link.Alias CONTAINS "ViewPrivacyPolicy"`)，且資料延伸實體 (例如 EQUALS 和 GREATER THAN) 的篩選運算子不會傳回預期結果。 + SFMC ClickEvent SOAP API 在反映新建立的記錄方面存在延遲，因此最近建立的記錄可能無法立即在 API 回應中使用。 範例：如果您於 **2025-01-10T14:30:00** 建立了 5 筆新的 ClickEvent 記錄，並立即使用 SOAP API 對其進行擷取，則回應可能不會包含所有 5 筆記錄。新建立的記錄最多可能需要 5 分鐘才會出現在 API 回應中。此延遲也會影響資料擷取和排程執行。 + 執行寫入操作時，支援兩種不同的 DateTime 格式：**2025-03-11T04：46：00** （不含毫秒） 和 **2025-03-11T04：46：00.000Z** AWS Glue （含毫秒）。 + 對於事件通知訂閱實體，只能為已驗證的回呼 URL 建立訂閱，而且每個回呼最多可有 200 個訂閱。 + 對於事件通知回呼實體，每個帳戶最多可建立 50 筆記錄。 # 連線至 Salesforce Commerce Cloud B2C Commerce API 是一組用於與 B2C Commerce 執行個體互動的 RESTful API 集合。其包含幾個不同的名稱：Salesforce Commerce API、縮寫 SCAPI，或只是 Commerce API。 API 可讓開發人員建置各種應用程式：從完整店面到自訂商家工具，再到增強 Business Manager。對於所有 B2C Commerce 客戶，均可免費使用該 API。 API 分為兩個主要的 API 群組：Shopper API 和 Admin API。在每個群組內，其分為 API 系列和專注於相關功能的小型群組。 **Topics** + [AWS Glue 支援 Salesforce Commerce Cloud](salesforce-commerce-cloud-support.md) + [包含用於建立和使用連線的 API 操作的政策](salesforce-commerce-cloud-configuring-iam-permissions.md) + [設定 Salesforce Commerce Cloud](salesforce-commerce-cloud-configuring.md) + [設定 Salesforce Commerce Cloud 連線](salesforce-commerce-cloud-configuring-connections.md) + [從 Salesforce Commerce Cloud 實體中讀取](salesforce-commerce-cloud-reading-from-entities.md) + [Salesforce Commerce Cloud 連線選項參考](salesforce-commerce-cloud-connection-options.md) + [限制](salesforce-commerce-cloud-connector-limitations.md) # AWS Glue 支援 Salesforce Commerce Cloud AWS Glue 支援 Salesforce Commerce Cloud，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Salesforce Commerce Cloud 查詢資料。 **支援作為目標？** 否。 **支援的 Salesforce Commerce Cloud API 版本** v1。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Salesforce Commerce Cloud 您必須先符合下列要求，才能使用 從 Salesforce Commerce Cloud AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個具有 clientId 和 clientSecret 的 Salesforce Commerce Cloud 用戶端應用程式。 + 您的 Salesforce Commerce Cloud 帳戶已啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到 Salesforce Commerce Cloud 帳戶。對於一般連線，您不需要在 Salesforce Commerce Cloud 中執行任何其他操作。 # 設定 Salesforce Commerce Cloud 連線 Salesforce Commerce Cloud 支援 OAuth2 的 CLIENT CREDENTIALS 授權類型。 + 此授權類型被視為雙腿 OAuth 2.0，因為用戶端使用其來取得使用者內容外的存取字符。 AWS Glue 能夠使用用戶端 ID 和用戶端機密來驗證您定義的自訂服務所提供的 Salesforce Commerce Cloud API。 + 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。 + 此授權類型會產生短期存留的存取字符，且可以透過呼叫身分端點來續約。 + 如需有關產生用戶端憑證之 Salesforce Commerce Cloud 文件的詳細資訊，請參閱 [Salesforce 文件](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html)。 若要設定 Salesforce Commerce Cloud 連線： 1. 在 中 AWS Secrets Manager，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於客戶管理的連線應用程式，機密應包含以 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作為金鑰的連線應用程式消費者機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections** 下建立連線： 1. 在「資料連線」下，選擇**建立連線**。 1. 選取**資料來源**時，請選取 Salesforce Commerce Cloud。 1. 提供 Salesforce Commerce Cloud 的**簡短代碼**、**組織 ID** 和**網站 ID**。 1. 選取 Salesforce Commerce Cloud 帳戶的 Salesforce Commerce Cloud 網域 URL。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 提供您要連線之 Salesforce Commerce Cloud 的 OAuth 範圍 (選用) 以及使用者管理的用戶端應用程式 ClientId。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Salesforce Commerce Cloud 實體中讀取 **先決條件** + 您想要從中讀取的 Salesforce Commerce Cloud Object。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 指派 | 是 | 是 | 是 | 是 | 是 | | 行銷活動 | 是 | 是 | 是 | 是 | 是 | | 目錄 | 是 | 是 | 是 | 是 | 是 | | 類別 | 是 | 是 | 是 | 是 | 是 | | 優惠券 | 是 | 是 | 是 | 是 | 是 | | 禮品券 | 是 | 是 | 是 | 是 | 是 | | 產品 | 是 | 是 | 是 | 是 | 是 | | 促銷活動 | 是 | 是 | 是 | 是 | 是 | | 來源碼群組 | 是 | 是 | 是 | 是 | 是 | **範例** ``` salesforce_commerce_cloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign", "API_VERSION": "v1" } ) ``` **Salesforce Commerce Cloud 實體和欄位詳細資訊** 實體清單： + 指派：[https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + 行銷活動：[https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + 目錄：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + 類別：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + 禮品券：[https：//https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + 產品：[https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + 促銷活動：[https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + 原始程式碼群組：[https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups](https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups) **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： | 實體 | 分區欄位 | DataType | | --- | --- | --- | | 行銷活動 | lastModified | DateTime | | 行銷活動 | startDate | DateTime | | 行銷活動 | endDate | DateTime | | 目錄 | creationDate | DateTime | | 類別 | creatiionDate | DateTime | | 禮品券 | merchantId | String | | 禮品券 | creatiionDate | DateTime | | 產品 | creatiionDate | DateTime | | 產品 | lastModified | DateTime | | 來源碼群組 | creationDate | DateTime | | 來源碼群組 | startTime | DateTime | | 來源碼群組 | endTime | DateTime | **範例** ``` salesforceCommerceCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "creationDate", "LOWER_BOUND": "2020-05-01T20:55:02.000Z", "UPPER_BOUND": "2024-07-11T20:55:02.000Z", "NUM_PARTITIONS": "10" } ) ``` # Salesforce Commerce Cloud 連線選項參考 以下是 Salesforce Commerce Cloud 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Salesforce Commerce Cloud 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Salesforce Commerce Cloud Rest API 版本。範例：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。用於讀取。要讀取的分區數目。 # 限制 以下是 Salesforce Commerce Cloud 連接器的限制： + 分區時，Contains 篩選條件未如預期運作。 + CDN Zones 的實體不支援沙盒執行個體，其僅支援開發和生產執行個體類型。如需詳細資訊，請參閱 [https://help.salesforce.com/s/articleView?id=cc.b2c\$1embedded\$1cdn\$1overview.htm](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn_overview.htm)。 + 在 Salesforce Commerce Cloud 中，沒有可擷取動態中繼資料的 API 端點。因此，沒有佈建可支援「產品」和「類別」實體中的自訂欄位。 + 網站 ID 是強制性查詢參數。必須透過「自訂連接器設定」傳遞網站 ID 值。如需詳細資訊，請參閱[基本 URL 和請求形成要素](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)。 + 可以在單一 API 請求中使用不同運算子的組合對最多兩個欄位套用篩選條件 (不含「層級」，如果有的話)，如下表所述： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + 在某些實體中，擷取時欄位的資料類型與用作可搜尋欄位時不同。因此，這些欄位沒有佈建篩選功能。下表提供有關這些欄位的詳細資訊。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) # 連線至 Salesforce Marketing Cloud Account Engagement Salesforce Marketing Cloud Account Engagement 是一種行銷自動化解決方案，可協助公司建立有意義的連線、產生更多管道，並增強銷售能力以達成更多交易。如果您是 Salesforce Marketing Cloud Account Engagement 使用者，您可以 AWS Glue 連線至 Salesforce Marketing Cloud Account Engagement 帳戶。您可以使用 Salesforce Marketing Cloud Account Engagement 作為 ETL 任務中的資料來源。執行這些任務，將資料從 Salesforce Marketing Cloud 帳戶參與傳輸到 AWS 服務或其他支援的應用程式。 **Topics** + [AWS Glue 支援 Salesforce Marketing Cloud 帳戶參與](salesforce-marketing-cloud-account-engagement-support.md) + [包含用於建立和使用連線的 API 操作的政策](salesforce-marketing-cloud-account-engagement-configuring-iam-permissions.md) + [設定 Salesforce Marketing Cloud Account Engagement](salesforce-marketing-cloud-account-engagement-configuring.md) + [設定 Salesforce Marketing Cloud Account Engagement 連線](salesforce-marketing-cloud-account-engagement-configuring-connections.md) + [從 Salesforce Marketing Cloud Account Engagement 實體讀取](salesforce-marketing-cloud-account-engagement-reading-from-entities.md) + [Salesforce Marketing Cloud Account Engagement 連線選項](salesforce-marketing-cloud-account-engagement-connection-options.md) + [Salesforce Marketing Cloud Account Engagement 連接器的限制和備註](salesforce-marketing-cloud-account-engagement-connector-limitations.md) # AWS Glue 支援 Salesforce Marketing Cloud 帳戶參與 AWS Glue 支援 Salesforce Marketing Cloud 帳戶參與，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務，以非同步或同步模式從 Salesforce Marketing Cloud 帳戶參與中查詢資料。 **支援作為目標？** 否。 **支援的 Salesforce Marketing Cloud Account Engagement API 版本** 支援下列 Salesforce Marketing Cloud Account Engagement API 版本： + v5 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Salesforce Marketing Cloud Account Engagement 您必須先符合下列要求，才能使用 從 Salesforce Marketing Cloud Account Engagement AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Salesforce 行銷帳戶。 + 您擁有 Salesforce 帳戶的授權 Account Engagement 計劃。 + 您已將 Salesforce 使用者與 Account Engagement 使用者同步。 + 您已在 App Manager 下建立新的連線應用程式，以取得 OAuth 憑證。 如果您符合這些要求，就可以 AWS Glue 連線到 Salesforce Marketing Cloud 帳戶參與帳戶。 # 設定 Salesforce Marketing Cloud Account Engagement 連線 授予類型決定 如何與 Salesforce Marketing Cloud Account Engagement AWS Glue 通訊，以請求存取您的資料。您的選擇會影響您在建立連線之前必須滿足的要求。Salesforce Marketing Cloud Account Engagement 僅支援 OAuth 2.0 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者仍然可以選擇在 Salesforce Marketing Cloud Account Engagement 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，他們仍會重新導向至 Salesforce Marketing Cloud 帳戶參與，以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需建立授權碼 OAuth 流程連線應用程式的公有 Salesforce Marketing Cloud Account Engagement 文件，請參閱[身分驗證](https://developer.salesforce.com/docs/marketing/pardot/guide/version5overview.html#authentication)。 若要設定 Salesforce Marketing Cloud Account Engagement 連線： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Salesforce Marketing Cloud Account Engagement。 1. 提供您要連線之 Salesforce Marketing Cloud Account Engagement 執行個體的 `INSTANCE_URL`。 1. 提供您要連線之 Salesforce Marketing Cloud Account Engagement 執行個體的 `PARDOT_BUSINESS_UNIT_ID`。 1. 從下拉式清單中選取適當的**授權碼 URL**。 1. 從下拉式清單中選取適當的**字符 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. 提供使用者管理的用戶端應用程式用戶端 ID (連線應用程式的用戶端 ID)。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。選取的機密需要具有值為連線應用程式中用戶端機密的金鑰 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Salesforce Marketing Cloud Account Engagement 實體讀取 **必要條件** 您想要從中讀取的 Salesforce Marketing Cloud Account Engagement 物件。將需要物件名稱。 **同步來源支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | 是 | 是 | 是 | 是 | 是 | | 動態內容 | 是 | 是 | 是 | 是 | 是 | | Email | 是 | 是 | 是 | 是 | 是 | | 電子郵件範本 | 是 | 是 | 是 | 是 | 是 | | Engagement Studio 計畫 | 是 | 是 | 是 | 是 | 是 | | 資料夾內容 | 是 | 是 | 是 | 是 | 是 | | 登陸頁面 | 是 | 是 | 是 | 是 | 是 | | 生命週期歷史記錄 | 是 | 是 | 是 | 是 | 是 | | 生命週期狀態 | 是 | 是 | 是 | 是 | 是 | | 清單 | 是 | 是 | 是 | 是 | 是 | | 列出電子郵件 | 是 | 是 | 是 | 是 | 是 | | 列出成員資格 | 是 | 是 | 是 | 是 | 是 | | 機會 | 是 | 是 | 是 | 是 | 是 | | 潛在客戶 | 是 | 是 | 是 | 是 | 是 | | 潛在客戶帳戶 | 是 | 是 | 是 | 是 | 是 | | 使用者 | 是 | 是 | 是 | 是 | 是 | **範例**： ``` salesforcepardot_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforcePardot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v5" } ) ``` **非同步來源支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | 是 | 否 | 否 | 是 | 否 | | 動態內容 | 是 | 否 | 否 | 是 | 否 | | 電子郵件範本 | 是 | 否 | 否 | 是 | 否 | | 登陸頁面 | 是 | 否 | 否 | 是 | 否 | | 生命週期歷史記錄 | 是 | 否 | 否 | 是 | 否 | | 生命週期狀態 | 是 | 否 | 否 | 是 | 否 | | 清單 | 是 | 否 | 否 | 是 | 否 | | 列出電子郵件 | 是 | 否 | 否 | 是 | 否 | | 列出成員資格 | 是 | 否 | 否 | 是 | 否 | | 機會 | 是 | 否 | 否 | 是 | 否 | | 潛在客戶 | 是 | 否 | 否 | 是 | 否 | | 潛在客戶帳戶 | 是 | 否 | 否 | 是 | 否 | | 使用者 | 是 | 否 | 否 | 是 | 否 | **範例**： ``` salesforcepardot_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforcePardot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v5", "TRANSFER_MODE": "ASYNC" } ) ``` **Salesforce Marketing Cloud Account Engagement 實體和欄位詳細資訊**： 若要檢視下列實體的欄位詳細資訊，請導覽至 [Salesforce Marketing Cloud Account Engagement API](https://developer.salesforce.com/docs/marketing/pardot)，選擇**指南**，向下捲動至**開放原始碼 API 包裝函式**，從功能表中展開**第 5 版文件**，然後選擇實體。 實體清單： + 行銷活動 + 動態內容 + Email + 電子郵件範本 + Engagement Studio 計畫 + 資料夾內容 + 登陸頁面 + 生命週期歷史記錄 + 生命週期狀態 + 清單 + 列出電子郵件 + 列出成員資格 + 機會 + 潛在客戶 + 潛在客戶帳戶 + 使用者 除了上述欄位之外，非同步模式還支援每個實體的特定可篩選欄位，如下表所示。 | 實體 | 非同步模式中支援的其他可篩選欄位 | | --- | --- | | 行銷活動 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 動態內容 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 電子郵件範本 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | Engagement Studio 計畫 | - | | 登陸頁面 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 生命週期歷史記錄 | createdAfter, createdBefore | | 生命週期狀態 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 清單 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 列出電子郵件 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 列出成員資格 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 機會 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 潛在客戶 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | | 潛在客戶帳戶 | createdAfter, createdBefore, deleted | | 使用者 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore | 如需其他欄位的詳細資訊，請參閱 [Salesforce Export API](https://developer.salesforce.com/docs/marketing/pardot/guide/export-v5.html#procedures) 請注意連接器的下列考量： + 實體中的 `delete` 欄位值可以為 `false` (預設)、`true` 或 `all`。 ## 分區查詢 **基於篩選條件的分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2022-01-01T01:01:01.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 + `PARTITION_BY`：要執行的分區類型。如果為欄位型分區，則會傳遞 "FIELD"。 範例： ``` salesforcepardot_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcepardot", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v5", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2022-01-01T01:01:01.000Z" "UPPER_BOUND": "2024-01-01T01:01:01.000Z" "NUM_PARTITIONS": "10", "PARTITION_BY": "FIELD" } ) ``` # Salesforce Marketing Cloud Account Engagement 連線選項 以下是 Salesforce Marketing Cloud Account Engagement 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Salesforce Marketing Cloud Account Engagement 中的物件名稱。 + `PARDOT_BUSINESS_UNIT_ID` - (必要) 用於建立連線。您要連線之 Salesforce Marketing Cloud Account Engagement 執行個體的業務單位 ID。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Salesforce Marketing Cloud Account Engagement Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - + 在同步模式中 - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + 在非同步模式中 - 預設：目前的 `DateTime` 值 (根據使用者的時區) - 1 年。用於讀取。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 Salesforce Marketing Cloud Account Engagement 執行個體 URL。 + `PARTITION_BY`(String) - (必要) 用於讀取。要執行的分區類型。如果為欄位型分區，則會傳遞 "FIELD"。 + `TRANSFER_MODE`(String) - (選用)，如果未提供此選項，則用於在 ASYNC 模式下執行任務的值將在 SYNC 模式下執行。 # Salesforce Marketing Cloud Account Engagement 連接器的限制和備註 下列為適用備註和限制： + 同時套用限制和分區時，限制優先於分區。 + 根據 API 文件，`SalesforceMarketingCloudEngagement` 對每日和並行請求強制執行 RateLimit。如需詳細資訊，請參閱[速率限制](https://developer.salesforce.com/docs/marketing/pardot/guide/overview.html?q=limitation#rate-limits)。 + Export API 受限於您帳戶的每日 Account Engagement API 呼叫限制和並行 Account Engagement API 呼叫限制。 + 與佇列類似，Export/Async API 呼叫會針對每個帳戶依序執行。較舊的匯出會在較新的匯出之前進行處理。 + 非同步模式中不支援分區。 + Export/Async API 呼叫中指定的所選欄位數目不能超過 150。 + **Prospect** 實體支援 150 多個欄位，但一次只能選取 150 個欄位。如果選擇 `Select All`，則會排除某些欄位。若要擷取這些排除欄位的資料，必須將其包含在 `Selected Fields` 選項中。 以下是 `SELECT_ALL` 中排除的欄位清單 - `updatedBy.firstName`、`updatedBy.lastName`、`updatedBy.jobTitle`、`updatedBy.roleName`、`updatedBy.salesforceId`、`updatedBy.createdAt`、`updatedBy.updatedAt`、`updatedBy.isDeleted`、`updatedBy.createdById`、`updatedBy.updatedById`、`updatedBy.tagReplacementLanguage` + 無法為 Async 匯出集合欄位。例如，在「列出電子郵件」中不支援 `senderOptions` 和 `replyToOptions` 欄位。 + 對於所有實體，篩選是強制性的。如果未提供篩選條件，預設篩選條件述詞會設定為 `Created After` 欄位，其值為目前日期時間 (調整為您的時區) 減去一年。 + 根據 Salesforce Marketing Cloud Account Engagement 限制，在 Async 中，擷取資料的範圍上限為 1 年。如果提供的查詢超過 1 年，任務會擲回錯誤。 + 目前，Salesforce Pardot 中存在錯誤。當任務僅包含沒有任何資料的單一欄位時，欄位值不會傳回正確的結果，而是會多次傳回欄位名稱。Salesforce Pardot 團隊意識到了問題，並積極制定解決方案。 # 在 AWS Glue Studio 中連線至 SAP HANA AWS Glue 會提供 SAP HANA 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 SAP HANA、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 AWS Glue Studio 會為 SAP HANA 建立統一連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 **Topics** + [建立 SAP HANA 連線](creating-saphana-connection.md) + [建立 SAP HANA 來源節點](creating-saphana-source-node.md) + [建立 SAP HANA 目標節點](creating-saphana-target-node.md) + [進階選項](#creating-saphana-connection-advanced-options) # 建立 SAP HANA 連線 若要從 連線至 SAP HANA AWS Glue，您需要在 AWS Secrets Manager 秘密中建立和存放 SAP HANA 登入資料，然後將該秘密與 SAP HANA AWS Glue 連線建立關聯。您將需要設定 SAP HANA 服務與 AWS Glue之間的網路連線。 **先決條件：** + 如果您的 SAP HANA 服務位於 Amazon VPC 中，請設定 Amazon VPC 以允許您的 AWS Glue 任務與 SAP HANA 服務通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 AWS Glue 將在執行任務時使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 SAP HANA 端點與此位置之間的網路流量。您的任務將需要與 SAP HANA JDBC 連接埠建立 TCP 連線。如需有關 SAP HANA 連接埠的詳細資訊，請參閱 [SAP HANA 文件](https://help.sap.com/docs/HANA_SMART_DATA_INTEGRATION/7952ef28a6914997abc01745fef1b607/88e2e8bded9e4041ad3ad87dc46c7b55.html?locale=en-US)。根據您的網路配置，這可能需要變更安全群組規則、網路 ACL、NAT 閘道及對等連線。 **設定連至 SAP HANA 的連線：** 1. 在 中 AWS Secrets Manager，使用您的 SAP HANA 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *saphanaUsername* 值來建立 `username/USERNAME` 金鑰對。 + 在選取**鍵/值組**時，請使用 *saphanaPassword* 值來建立 `password/PASSWORD` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便未來在 AWS Glue中使用。 + 選取**連線類型**時，請選取 SAP HANA。 + 提供 **SAP HANA URL** 時，請提供執行個體的 URL。 SAP HANA JDBC URL 會採用的格式為 `jdbc:sap://saphanaHostname:saphanaPort/?databaseName=saphanaDBname,ParameterName=ParameterValue` AWS Glue 需要下列 JDBC URL 參數： + `databaseName`：要連線之 SAP HANA 的預設資料庫。 + 選取 **AWS 機密**時，請提供 *secretName*。 建立 AWS Glue SAP HANA 連線後，您必須先執行下列步驟，才能執行 AWS Glue 任務： + 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 *secretName* 的許可。 # 建立 SAP HANA 來源節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue SAP HANA 連線，如上節所述：[建立 SAP HANA 連線](creating-saphana-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要讀取的 SAP HANA 資料表 *tableName* 或查詢 *targetQuery*。 您可以在表單 `schemaName.tableName` 中使用 SAP HANA 資料表名稱和結構描述名稱來指定資料表。如果資料表位於預設結構描述 "public" 中，則不需要結構描述名稱和 "." 分隔符號。呼叫此 *tableIdentifier*。請注意，在 `connectionName` 中，資料庫會以 JDBC URL 參數形式提供。 ## 新增 SAP HANA 資料來源 **新增**資料來源 – SAP HANA** 節點：** 1. 選擇 SAP HANA 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 SAP HANA 連線**。如需詳細資訊，請參閱前一 [建立 SAP HANA 連線](creating-saphana-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇 **SAP HANA 來源**選項： + **選擇單一資料表**：從單一資料表存取所有資料。 + **輸入自訂查詢**：根據自訂查詢從多個資料表存取資料集。 1. 如果您選擇單一資料表，請輸入 *tableName*。 如果您選擇**輸入自訂查詢**，請輸入 SQL SELECT 查詢。 1. 在**自訂 SAP HANA 屬性**中，視需要輸入參數和值。 # 建立 SAP HANA 目標節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue SAP HANA 連線，如上節所述：[建立 SAP HANA 連線](creating-saphana-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 SAP HANA 資料表 *tableName*。 您可以在表單 `schemaName.tableName` 中使用 SAP HANA 資料表名稱和結構描述名稱來指定資料表。如果資料表位於預設結構描述 "public" 中，則不需要結構描述名稱和 "." 分隔符號。呼叫此 *tableIdentifier*。請注意，在 `connectionName` 中，資料庫會以 JDBC URL 參數形式提供。 ## 新增 SAP HANA 資料目標 **新增**資料目標 – SAP HANA** 節點：** 1. 選擇 SAP HANA 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 SAP HANA 連線**。如需詳細資訊，請參閱前一 [建立 SAP HANA 連線](creating-saphana-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 透過提供 *tableName* 來設定**資料表名稱**。 1. 在**自訂 Teradata 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 SAP HANA 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[SAP HANA 連線](aws-glue-programming-etl-connect-saphana-home.md)。 # 連線至 SAP OData SAP OData 是一種標準 Web 協定，用於使用 ABAP (進階業務應用程式程式設計) 查詢和更新 SAP 中存在的資料，套用和建置 HTTP 等 Web 技術，以從各種外部應用程式、平台和裝置存取資訊。使用該產品，您可以存取所需的一切，以協助您與 SAP 系統、應用程式或資料無縫整合。 **Topics** + [AWS Glue 支援 SAP OData](sap-odata-support.md) + [建立連線](sap-odata-creating-connections.md) + [建立 SAP OData 任務](sap-odata-creating-job.md) + [寫入到 SAP OData](sap-odata-writing.md) + [使用 SAP OData 狀態管理指令碼](sap-odata-state-management-script.md) + [非 ODP 實體的分區](sap-odata-non-odp-entities-partitioning.md) + [SAP OData 連線選項](sap-odata-connection-options.md) + [SAP OData 實體和欄位詳細資訊](sap-odata-entity-field-details.md) # AWS Glue 支援 SAP OData AWS Glue 支援 SAP OData，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 SAP OData 查詢資料。 **支援作為目標？** 是。您可以使用 AWS Glue ETL 任務將記錄寫入 SAP OData。 **支援的 SAP OData API 版本** 支援下列 SAP OData API 版本： + 2.0 **支援的來源** 支援下列來源： + ODP (Operational Data Provisioning) 來源： + BW Extractors (DataSources) + CDS Views + SLT + 非 ODP 來源，例如： + CDS View 服務 + RFC 型服務 + 自訂 ABAP 服務 **支援的 SAP 元件** 以下是最低要求： + 必須為服務探索啟用目錄服務。 + 在 SAP 系統的 SAP Gateway 中設定要擷取的營運資料佈建 (ODP) 資料來源。 + **OData V2.0**：透過交易 `/IWFND/MAINT_SERVICE` 在您的 SAP Gateway 中啟用 OData V2.0 目錄服務。 + 透過交易 `/IWFND/MAINT_SERVICE` 在 SAP Gateway 中啟用 OData V2.0 服務。 + SAP OData 服務必須支援用戶端分頁/查詢選項，例如 `$top` 和 `$skip`。其還必須支援系統查詢選項 `$count`。 + 您必須為 SAP 中的使用者提供必要的授權，以探索服務並使用 SAP OData 服務擷取資料。請參閱 SAP 提供的安全文件。 + 如果想要使用 OAuth 2.0 作為授權機制，則必須為 OData 服務啟用 OAuth 2.0，並根據 SAP 文件註冊 OAuth 用戶端。 + 若要根據 ODP 資料來源產生 OData 服務，SAP Gateway Foundation 必須在 ERP/BW 堆疊或中樞組態中進行本機安裝。 + 對於 ERP/BW 應用程式，SAP NetWeaver AS ABAP 堆疊必須為 7.50 SP02 或更高版本。 + 對於中樞系統 (SAP Gateway)，中樞系統的 SAP NetWeaver AS ABAP 必須為 7.50 SP01 或更高版本，才能進行遠端中樞設定。 + 對於非 ODP 來源，SAP NetWeaver 堆疊版本必須為 7.40 SP02 或更高版本。 **支援的身分驗證方法** 支援下列身分驗證方法： + 基本身分驗證 + OAuth 2.0 # 先決條件 使用 SAP OData 連線啟動從 SAP OData 擷取資料 AWS Glue 的任務之前，請先完成下列先決條件： + 必須在 SAP 系統中啟用相關的 SAP OData Service，以確保資料來源可供取用。如果未啟用 OData 服務，Glue 任務將無法從 SAP 中存取或擷取資料。 + 必須在 SAP 中設定適當的身分驗證機制，例如基本 （自訂） 身分驗證或 OAuth 2.0，以確保 AWS Glue 任務可以成功與 SAP OData 服務建立連線。 + 設定 IAM 政策以授予 AWS Glue 任務適當的許可，以存取 SAP、Secrets Manager 和程序中涉及的其他 AWS 資源。 + 如果 SAP 系統託管在私有網路中，則必須設定 VPC 連線，以確保 AWS Glue 任務可以安全地與 SAP 通訊，而不會透過公有網際網路公開敏感資料。 AWS Secrets Manager 可用來安全地存放敏感資訊，例如 SAP 登入資料， AWS Glue 任務可在執行時間動態擷取。這種方法不需要硬式編碼憑證，可提高安全性和靈活性。 下列先決條件提供step-by-step指引，說明如何設定每個元件，以在 AWS Glue 和 SAP OData 之間順暢整合。 **Topics** + [SAP OData 啟用](sap-odata-activation.md) + [IAM 政策](sap-odata-configuring-iam-permissions.md) + [連線/VPC 連線](sap-odata-connectivity-vpc-connection.md) + [SAP 身分驗證](sap-odata-authentication.md) + [AWS Secrets Manager 來存放您的 Auth 秘密](sap-odata-aws-secret-manager-auth-secret.md) # SAP OData 啟用 完成 SAP OData 連線的下列步驟： ## ODP 來源 必須先符合下列要求，才能從 ODP 提供者中傳輸資料： + 您擁有 SAP NetWeaver AS ABAP 執行個體。 + 您的 SAP NetWeaver 執行個體包含您要從中傳輸資料的 ODP 提供者。ODP 提供者包括： + SAP DataSources (交易代碼 RSO2) + SAP 核心資料服務 ABAP CDS 檢視 + SAP BW 或 SAP BW/4HANA 系統 (InfoObject、DataStore Object) + 透過 SAP Landscape Replication Server (SAP SLT)，從 SAP 來源系統即時複寫資料表和資料庫檢視 + SAP ABAP 型來源中的 SAP HANA 資訊檢視 + 您的 SAP NetWeaver 執行個體具有 SAP Gateway Foundation 元件。 + 您已建立可從 ODP 提供者處擷取資料的 OData 服務。若要建立 OData 服務，請使用 SAP Gateway Service Builder。若要存取 ODP 資料，Amazon AppFlow 會使用 OData API 來呼叫此服務。如需詳細資訊，請參閱 SAP BW/4HANA 文件中的[透過 OData 產生擷取 ODP 資料的服務](https://help.sap.com/docs/SAP_BPC_VERSION_BW4HANA/dd104a87ab9249968e6279e61378ff66/69b481859ef34bab9cc7d449e6fff7b6.html?version=11.0)。 + 若要根據 ODP 資料來源產生 OData 服務，SAP Gateway Foundation 必須在 ERP/BW 堆疊或中樞組態中進行本機安裝。 + 對於 ERP/BW 應用程式，SAP NetWeaver AS ABAP 堆疊必須為 7.50 SP02 或更高版本。 + 對於中樞系統 (SAP Gateway)，中樞系統的 SAP NetWeaver AS ABAP 必須為 7.50 SP01 或更高版本，才能進行遠端中樞設定。 ## 非 ODP 來源 + SAP NetWeaver 堆疊版本必須為 7.40 SP02 或更高版本。 + 必須為服務探索啟用目錄服務。 + **OData V2.0**：可透過交易 `/IWFND/MAINT_SERVICE` 在您的 SAP Gateway 中啟用 OData V2.0 目錄服務 + SAP OData 服務必須支援用戶端分頁/查詢選項，例如 `$top` 和 `$skip`。其還必須支援系統查詢選項 `$count`。 + 對於 OAuth 2.0，必須為 OData 服務啟用 OAuth 2.0，並根據 SAP 文件註冊 OAuth 用戶端，設定已授權的重新導向 URL，如下所示： + `https://.console.aws.amazon.com/gluestudio/oauth`，``將 取代 AWS Glue 為正在執行的區域，例如：us-east-1。 + 必須啟用安全設定以透過 HTTPS 進行連線。 + 必須為 SAP 中的使用者提供必要的授權，以探索服務並使用 SAP OData 服務擷取資料。請參閱 SAP 提供的安全文件。 # IAM 政策 ## 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS IAM 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue" ], "Resource": "*" } ] } ``` ------ 該角色必須授予對任務使用的所有資源的存取權，例如 Amazon S3。如果不想使用上述方法，可選擇使用下列受管 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 主控台的使用者。 + [SecretsManagerReadWrite](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/SecretsManagerReadWrite) – 透過 AWS 管理主控台提供讀取/寫入存取權給 AWS Secrets Manager。注意：這不包括 IAM 動作，因此如果需要輪換組態，請結合 `IAMFullAccess`。 **設定 VPC 所需的 IAM 政策/許可** 使用 VPC 連線建立 AWS Glue 連線時，需要下列 IAM 許可。如需詳細資訊，請參閱[為 AWS Glue建立 IAM 政策](https://docs.aws.amazon.com/glue/latest/dg/create-service-policy.html)。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface", "ec2:DescribeNetworkInterfaces" ], "Resource": [ "*" ] } ] } ``` ------ # 連線/VPC 連線 VPC 連線步驟： 1. 使用現有 VPC 連線，或遵循 [Amazon VPC 文件](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html)建立新連線。 1. 請確保擁有將流量路由到網際網路的 NAT 閘道。 1. 選擇 VPC 端點作為 Amazon S3 閘道來建立連線。 1. 啟用 DNS 解析和 DNS 主機名稱以使用 AWS 提供的 DNS 服務。 1. 前往已建立的 VPC，並為 STS AWS Glue、Secret Manager 等不同服務新增必要的端點。 1. 選擇建立端點。 1. 針對服務類別，選擇 AWS 服務。 1. 針對「服務名稱」，選擇要連線的服務。 1. 選擇 VPC 並啟用 DNS 名稱。 1. VPC 連線所需的 VCP 端點： 1. [STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sts_vpc_endpoint_create.html) 1. [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html) 1. [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) ## 安全群組設定 安全群組必須允許來自 AWS Glue VPC 的接聽連接埠流量， AWS Glue 才能連線到它。最佳實務是盡可能限制來源 IP 地址的範圍。 AWS Glue 需要特殊的安全群組，允許所有來自其本身的傳入流量。可以建立自我參考規則，其允許來自安全群組的所有流量。可以修改現有的安全群組，並將安全群組指定為來源。 從 URL 端點的 HTTPS 連接埠 (NLB 或 SAP 執行個體) 中開啟通訊。 ## 連線選項 + HTTPS 與內部和外部 NLB 的連線，來自憑證認證機構 (CA) 的 SSL 憑證，而非自我簽署的 SSL 憑證 + 與來自憑證認證機構 (CA) 的 SAP 執行個體 SSL 憑證的 HTTPS 連線，而非自我簽署的 SSL 憑證 # SAP 身分驗證 SAP 連接器同時支援 CUSTOM (這是 SAP BASIC 身分驗證) 和 OAUTH 身分驗證方法。 ## 自訂身分驗證 AWS Glue 支援自訂 （基本身分驗證） 作為建立 SAP 系統連線的方法，允許使用使用者名稱和密碼進行安全存取。此身分驗證類型適用於自動化案例，因為它允許在 SAP OData 執行個體中預先使用具有特定使用者許可的使用者名稱和密碼。 AWS Glue 可以使用使用者名稱和密碼來驗證 SAP OData APIs。在 中 AWS Glue，基本授權會實作為自訂授權。 如需基本驗證流程的公有 SAP OData 文件，請參閱 [HTTP 基本身分驗證](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/5c8bca0af1654b05a83193b2922dcee2.html)。 ## OAuth 2.0 身分驗證 AWS Glue 也支援 OAuth 2.0 做為建立 SAP 系統連線的安全身分驗證機制。這可實現無縫整合，同時確保符合現代身分驗證標準，並提高資料存取的安全性。 ## AUTHORIZATION\$1CODE 授權類型 授予類型決定 如何與 SAP OData AWS Glue 通訊，以請求存取您的資料。SAP OData 僅支援 `AUTHORIZATION_CODE` 授權類型。此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 使用者仍然可以選擇在 SAP OData 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 SAP OData 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 SAP OData 文件，請參閱[使用 OAuth 2.0 進行身份驗證](https://help.sap.com/docs/ABAP_PLATFORM_NEW/e815bb97839a4d83be6c4fca48ee5777/2e5104fd87ff452b9acb247bd02b9f9e.html)。 # AWS Secrets Manager 來存放您的 Auth 秘密 您需要將 SAP OData 連線秘密存放在 AWS Secrets Manager 中，設定必要的擷取許可，如 [IAM 政策](sap-odata-configuring-iam-permissions.md)一節所指定，並在建立連線時使用它。 使用 AWS Secrets Manager 的 AWS 管理主控台為您的 SAP 來源建立秘密。如需詳細資訊，請參閱[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。 AWS Secrets Manager 中的詳細資訊應該包含下列程式碼中的元素。 ## 自訂身分驗證機密 您需要輸入 SAP 系統使用者名稱而非 **，輸入其密碼而非 **，並輸入 True 或 False。在此情況下，將 `basicAuthDisableSSO` 設定為 `true` 會停用基本身分驗證請求的單一登入 (SSO)，每個請求都需要明確的使用者憑證。相反，如果可用，將其設定為 `false` 可允許使用現有的 SSO 工作階段。 ``` { "basicAuthUsername": "", "basicAuthPassword": "", "basicAuthDisableSSO": "", "customAuthenticationType": "CustomBasicAuth" } ``` ## OAuth 2.0 機密 如果您使用 OAuth 2.0 做為身分驗證機制， AWS Secrets Manager 中的秘密應該具有下列格式**的使用者受管用戶端應用程式 ClientId**。您需要輸入 SAP 用戶端機密而非 。 ``` {"USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET": "" } ``` # 建立連線 若要設定 SAP OData 連線： 1. 登入 AWS 管理主控台並開啟[AWS Glue 主控台](https://console.aws.amazon.com/glue)。在 AWS Glue Studio 中，依照下列步驟建立連線： 1. 按一下左側面板中的「資料連線」。 1. 按一下「建立連線」。 1. 在**選擇資料來源**中選取 **SAP OData** 1. 提供您要連線之 SAP OData 執行個體的**應用程式主機 URL**。對於非 VPC 連線，必須可透過公有網際網路存取此應用程式主機 URL。 1. 提供您要連線之 SAP OData 執行個體的**應用程式服務路徑**。這與目錄服務路徑相同。例如：`/sap/opu/odata/iwfnd/catalogservice;v=2`. AWS Glue doesn 不接受特定物件路徑。 1. 提供您要連線之 SAP OData 執行個體的**用戶端編號**。可接受的值為 [001-999]。範例： 010 1. 提供您要連線之 SAP OData 執行個體的**連接埠號碼**。範例：443 1. 提供您要連線之 SAP OData 執行個體的**登入語言**。範例：EN 1. 選取 AWS Glue 可擔任的 AWS IAM 角色，並具有 [IAM 政策](sap-odata-configuring-iam-permissions.md)區段中所述的許可。 1. AWS Glue 從下拉式清單中選取您要用於 中此連線的**身分驗證類型**：OAUTH2 或 CUSTOM 1. CUSTOM - 選取您在 [AWS Secrets Manager 來存放您的 Auth 秘密](sap-odata-aws-secret-manager-auth-secret.md) 一節中指定的機密。 1. OAUTH 2.0 - 僅在 OAuth 2.0 的情況下鍵入下列輸入： 1. 在**使用者管理的用戶端應用程式用戶端 Id** 下，輸入您的用戶端 ID。 1. `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` （您的用戶端秘密） 位於您在 [AWS Secrets Manager 來存放您的 Auth 秘密](sap-odata-aws-secret-manager-auth-secret.md)區段中建立的 AWS Secrets Manager。 1. 在**授權碼 URL** 下，輸入授權碼 URL。 1. 在**授權字符 URL** 下，輸入授權字符 URL。 1. 在 **OAuth 範圍下**，輸入以空格分隔的 OAuth 範圍。範例：`/IWFND/SG_MED_CATALOG_0002 ZAPI_SALES_ORDER_SRV_0001` 1. 如果想要使用您的網路，請選取網路選項。如需詳細資訊，請參閱[連線/VPC 連線](sap-odata-connectivity-vpc-connection.md)。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。如需詳細資訊，請參閱「[IAM 政策](sap-odata-configuring-iam-permissions.md)」。 1. 選擇**測試連線**並測試您的連線。如果連線測試通過，請按一下「下一步」，然後輸入連線名稱並儲存連線。如果已選擇網路選項 (VPC)，則無法使用測試連線功能。 # 建立 SAP OData 任務 請參閱[使用 AWS Glue Studio 建置視覺化 ETL 任務](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html) # 營運資料佈建 (ODP) 來源 營運資料佈建 (ODP) 提供技術基礎設施，可以用來支援各種目標應用程式的資料擷取和複寫，並支援這些案例中的 delta 機制。如果為 delta 程序，來源 (ODP 提供者) 中的資料會使用更新程序自動寫入 delta 佇列 (Operational Delta Queue – ODQ)，或使用擷取器界面傳遞至 delta 佇列。ODP 提供者可以是 DataSource (擷取器)、ABAP Core Data Services Views (ABAP CDS Views)、SAP BW 或 SAP BW/4HANA、SAP Landscape Transformation Replication Server (SLT) 和 SAP HANA Information Views (計算檢視)。目標應用程式 (稱為 ODQ 「訂閱者」或更普遍稱為「ODP 消費者」) 從 delta 佇列中擷取資料並繼續處理資料。 ## 完整載入 在 SAP OData 和 ODP 實體的內容中，**完整載入**是指在單一操作中從 ODP 實體擷取所有可用資料的程序。此操作會從來源系統中擷取完整的資料集，確保目標系統擁有實體資料的完整最新副本。完全載入通常用於不支援增量載入的來源或需要重新整理目標系統時。 **範例** 您可以在建立 DynamicFrame 時，明確將 `ENABLE_CDC` 旗標設為 false。注意：`ENABLE_CDC` 預設為 false，如果您不想初始化 delta 佇列，則不需要傳送此旗標或將其設定為 true。未將此旗標設定為 true 將導致完整的載入擷取。 ``` sapodata_df = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "ENABLE_CDC": "false" }, transformation_ctx=key) ``` ## 增量載入 ODP (Operational Data Provisioning) 實體內容中的**增量載入**包括自上次資料擷取以來，僅從來源系統擷取新的或變更的資料 (delta)，避免預先處理已處理的記錄。這種方法可大幅提升效率、減少資料傳輸量、提高效能、確保系統之間的高效同步，並將處理時間降至最低，尤其是經常變更的大型資料集。 # Delta Token 型增量傳輸 對於支援其已啟用 ODP 的實體，若要使用變更資料擷取 (CDC) 啟用增量傳輸，請遵循下列步驟： 1. 在指令碼模式下建立增量傳輸任務。 1. 建立 DataFrame 或 Glue DynamicFrame 時，需要傳遞選項 `"ENABLE_CDC": "True"`。此選項可確保您會收到來自 SAP 的 Delta Token，其可用於後續擷取變更的資料。 Delta Token 會出現在 DELTA\$1TOKEN 資料欄中 dataframe 的最後一列。此字符可用作後續呼叫中的連接器選項，以逐步擷取下一組資料。 **範例** + 建立 DynamicFrame 時，我們會將 `ENABLE_CDC` 旗標設定為 `true`。注意：`ENABLE_CDC` 預設為 `false`，如果您不想初始化 delta queue，則不需要傳送此旗標或將其設定為 true。未將此旗標設定為 true 將導致完整的載入擷取。 ``` sapodata_df = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "ENABLE_CDC": "true" }, transformation_ctx=key) # Extract the delta token from the last row of the DELTA_TOKEN column delta_token_1 = your_logic_to_extract_delta_token(sapodata_df) # e.g., D20241029164449_000370000 ``` + 擷取的 delta token 可以作為選項進行傳遞，以擷取新事件。 ``` sapodata_df_2 = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", // passing the delta token retrieved in the last run "DELTA_TOKEN": delta_token_1 } , transformation_ctx=key) # Extract the new delta token for the next run delta_token_2 = your_logic_to_extract_delta_token(sapodata_df_2) ``` 請注意，其中存在 `DELTA_TOKEN` 的最後一個記錄不是來自來源的交易記錄，而是僅用於傳遞 delta token 值。 除了 `DELTA_TOKEN` 之外，dataframe 的每一列都會傳回下列欄位。 + **GLUE\$1FETCH\$1SQ**：這是一個序列欄位，按照記錄接收順序從 EPOC 時間戳記產生，對於每個記錄都是唯一的。如果您需要了解或建立來源系統中的變更順序，則可以使用此功能。只有啟用 ODP 的實體才會出現此欄位。 + **DML\$1STATUS**：這會顯示來源中所有新插入和更新記錄的 `UPDATED`，以及已從來源中刪除之記錄的 `DELETED`。 如需有關如何管理狀態和重複使用 delta token 以透過範例擷取變更記錄的詳細資訊，請參閱 [使用 SAP OData 狀態管理指令碼](sap-odata-state-management-script.md) 一節。 ## Delta Token 失效 Delta Token 與服務集合和使用者相關聯。如果針對相同的服務集合和使用者啟動具有 `“ENABLE_CDC” : “true”` 的新初始提取，則 SAP OData 服務將使先前初始化後簽發的所有之前的 delta token 失效。使用過期的 delta token 叫用連接器將導致例外狀況： `Could not open data access via extraction API RODPS_REPL_ODP_OPEN` # OData 服務 (非 ODP 來源) ## 完整載入 對於非 ODP (營運資料佈建) 系統，**完整載入**涉及從來源系統擷取整個資料集，並將其載入目標系統。由於非 ODP 系統本質上不支援 deltas 等進階資料擷取機制，因此程序非常簡單，但可能會耗費大量資源，具體取決於資料大小。 ## 增量載入 對於不支援 **ODP (營運資料佈建)** 的系統或實體，可透過實作時間戳記型機制來追蹤和擷取變更，手動管理增量資料傳輸。 **時間戳記型增量傳輸** 對於啟用非 ODP 的實體 (或未使用 ENABLE\$1CDC 旗標的已啟用 ODP 的實體)，我們可以在連接器中使用 `filteringExpression` 選項來指示要擷取資料的 `datetime` 間隔。此方法依賴於資料中的時間戳記欄位，表示上次建立/修改每個記錄的時間。 **範例** 擷取 2024-01-01T00：00：00.000 之後變更的記錄 ``` sapodata_df = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "filteringExpression": "LastChangeDateTime >= 2024-01-01T00:00:00.000" }, transformation_ctx=key) ``` 注意：在此範例中，`LastChangeDateTime` 欄位表示上次修改每個記錄的時間。實際欄位名稱可能會因您的特定 SAP OData 實體而有所不同。 若要在後續執行中取得新的資料子集，可以使用新的時間戳記來更新 `filteringExpression`。一般而言，這是先前擷取資料的最大時間戳記值。 **範例** ``` max_timestamp = get_max_timestamp(sapodata_df) # Function to get the max timestamp from the previous run next_filtering_expression = f"LastChangeDateTime > {max_timestamp}" # Use this next_filtering_expression in your next run ``` 在下一節中，我們將提供自動化方法來管理這些時間戳記型增量傳輸，無需在執行之間手動更新篩選表達式。 # 寫入到 SAP OData 本節說明如何使用 SAP OData AWS Glue 連接器將資料寫入 SAP OData Service。 **先決條件** + 存取 SAP OData 服務 + 您想要寫入到的 SAP OData EntitySet 物件。將需要物件名稱。 + 有效的 SAP OData 憑證和有效的連線 + IAM [政策](https://docs.aws.amazon.com/glue/latest/dg/sap-odata-configuring-iam-permissions.html)中所述的適當許可 SAP OData 連接器支援兩種寫入操作： + INSERT + UPDATE 使用 UPDATE 寫入操作時，必須提供 ID\$1FIELD\$1NAMES 來指定記錄的外部 ID 欄位。 **範例**： ``` sapodata_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="sapodata", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "WRITE_OPERATION": "INSERT" } ``` # 使用 SAP OData 狀態管理指令碼 若要在 AWS Glue 任務中使用 SAP OData 狀態管理指令碼，請遵循下列步驟： + 下載狀態管理指令碼：公有 Amazon S3 儲存貯體中的 `s3://aws-blogs-artifacts-public/artifacts/BDB-4789/sap_odata_state_management.zip `。 + 將指令碼上傳至您的 AWS Glue 任務具有存取許可的 Amazon S3 儲存貯體。 + 參考 AWS Glue 任務中的指令碼：建立或更新 AWS Glue 任務時，請傳遞參考 Amazon S3 儲存貯體中指令碼路徑`'--extra-py-files'`的選項。例如：`--extra-py-files s3://your-bucket/path/to/sap_odata_state_management.py` + 在 AWS Glue 任務指令碼中匯入和使用狀態管理程式庫。 ## Delta-token 型增量傳輸範例 以下是如何使用狀態管理指令碼進行 Delta-token 型增量傳輸的範例： ``` from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType # Initialize the state manager state_manager = StateManagerFactory.create_manager( manager_type=StateManagerType.JOB_TAG, state_type=StateType.DELTA_TOKEN, options={ "job_name": args['JOB_NAME'], "logger": logger } ) # Get connector options (including delta token if available) key = "SAPODataNode" connector_options = state_manager.get_connector_options(key) # Use the connector options in your Glue job df = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "ENABLE_CDC": "true", **connector_options } ) # Process your data here... # Update the state after processing state_manager.update_state(key, sapodata_df.toDF()) ``` ## 時間戳記型增量傳輸範例 以下是如何使用狀態管理指令碼進行 Delta-token 型增量傳輸的範例： ``` from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType # Initialize the state manager state_manager = StateManagerFactory.create_manager( manager_type=StateManagerType.JOB_TAG, state_type=StateType.DELTA_TOKEN, options={ "job_name": args['JOB_NAME'], "logger": logger } ) # Get connector options (including delta token if available) key = "SAPODataNode" connector_options = state_manager.get_connector_options(key) # Use the connector options in your Glue job df = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "ENABLE_CDC": "true", **connector_options } ) # Process your data here... # Update the state after processing state_manager.update_state(key, sapodata_df.toDF()) ``` 在這兩個範例中，狀態管理指令碼會處理在任務執行之間存放狀態 (delta token 或時間戳記) 的複雜性。其會在取得連接器選項時自動擷取最後的已知狀態，並在處理後更新狀態，確保每個任務只會處理最新的或變更的資料。 # 非 ODP 實體的分區 在 Apache Spark 中，分區是指在叢集中的工作者節點之間分區和分配資料以進行平行處理的方式。每個分區都是可由任務獨立處理的資料邏輯區塊。分割是 Spark 中的基本概念，直接影響效能、可擴展性和資源使用率。 AWS Glue 工作使用 Spark 的分割機制，將資料集分割為較小的區塊 （分割區），可在叢集的工作者節點之間平行處理。請注意，分區不適用於 ODP 實體。 如需詳細資訊，請參閱 [AWS Glue Spark 和 PySpark 任務](https://docs.aws.amazon.com/glue/latest/dg/spark_and_pyspark.html)。 **先決條件** 您想要從中讀取的 SAP OData 的物件。將需要物件/實體集名稱。例如：` /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder `。 **範例** ``` sapodata_read = glueContext.create_dynamic_frame.from_options( connection_type="SAPOData", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "/sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder" }, transformation_ctx=key) ``` ## 分區查詢 ### 欄位型分區 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。Integer、Date 和 DateTime 欄位在 SAP OData 連接器中支援欄位型分區。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於資料類型為 DateTime 的所有欄位，可接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例：`"2000-01-01T00:00:00.000Z"` + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 + `PARTITION_BY`：要執行的類型分區，如果為欄位型分區，則會傳遞 `FIELD`。 **範例** ``` sapodata= glueContext.create_dynamic_frame.from_options( connection_type="sapodata", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet", "PARTITION_FIELD": "validStartDate" "LOWER_BOUND": "2000-01-01T00:00:00.000Z" "UPPER_BOUND": "2020-01-01T00:00:00.000Z" "NUM_PARTITIONS": "10", "PARTITION_BY": "FIELD" }, transformation_ctx=key) ``` ### 記錄型分區 原始查詢會分區為 Spark 任務可同時執行的子查詢的 `NUM_PARTITIONS` 數目。 記錄型分區僅支援非 ODP 實體，因為下一個 token/skip token 支援 ODP 實體中的分頁。 + `PARTITION_BY`：要執行的類型分區。如果為記錄型分區，則會傳遞 `COUNT`。 **範例** ``` sapodata= glueContext.create_dynamic_frame.from_options( connection_type="sapodata", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet", "NUM_PARTITIONS": "10", "PARTITION_BY": "COUNT" }, transformation_ctx=key) ``` # 限制/標註 + ODP 實體與記錄型分區不相容，因為分頁是使用 skip token/delta token 來處理的。因此，對於記錄型分區，無論使用者輸入為何，maxConcurrency 的預設值都會設為 "null"。 + 同時套用限制和分區時，限制優先於分區。 # SAP OData 連線選項 以下是 SAP OData 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。SAP OData 中的物件名稱。 例如：/sap/opu/odata/sap/API\$1SALES\$1ORDER\$1SRV/A\$1SalesOrder + `API_VERSION`(String) - (選用) 用於讀取。您想要使用的 SAP OData Rest API 版本。範例：2.0。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 例如：SalesOrder + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 例如：`SalesOrder = "10"` + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 例如：`SELECT * FROM /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder` + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 例如：`ValidStartDate` + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 例如：`"2000-01-01T00:00:00.000Z"` + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 例如：`"2024-01-01T00:00:00.000Z"` + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - SAP 執行個體應用程式主機 URL。 例如：`https://example-externaldata.sierra.aws.dev` + `SERVICE_PATH`(String) - SAP 執行個體應用程式服務路徑。 例如：`/sap/opu/odata/iwfnd/catalogservice;v=2` + `CLIENT_NUMBER`(String) - SAP 執行個體應用程式用戶端編號。 例如：100 + `PORT_NUMBER`(String) - 預設：SAP 執行個體應用程式連接埠號碼。 例如：443 + `LOGON_LANGUAGE`(String) - SAP 執行個體應用程式登入語言。 例如：`EN` + `ENABLE_CDC`(String) - 定義是否在啟用 CDC 的情況下執行任務，即追蹤變更。 例如：`True/False` + `DELTA_TOKEN`(String) - 根據提供的有效 Delta Token 執行增量資料提取。 例如：`D20241107043437_000463000` + `PAGE_SIZE`(Integer) - 定義查詢記錄的頁面大小。預設頁面大小為 50，000。指定頁面大小時，SAP 僅傳回每個 API 呼叫定義的記錄數，而不是整個資料集。連接器仍會提供記錄總數，並使用指定的頁面大小來處理分頁。如果需要更大的頁面大小，可以選擇任何值，最高可達 500,000，這是允許的最大值。將會忽略超過 500,000 的指定頁面大小。反之，系統會使用允許的頁面大小上限。您可以新增`PAGE_SIZE`具有所需值的連線選項，在 AWS Glue Studio UI 中指定頁面大小。 例如：`20000` # SAP OData 實體和欄位詳細資訊 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/sap-odata-entity-field-details.html) # 連線至 SendGrid SendGrid 是交易和行銷電子郵件的客戶通訊平台。 + SendGrid 連接器有助於建立和管理聯絡人清單，以及建立電子郵件行銷活動。 + SendGrid 可讓線上企業、非營利組織和其他線上實體建立並向大量受眾傳送行銷電子郵件，並監控這些電子郵件的參與度。 **Topics** + [AWS Glue 支援 SendGrid](sendgrid-support.md) + [包含用於建立和使用連線的 API 操作的政策](sendgrid-configuring-iam-permissions.md) + [設定 SendGrid](sendgrid-configuring.md) + [設定 SendGrid 連線](sendgrid-configuring-connections.md) + [從 SendGrid 實體中讀取](sendgrid-reading-from-entities.md) + [SendGrid 連線選項](sendgrid-connection-options.md) + [SendGrid 限制](sendgrid-limitations.md) # AWS Glue 支援 SendGrid AWS Glue 支援 SendGrid，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 SendGrid 查詢資料。 **支援作為目標？** 否。 **支援的 SendGrid API 版本** 支援下列 SendGrid API 版本： + v3 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 SendGrid 您必須先符合下列要求，才能使用 從 SendGrid AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個具有 API 金鑰的 SendGrid 帳戶。 + 您的 SendGrid 帳戶具有包含有效授權的 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 SendGrid 帳戶。對於一般連線，不需要在 SendGrid 中執行任何其他操作。 # 設定 SendGrid 連線 SendGrid 支援自訂身分驗證。 如需產生自訂身分驗證所需 API 金鑰的公有 SendGrid 文件，請參閱[身分驗證](https://www.twilio.com/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/authentication)。 若要設定 SendGrid 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `api_key` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 SendGrid。 1. 提供您要連線的 SendGrid 執行個體的 `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`。 # 從 SendGrid 實體中讀取 **必要條件** 您要從中讀取的 SendGrid 物件。您將需要物件名稱，例如 `lists`、`singlesends` 或 `segments`。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 清單 | 否 | 是 | 否 | 是 | 否 | | 單次傳送 | 是 | 是 | 否 | 是 | 否 | | 行銷活動統計資料 - 自動化 | 是 | 是 | 否 | 是 | 否 | | 行銷活動統計資料 - 單次傳送 | 是 | 是 | 否 | 是 | 否 | | 客群 | 是 | 否 | 否 | 是 | 否 | | 聯絡人 | 是 | 否 | 否 | 是 | 否 | | Category | 否 | 否 | 否 | 是 | 否 | | 統計資料 | 是 | 否 | 否 | 是 | 否 | | 取消訂閱群組 | 是 | 否 | 否 | 是 | 否 | **範例**： ``` sendgrid_read = glueContext.create_dynamic_frame.from_options( connection_type="sendgrid", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "lists", "API_VERSION": "v3", "INSTANCE_URL": "instanceUrl" } ``` **SendGrid 實體和欄位詳細資訊**： 具有靜態中繼資料的實體： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/sendgrid-reading-from-entities.html) **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型，DateTime 資料類型會轉換為 Timestamp。 ## 分區查詢 SendGrid 不支援篩選條件型分區或記錄型分區。 # SendGrid 連線選項 以下是 SendGrid 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。SendGrid 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 SendGrid Rest API 版本。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 SendGrid 執行個體 URL。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # SendGrid 限制 以下是 SendGrid 的限制或備註： + 只有 `start_date` 欄位上的 Stats 實體和 `event_timestamp` 欄位上的 Contact 實體才支援增量提取。 + 只有 Marketing Campaign Stats (自動化)、Marketing Campaign Stats (單次傳送)、Single Sends 和 Lists 實體支援分頁。 + 對於 Stats 實體，`start_date` 為強制性篩選參數。 + 具有受限存取權限的 API 金鑰不支援 Email API 和 Stats 實體的讀取存取權。使用具有完整存取權的 API 金鑰。如需詳細資訊，請參閱 [API 概觀](https://www.twilio.com/docs/sendgrid/api-reference/api-keys/create-api-keys#api-overview)。 # 連線至 ServiceNow ServiceNow 是以雲端為基礎的 SaaS 平台，用於自動化 IT 管理工作流程。ServiceNow 平台可與其他工具輕鬆整合，讓使用者使用各種應用程式和外掛程式來管理專案、團隊和客戶互動。身為 ServiceNow 使用者，您可以 AWS Glue 連線至您的 ServiceNow 帳戶。然後，您可以在 ETL 任務中使用 ServiceNow 作為資料來源。執行這些任務，以在 ServiceNow AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 ServiceNow](servicenow-support.md) + [包含用於建立和使用連線的 API 操作的政策](servicenow-configuring-iam-permissions.md) + [設定 ServiceNow](servicenow-configuring.md) + [設定 ServiceNow 連線](servicenow-configuring-connections.md) + [從 ServiceNow 實體中讀取](servicenow-reading-from-entities.md) + [ServiceNow 連線選項](servicenow-connection-options.md) + [ServiceNow 連接器的限制和備註](servicenow-connector-limitations.md) # AWS Glue 支援 ServiceNow AWS Glue 支援 ServiceNow，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 ServiceNow 查詢資料。 **支援作為目標？** 否。 **支援的 ServiceNow API 版本** 支援以下 ServiceNow API 版本： +   v2 如需特定版本的實體支援，請參閱「來源的支援實體」。 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 ServiceNow 您必須先符合下列要求，才能使用 從 ServiceNow AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個帶有電子郵件和密碼的 ServiceNow 帳戶。如需詳細資訊，請參閱[建立 ServiceNow 帳戶](#servicenow-configuring-creating-servicenow-account)。 + 您的 ServiceNow 帳戶已啟用 API 存取。所有 ServiceNow API 的使用皆免費。 如果您符合這些要求，就可以 AWS Glue 連線到您的 ServiceNow 帳戶。 ## 建立 ServiceNow 帳戶 若要建立 ServiceNow 帳戶： 1. 導覽至 servicenow.com 上的註冊頁面，輸入您的詳細資訊，然後按一下**繼續**。 1. 當您在註冊的郵件中收到驗證碼時，請輸入該代碼，然後選擇**驗證**。 1. 設定多重要素驗證或跳過此操作。 已建立帳戶，ServiceNow 會顯示您的設定檔。 ## 建立 ServiceNow 開發人員執行個體 登入 ServiceNow 後請求開發人員執行個體。 1. 在 [ServiceNow 登入頁面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)中，輸入您的帳戶憑證。 1. 選擇 **ServiceNow Developer Program**。 ![\[\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/servicenow-dev-program.png) 1. 選擇右上角的**請求執行個體**。 1. 輸入您的任務責任。表明您同意使用條款，然後選擇**完成設定**。 1. 建立執行個體後，請記下您的執行個體 URL 和憑證。 ## 擷取 BasicAuth 憑證 若要擷取免費帳戶的基本身分驗證憑證： 1. 在 [ServiceNow 登入頁面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)中，輸入您的帳戶憑證。 1. 在首頁上，選擇編輯設定檔區段 (右上角)，然後選擇**管理執行個體密碼**。 1. 擷取登入憑證，例如使用者名稱、密碼和執行個體 URL。 **注意** 如果為帳戶啟用 MFA，請將 MFA 字符附加到基本身分驗證的使用者密碼結尾：: 如需詳細資訊，請參閱 ServiceNow 文件中的[建置應用程式](https://docs.servicenow.com/bundle/xanadu-application-development/page/build/custom-application/concept/build-applications.html)。 ## 建立 OAuth 2.0 憑證 若要在 ServiceNow 連接器中使用 OAuth2.0，您需要建立傳入用戶端以產生用戶端 ID 和用戶端機密： 1. 在 [ServiceNow 登入頁面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)中，輸入您的帳戶憑證。 1. 在首頁上選擇**開始建置**。 1. 在 App Engine Studio 頁面中，搜尋**應用程式登錄檔**。 1. 選擇右上角的**新增**。 1. 選擇**為外部用戶端建立 OAuth API 端點**選項。 1. 對 OAuth 組態進行任何必要的變更，然後選擇**更新**。 重新導向 URL 的範例：https://us-east-1.console.aws.amazon.com/gluestudio/oauth 1. 選取新建立的 OAuth 用戶端應用程式，以擷取用戶端 ID 和用戶端機密。 1. 儲存用戶端 ID 和用戶端機密以供進一步處理。 若要在非生產開發人員帳戶中設定 OAuth： 1. 使用 ServiceNow 文件中的[建立身分驗證設定檔](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/authentication/task/create-an-authentication-profile.html)主題來建立身分驗證設定檔。 1. 在 OAuth 的身分驗證設定檔中，將**類型**選取為 OAuth，然後選取上述建立的傳入用戶端來設定 **OAuth 實體**。 1. 如果有多個用戶端，則需要建立多個身分驗證設定檔，以在身分驗證設定檔中設定所需的 OAuth 實體。 1. 如果未設定，請建立 REST API 存取政策，以授予對 TABLE API 的存取權。請參閱[建立 REST API 存取政策](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/authentication/task/create-api-access-policy.html)。 # 設定 ServiceNow 連線 授予類型決定 如何與 ServiceNow AWS Glue 通訊，以請求存取您的資料。您的選擇會影響您在建立連線之前必須滿足的要求。ServiceNow 僅支援 OAuth 2.0 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 AWS Glue 主控台會將使用者重新導向至 ServiceNow，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 ServiceNow 執行個體。 + 使用者仍然可以選擇在 ServiceNow 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 ServiceNow，以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 ServiceNow 文件，請參閱[設定 OAuth](https://docs.servicenow.com/bundle/vancouver-platform-security/page/administer/security/task/t_SettingUpOAuth.html)。 若要設定 ServiceNow 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於基本身分驗證，機密應包含以 `USERNAME` 和 `PASSWORD` 作為金鑰的連線應用程式消費者機密。 1. 對於授權碼授予類型，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須在 AWS Glue中為每個連線建立機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 ServiceNow。 1. 提供您要連線之 ServiceNow 執行個體的 INSTANCE\$1URL。 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. 在 AWS Glue中選取您要用於此連線的**身分驗證類型**。 1. 基本驗證：此身分驗證類型適用於自動化案例，因為它允許 預先使用具有 ServiceNow 執行個體中特定使用者許可的使用者名稱和密碼。 AWS Glue 能夠使用使用者名稱和密碼來驗證 ServiceNow APIs。只有在基本驗證時，才鍵入下列輸入：`Username` 和 `Password`。 1. OAuth2：僅在 OAuth2 的情況下鍵入下列輸入：`ClientId`、`ClientSecret`、`Authorization URL`、`Authorization Token URL`。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 ServiceNow 實體中讀取 **必要條件** 您想要從中讀取的 ServiceNow Tables 物件。您將需要物件名稱，例如 pa\$1bucket 或 incident。 **範例**： ``` servicenow_read = glueContext.create_dynamic_frame.from_options( connection_type="servicenow", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "pa_buckets", "API_VERSION": "v2" "instanceUrl": "https://.service-now.com" } ) ``` **ServiceNow 實體和欄位詳細資訊**： 對於下列實體，ServiceNow 會提供端點來動態擷取中繼資料，以便在每個實體的資料類型層級擷取運算子支援。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/servicenow-reading-from-entities.html) **注意** 在連接器的回應中，Struct 資料類型會轉換為 String 資料類型。 **注意** `DML_STATUS` 是用於追蹤 CREATED/UPDATED 記錄的額外使用者定義的屬性。 ## 分區查詢 **欄位型分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/servicenow-reading-from-entities.html) + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-01-30T06:47:51.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 下表說明實體分區欄位支援詳細資訊： 範例： ``` servicenow_read = glueContext.create_dynamic_frame.from_options( connection_type="servicenow", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "pa_buckets", "API_VERSION": "v2", "instanceUrl": "https://.service-now.com" "PARTITION_FIELD": "sys_created_on" "LOWER_BOUND": "2024-01-30T06:47:51.000Z" "UPPER_BOUND": "2024-06-30T06:47:51.000Z" "NUM_PARTITIONS": "10" } ``` **記錄型分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用此參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 在記錄型分區中，會從 ServiceNow API 中查詢存在的記錄總數，並除以提供的 `NUM_PARTITIONS` 數目。然後，每個子查詢都會同時擷取產生的記錄數目。 + `NUM_PARTITIONS`：分區數目。 範例： ``` servicenow_read = glueContext.create_dynamic_frame.from_options( connection_type="servicenow", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "pa_buckets", "API_VERSION": "v2", "instanceUrl": "https://.service-now.com" "NUM_PARTITIONS": "2" } ``` # ServiceNow 連線選項 以下是 ServiceNow 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。ServiceNow 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 ServiceNow Rest API 版本。例如：v1、v2、v3、v4。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。例如：2024-01-30T06:47:51.000Z。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。例如：2024-06-30T06:47:51.000Z。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。例如：10。 + `INSTANCE_URL`(String) - (必要) 格式為 https://.service-now.com 的有效 ServiceNow 執行個體 URL。 + `PAGE_SIZE`(Integer) - 定義查詢記錄的頁面大小。預設頁面大小為 1，000。指定頁面大小時，ServiceNow 僅傳回每個 API 呼叫定義的記錄數，而不是整個資料集。連接器仍會提供記錄總數，並使用指定的頁面大小來處理分頁。如果需要更大的頁面大小，可以選擇任何值，最高可達 10,000，這是允許的最大值。將會忽略超過 10,000 的指定頁面大小。反之，系統會使用允許的頁面大小上限。可新增具有所需值的連線選項 `PAGE_SIZE`，以便在 AWS Glue Studio UI 中指定頁面大小。例如：5000。 # ServiceNow 連接器的限制和備註 以下是 ServiceNow 連接器的限制或備註： + 根據 [SaaS 文件](https://www.servicenow.com/docs/bundle/washingtondc-application-development/page/build/applications/reference/r_GlobalDefaultFields.html)，`sys_created_on`、`sys_updated_on` 和 `sys_mod_count` 是系統產生的欄位。連接器依賴 SaaS API 在回應內文中提供這些欄位。 + 如果 SaaS 未對任何實體產生這些欄位，則不支援以篩選條件為基礎的分區。 + 如果 SaaS API 在回應中未傳回 `sys_created_on` 和 `sys_updated_on` 欄位，則無法計算 `DML_STATUS`。 + 提高讀取效能和效率 + 當使用者未指定 ORDER BY 子句時，ServiceNow 連接器現在會自動依 `sys_id` 欄位以遞增順序排序記錄 (必須存在於中繼資料中)。在這種情況下，將透過新的基於最佳化金鑰集的分頁對記錄進行分頁。 + 如果指定 ORDER BY 子句，則不會使用新的最佳化，而且將使用現有 (使用者定義的基於「排序依據」和「位移限制」的分頁) 方法擷取記錄。 # 在 AWS Glue Studio 中連線至 Slack Slack 是一種企業通訊應用程式，可讓使用者透過各種公有和私有頻道傳送訊息和附件。如果您是 Slack 使用者，您可以 AWS Glue 連線到 Slack 帳戶。然後，您可以在 ETL 任務中使用 Slack 作為資料來源。執行這些任務以在 Slack AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Slack](slack-support.md) + [包含用於建立和使用連線的 API 操作的政策](slack-configuring-iam-permissions.md) + [設定 Slack](slack-configuring.md) + [設定 Slack 連線](slack-configuring-connections.md) + [從 Slack 實體中讀取](slack-reading-from-entities.md) + [Slack 連線選項](slack-connection-options.md) + [限制](slack-limitations.md) + [建立新的 Slack 帳戶並設定用戶端應用程式](slack-new-account-creation.md) # AWS Glue 支援 Slack AWS Glue 支援 Slack，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Slack 查詢資料。 **支援作為目標？** 否。 **支援的 Slack API 版本** Slack API v2。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策描述建立和使用連線所需的 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 Amazon CloudWatch Logs、IAM 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。 + [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接到的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。 # 設定 Slack 您必須先符合下列要求，才能使用 AWS Glue 往返 Slack 傳輸資料： ## 最低需求 + 您必須擁有一個 Slack 帳戶。如需詳細資訊，請參閱[建立新的 Slack 帳戶並設定用戶端應用程式](slack-new-account-creation.md)。 如果您符合這些要求，就可以 AWS Glue 連線到 Slack 帳戶。 # 設定 Slack 連線 Slack 支援 OAuth 2 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。 AWS Glue 主控台會將使用者重新導向至 Slack，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Slack 執行個體。 使用者仍然可以選擇在 Slack 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Slack 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符會在建立 1 小時後過期。可以使用重新整理字符來獲取新的存取字符。 如需有關為授權碼 OAuth 流程建立連線應用程式的詳細資訊，請參閱 [Slack API](https://api.slack.com/quickstart)。 若要設定 Slack 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須在 AWS Glue中建立連線機密。 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**連線類型**時，選取 Slack。 1. 提供 Slack 環境。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Slack 實體中讀取 **先決條件** + 您要從中讀取的 Slack 物件。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 對話 | 是 | 是 | 否 | 是 | 是 | **範例** ``` slack_read = glueContext.create_dynamic_frame.from_options( connection_type="slack", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversations/C058W38R5J8" } ) ``` **Slack 實體和欄位詳細資訊** | 實體 | 欄位 | 資料類型 | 支援的運算子 | | --- | --- | --- | --- | | 對話 | 附件 | 清單 | NA | | 對話 | bot\$1id | String | NA | | 對話 | blocks | 清單 | NA | | 對話 | client\$1msg\$1id | String | NA | | 對話 | is\$1starred | Boolean | NA | | 對話 | last\$1read | String | NA | | 對話 | latest\$1reply | String | NA | | 對話 | 反應 | 清單 | NA | | 對話 | 回應 | 清單 | NA | | 對話 | reply\$1count | Integer | NA | | 對話 | reply\$1users | 清單 | NA | | 對話 | reply\$1users\$1count | Integer | NA | | 對話 | 已訂閱 | Boolean | NA | | 對話 | 子類型 | String | NA | | 對話 | text | String | NA | | 對話 | 團隊 | String | NA | | 對話 | thread\$1ts | String | NA | | 對話 | ts | String | EQUAL\$1TO, BETWEEN, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL\$1TO, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL\$1TO | | 對話 | type | String | NA | | 對話 | user | String | NA | | 對話 | 邀請者 | String | NA | | 對話 | 根 | Struct | NA | | 對話 | is\$1locked | Boolean | NA | | 對話 | files | 清單 | NA | | 對話 | 房間 | Struct | NA | | 對話 | 上傳 | Boolean | NA | | 對話 | display\$1as\$1bot | Boolean | NA | | 對話 | 通道 | String | NA | | 對話 | no\$1notifications | Boolean | NA | | 對話 | permalink | String | NA | | 對話 | pinned\$1to | 清單 | NA | | 對話 | pinned\$1info | Struct | NA | | 對話 | edited | Struct | NA | | 對話 | app\$1id | String | NA | | 對話 | bot\$1profile | Struct | NA | | 對話 | 中繼資料 | Struct | NA | **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值範例：`"2024-07-01T00:00:00.000Z"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示。 | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 對話 | ts | String | **範例** ``` slack_read = glueContext.create_dynamic_frame.from_options( connection_type="slack", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversations/C058W38R5J8", "PARTITION_FIELD": "ts" "LOWER_BOUND": "2022-12-01T00:00:00.000Z" "UPPER_BOUND": "2024-09-23T15:00:00.000Z" "NUM_PARTITIONS": "2" } ) ``` # Slack 連線選項 以下是 Slack 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。支援的實體名稱。範例：`conversations/C058W38R5J8`。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的欄位。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # 限制 以下是 Slack 連接器的限制： + 不支援記錄型分區，因為連接器不提供任何方法來擷取指定對話中的可用記錄 (訊息) 總數。 # 建立新的 Slack 帳戶並設定用戶端應用程式 **建立 Slack 帳戶** 1. 開啟 [Slack 首頁](https://slack.com/intl/en-in/)以註冊帳戶。 1. 選擇**使用電子郵件地址註冊**。輸入電子郵件地址，然後選擇**繼續**。 1. 輸入傳送到您電子郵件地址的 6 個字元代碼，其會將您重新導向至建立工作區或加入現有工作區。 1. 選擇**建立工作區**以建立新工作區。在設定過程中，其將重新引導您回答幾個問題。 + 公司名稱 + 您的姓名 + 透過電子郵件新增同事 + 您的團隊正在做什麼？ (這將是頻道名稱) 1. 填寫這些問題的輸入欄位並繼續。您的帳戶現在已準備好可供使用。 **建立 Slack 開發人員應用程式** 1. 登入您的 Slack 帳戶並登入 Slack 工作區。 1. 從工作區功能表中，選取**工具和設定**，然後選取**管理應用程式**。 1. 從「Slack 應用程式型錄」功能表中，選取**建置**。 1. 在**應用程式**頁面中，選取**建立應用程式**。 1. 在**建立應用程式**頁面中，選取**從頭開始**。 1. 在開啟的**命名應用程式並選擇工作區**對話方塊中，新增應用程式名稱並**選擇要在其中部署應用程式的工作區**。然後選取**建立應用程式**。 1. 記下應用程式憑證中顯示的用戶端 ID 和機密 1. 在「OAuth 與許可」邊欄中，移至「範圍」，然後選擇**新增 OAuth 範圍**。可以將重新導向 URL 新增至您的應用程式組態，以自動產生「新增至 Slack」按鈕或分發您的應用程式。向上捲動至「重新導向 URL」區段，然後選擇**新增重新導向 URL** 並儲存。 1. 然後，捲動至「工作區的 OAuth 字符」區段，然後選擇**安裝至工作區**。 1. 在開啟的對話方塊中，通知您建立的應用程式正在請求存取您要連線之 Slack 工作區的許可，請選取**允許**。 1. 成功完成後，主控台會顯示「工作區的 OAuth 字符」畫面。 1. 從工作區的 OAuth 權杖畫面中，複製並儲存您將用來連線的 OAuth 權杖 AWS Glue 1. 接著，您可以擷取 Slack 團隊 ID。從 Slack 工作區功能表中，選取**工具和設定**，然後選取**管理應用程式**。可以在開啟的頁面 URL 中找到您的團隊 ID。 1. 若要公開分發您的應用程式，可以選擇側邊列中的**管理分發**按鈕來啟用。向下捲動至「與其他工作區共用您的應用程式」區段，然後選擇**移除硬式編碼資訊**。提供同意，然後選擇**作用中的公有分發**。 1. 您的應用程式現在已公開分發。若要存取實體 API，必須將應用程式新增至使用者想要存取的每個工作區頻道。 1. 登入 slack 帳戶並開啟需要存取其頻道的工作區。 1. 在工作區中，開啟應用程式想要存取的頻道，然後選擇頻道標題。從快顯視窗中選取**整合**索引標籤，然後新增應用程式。透過這種方式，應用程式會與頻道整合，以存取其 API。 OAuth 2.0 用戶端 ID 必須擁有一個或多個已授權的重新導向 URL。重新導向 URL 的格式如下： **注意** Appflow URLs 可能會變更 AWS Glue 平台的重新導向後 URLs。用戶端 ID 和用戶端機密來自 OAuth 2.0 用戶端 ID 的設定。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/slack-new-account-creation.html) # 連線至 Smartsheet Smartsheet 是一種工作管理和協同合作 SaaS 產品。基本上，Smartsheet 可讓使用者使用類似試算表的物件來建立、儲存和利用業務資料。 **Topics** + [AWS Glue 支援 Smartsheet](smartsheet-support.md) + [包含用於建立和使用連線的 API 操作的政策](smartsheet-configuring-iam-permissions.md) + [設定 Smartsheet](smartsheet-configuring.md) + [設定 Smartsheet 連線](smartsheet-configuring-connections.md) + [從 Smartsheet 實體中讀取](smartsheet-reading-from-entities.md) + [Smartsheet 連線選項](smartsheet-connection-options.md) + [建立 Smartsheet 帳戶](smartsheet-create-account.md) + [限制](smartsheet-connector-limitations.md) # AWS Glue 支援 Smartsheet AWS Glue 支援智慧資料表，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Smartsheet 查詢資料。 **支援作為目標？** 否。 **支援的 Smartsheet API 版本** v2.0 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 主控台的使用者。 # 設定 Smartsheet 您必須先符合下列要求，才能使用 從 Smartsheet AWS Glue 傳輸： ## 最低需求 + 您擁有一個帶有電子郵件和密碼的 Smartsheet 帳戶。如需有關建立帳戶的詳細資訊，請參閱[建立 Smartsheet 帳戶](smartsheet-create-account.md)。 + 您的 Smartsheet 帳戶具有包含有效授權的 API 存取。 + 您的 Smartsheet 帳戶具有適用於 `Sheets` 實體的**專業定價**計劃，以及適用於 `Events` 實體的帶事件報告附加元件的企業定價計劃。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Smartsheet 帳戶。對於一般連線，不需要在 Smartsheet 中執行任何其他操作。 # 設定 Smartsheet 連線 Smartsheet 支援 OAuth2 的 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」`OAuth`，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。使用者可以選擇在 Smartsheet 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Smartsheet 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 如需為 AUTHORIZATION\$1CODE OAuth 流程建立連線應用程式的公有 Smartsheet 文件，請參閱 [Smartsheet API](https://smartsheet.redoc.ly/#section/OAuth-Walkthrough)。 若要設定 Smartsheet 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 **注意** 必須在 AWS Glue中為每個連線建立機密。 1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections 下建立連線**： 1. 選取**連線類型**時，請選取 Smartsheet。 1. 提供您要連線之 Smartsheet 的 `instanceUrl`。 1. 選取 AWS Glue 可擔任的 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`。 # 從 Smartsheet 實體中讀取 **先決條件** 您要從中讀取的 `Smartsheet` 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 清單工作表 | 是 | 是 | 否 | 是 | 否 | | 資料列中繼資料 | 是 | 是 | 否 | 是 | 否 | | 工作表中繼資料 | 否 | 否 | 否 | 是 | 否 | | 工作表資料 | 是 | 是 | 是 | 是 | 否 | | 事件 | 是 | 是 | 否 | 是 | 否 | **範例** ``` Smartsheet_read = glueContext.create_dynamic_frame.from_options( connection_type="smartsheet", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "list-sheets", "API_VERSION": "2.0", "INSTANCE_URL": "https://api.smartsheet.com" }) ``` **Smartsheet 實體和欄位詳細資訊** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/smartsheet-reading-from-entities.html) **具有動態中繼資料的實體：** 對於下列實體，Smartsheet 提供端點以動態擷取中繼資料，允許在資料類型層級擷取運算子支援。 | 實體 | 資料類型 | 支援的運算子 | | --- | --- | --- | | 工作表資料 | String | NA | | 工作表資料 | Long | "=" | | 工作表資料 | Integer | NA | | 工作表資料 | DateTime | > | **範例** ``` Smartsheet_read = glueContext.create_dynamic_frame.from_options( connection_type="smartsheet", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "list-sheets", "API_VERSION": "2.0", "INSTANCE_URL": "https://api.smartsheet.com" } ``` # Smartsheet 連線選項 以下是 Smartsheet 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Smartsheet 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Smartsheet Rest API 版本。例如，V2.0。 + `INSTANCE_URL`(String) – (必要) 用於讀取。Smartsheet 執行個體 URL。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Smartsheet 帳戶 1. 存取 [Smartsheet 註冊頁面](https://app.smartsheet.com/home)以註冊 Smartsheet 帳戶。 1. 選擇**建立帳戶**以建立新帳戶，或使用已註冊的 Google、Microsoft 或 Apple 帳戶登入。 1. 出現提示時，輸入工作電子郵件地址。 1. 選擇**繼續**，並視需要驗證您的身分。 1. 從 Smartsheet 中開啟確認電子郵件，然後選擇確認連結以驗證您的帳戶。 根據預設，您將會訂閱試驗計畫。 1. 在左下角，選擇**帳戶**圖示，然後選擇**新增授權/升級**以升級定價計劃。 **注意** 這是存取**事件報告**所必需的，其是**企業**計劃中的附加元件。 1. 在**企業**計劃下，選擇**聯絡我們**，向支援團隊請求帳戶升級。 1. 在支援請求表單中，提供必要的詳細資訊以及您升級該計劃的需求。 如此即完成 **Enterprise** 計劃升級。 **建立 `OAuth2.0` 憑證** 1. 升級帳戶的定價計劃以取得**開發人員工具**的存取權後，請存取 [Smartsheet 開發人員](https://developers.smartsheet.com/)。 您會收到啟用電子郵件。 1. 從 Smartsheet 中打開啟用電子郵件，然後選擇啟用連結，在您的帳戶中啟用開發人員工具。 開發人員工具可讓您建立應用程式。 1. 開啟 Smartsheet 帳戶的首頁，然後選擇**帳戶**以檢查存取權。 1. 從服務清單中選擇**開發人員工具**，然後輸入**開發人員設定檔**詳細資訊。 1. 選擇**建立新應用程式**。 1. 在應用程式註冊表單中輸入以下詳細資訊： + **名稱** – 應用程式的名稱。 + **說明** – 應用程式的說明。 + **URL** – 可讓您啟動應用程式的 URL 或登陸頁面的 URL。 + **聯絡/支援** – 支援團隊的聯絡資訊。 + **重新導向 URL** – 在應用程式中將接收 [OAuth 2.0](https://.console.aws.amazon.com/appflow/oauth) 憑證的 URL (也稱為回呼 URL)。 1. 選擇**儲存**。 Smartsheet 會將用戶端 ID 和用戶端機密指派給您的應用程式。記錄這些值以進行後續步驟。也可以稍後在**開發人員工具**區段中再次查詢。 # 限制 Smartsheet 不支援欄位型或記錄型分區。 # 在 AWS Glue Studio 中連線至 Snapchat Ads Snapchat 是由 Snap Inc. (最初為 Snapchat Inc.) 開發的多媒體即時傳訊應用程式和服務。Snapchat 的其中一個主要功能是，在收件人無法存取圖片和訊息之前，通常只能短暫使用圖片和訊息。Snapchat Marketing 是企業可以付費為 Snapchat 使用者提供服務的貼文。 **Topics** + [AWS Glue 支援 Snapchat 廣告](snapchat-ads-support.md) + [包含用於建立和使用連線的 API 操作的政策](snapchat-ads-configuring-iam-permissions.md) + [設定 Snapchat Ads](snapchat-ads-configuring.md) + [設定 Snapchat Ads 連線](snapchat-ads-configuring-connections.md) + [從 Snapchat Ads 實體中讀取](snapchat-ads-reading-from-entities.md) + [Snapchat Ads 連線選項](snapchat-ads-connection-options.md) + [建立 Snapchat Ad 帳戶並設定用戶端應用程式](connecting-to-data-snapchat-ads-new-account.md) + [在 Snapchat Ads 帳戶中建立應用程式](connecting-to-data-snapchat-ads-managed-client-application.md) # AWS Glue 支援 Snapchat 廣告 AWS Glue 支援 Snapchat 廣告，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Snapchat Ads 查詢資料。 **支援作為目標？** 否。 **支援的 Snapchat Ads API 版本** v1。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策說明建立和使用 連線所需的 AWS 許可。如果您要建立新角色，請建立包含下列項目的政策： ------ #### [ 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 Amazon CloudWatch Logs、IAM 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。 + [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接到的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。 # 設定 Snapchat Ads 您必須先符合下列要求，才能使用 從 Snapchat Ads AWS Glue 傳輸： ## 最低需求 + 您擁有一個 Snapchat Ads 帳戶。如需建立帳戶的詳細資訊，請參閱[建立 Snapchat Ad 帳戶並設定用戶端應用程式](connecting-to-data-snapchat-ads-new-account.md)。 + 您已在 Snapchat Ads 帳戶中建立 OAuth2 應用程式。此整合提供了 AWS Glue 在對您的帳戶進行驗證呼叫時用於安全存取資料的憑證。如需詳細資訊，請參閱[在 Snapchat Ads 帳戶中建立應用程式](connecting-to-data-snapchat-ads-managed-client-application.md)。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Snapchat Ads 帳戶。在 Snapchat Ads 中，連線的應用程式是一種架構 AWS Glue，可授權外部應用程式存取您的 Snapchat Ads 資料。 # 設定 Snapchat Ads 連線 Snapchat Ads 僅支援 `AUTHORIZATION_CODE` 授權類型。 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。根據預設，建立連線的使用者可能需要 AWS Glue 擁有的連線應用程式 （受AWS Glue 管用戶端應用程式），除了其 Snapchat Ads 執行個體 URL 之外，不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Snapchat Ads，其中使用者必須登入 AWS Glue ，並允許請求的許可存取其 Snapchat Ads 執行個體。 使用者仍然可以選擇在 Snapchat Ads 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Snapchat Ads 以登入並授權 AWS Glue 存取其資源。 此授權類型會產生重新整理字符和存取字符。存取字符會在建立 1 小時後過期。可以使用重新整理字符來獲取新的存取字符。 如需有關為授權碼 OAuth 流程建立連線應用程式的詳細資訊，請參閱 [Ads API](https://marketingapi.snapchat.com/docs/#authentication)。 若要設定 Snapchat Ads 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Snapchat Ads。 1. 提供 Snapchat Ads 環境。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Snapchat Ads 實體中讀取 **先決條件** + 您想要從中讀取的 Snapchat Ads 物件。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 組織 | 否 | 否 | 否 | 是 | 否 | | 廣告帳戶 | 否 | 否 | 否 | 是 | 否 | | 創意 | 否 | 否 | 否 | 是 | 否 | | 媒體 | 否 | 否 | 否 | 是 | 否 | | 行銷活動 | 是 | 否 | 否 | 是 | 否 | | 廣告帳戶下的廣告 | 是 | 否 | 否 | 是 | 否 | | 行銷活動下的廣告 | 否 | 否 | 否 | 是 | 否 | | 廣告小組 | 是 | 否 | 否 | 是 | 否 | | 區段 | 否 | 否 | 否 | 是 | 否 | **範例** ``` snapchatads_read = glueContext.create_dynamic_frame.from_options( connection_type="snapchatAds", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "organization", "API_VERSION": "v1" } ) ``` **Snapchat Ads 實體和欄位詳細資訊** Snapchat Ads 會在選取的實體下動態載入可用欄位。視欄位的資料類型而定，其支援下列篩選條件運算子。 | 欄位資料類型 | 支援的篩選條件運算子 | | --- | --- | | Boolean | = | **分區查詢** + 欄位型分區：不支援。 + 記錄型分區：不支援。 # Snapchat Ads 連線選項 以下是 Snapchat Ads 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Snapchat Ads 實體的名稱。範例：` campaign `。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Snapchat Ads Rest API 版本。該值將為 v1，因為 Snapchat Ads 目前僅支援 v1 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為所選實體選取的資料欄的以逗號分隔的資料欄清單。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # 建立 Snapchat Ad 帳戶並設定用戶端應用程式 **Topics** + [註冊 Snapchat Ads](#snapchat-ads-sign-up) + [建立 Snapchat Ad 帳戶的步驟](#snapchat-ads-create-ad-account) ## 註冊 Snapchat Ads **若要註冊 Snapchat Ads，請執行以下操作：** 1. 導覽至 [Snapchat Ads Manager](https://ads.snapchat.com/)。選擇 **Snapchat 新手？**旁邊的**註冊**。 1. 在**建立帳戶**畫面上，依照提示輸入您的公司名稱、電子郵件、密碼等。選擇**下一步**。 1. 在**建立設定檔**畫面上，輸入使用者名稱和網站 (選用) 的值，然後選擇**建立帳戶**。這可讓您選擇在**編輯設定檔**畫面上新增設定檔相片和簡歷。選擇**確認**。 1. 在**商業資訊**畫面上，填寫國家/地區、貨幣、電話號碼、GSTIN 等必要欄位，然後選擇**下一步**來完成帳戶建立程序。 ## 建立 Snapchat Ad 帳戶的步驟 **若要建立 Snapchat Ad 帳戶，請執行以下操作：** 1. 登入 **Ads Manager**。接著，按一下頂角的導覽，然後選取**廣告帳戶**。 1. 選擇 **\$1 新建廣告帳戶**。輸入您的廣告商詳細資訊： + 選取您是否為代表廣告商購買廣告的機構。如果您選取「是」，而您的廣告使用的目標參數可能包括年齡、性別或郵遞區號層級目標，則可能會被拒絕。最低年齡目標可能適用於 21 歲以下人士。 + 選取您的廣告帳戶是否投放在住房、信貸或招聘廣告。如果您選取「是」，而您的廣告使用的目標參數可能包括年齡、性別或郵遞區號層級目標，則可能會被拒絕。最低年齡目標可能適用於 21 歲以下人士。 + 選取您是否將使用廣告帳戶進行政治廣告。如果您正在投放政治廣告，請輸入贊助該廣告的政治組織或倡議團體。如果您未準確輸入政治組織，您的廣告可能會被拒絕。提交廣告之前，您還需要填寫必要連結的「政治廣告審查表單」。 1. 選擇**帳戶詳細資訊**，並填寫您的廣告帳戶資訊： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/connecting-to-data-snapchat-ads-new-account.html) 1. 選擇**建立帳戶**。系統將會建立您的廣告帳戶，您可以在 Ads Manager 的「廣告帳戶」部分中找到其。若要開始啟動廣告，您需要輸入付款方式。您也可以將成員新增至您的廣告帳戶。 1. 選取您要使用現有的付款還是建立新的付款。然後，選擇**儲存付款方式**。 1. 選取[您邀請加入企業的任何成員](https://businesshelp.snapchat.com/s/article/manage-members?language=en_US)，以新增至廣告帳戶。如需可指派的角色和許可的詳細資訊，請參閱[角色和許可概觀](https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US)。然後，新增的成員將能夠登入 Ads Manager 並存取此廣告帳戶。完成後，儲存您的成員。 如需廣告帳戶的詳細資訊，請參閱 [https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US](https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US)https://businesshelp.snapchat.com/s/article/roles-permissions?language=en\$1US # 在 Snapchat Ads 帳戶中建立應用程式 若要啟用 Snapchat 的行銷 API 的存取權，請確定您已設定企業帳戶。然後遵循下面的步驟： 1. 登入 Ads Manager。接著，選擇左上角的功能表，選取**商業儀表板**，然後選取**商業詳細資訊**。 1. 選擇 **\$1OAuth 應用程式**。 1. 輸入您的應用程式名稱，並將下列 URL 新增為 Snap 重新導向 URI `https://.console.aws.amazon.com/gluestudio/oauth`。例如，如果使用 us-west-1 區域，URL 將為 `https://us-west-1.console.aws.amazon.com/gluestudio/oauth) and choose Create OAuth App`。選擇**建立 OAuth 應用程式**。 1. 將會顯示您的應用程式憑證 (用戶端 ID 和用戶端機密)。請予以儲存，因為建立連線時需要使用這些憑證。 # 在 AWS Glue Studio 中連線至 Snowflake **注意** 您可以使用 AWS Glue for Spark 從 AWS Glue 4.0 及更新版本中的 Snowflake 讀取和寫入資料表。若要使用 AWS Glue 任務以程式設計方式設定 Snowflake 連線，請參閱[Redshift 連線](aws-glue-programming-etl-connect-redshift-home.md)。 AWS Glue 提供 Snowflake 的內建支援。AWS Glue Studio 提供視覺化介面來連線至 Snowflake、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行這些任務。 AWS Glue Studio 會為 Snowflake 建立統一連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 **Topics** + [建立 Snowflake 連線](creating-snowflake-connection.md) + [建立 Snowflake 來源節點](creating-snowflake-source-node.md) + [建立 Snowflake 目標節點](creating-snowflake-target-node.md) + [進階選項](#creating-snowflake-connection-advanced-options) # 建立 Snowflake 連線 **注意** 統一連線 (連線 v2) 會標準化所有連線，以使用 `USERNAME`、`PASSWORD` 金鑰作為基本驗證憑證。您仍然可以透過包含 `sfUser`、`sfPassword` 的機密的 API 建立 v1 連線。 在 中新增**資料來源 - Snowflake** 節點時AWS Glue Studio，您可以選擇現有的 AWS Glue Snowflake 連線或建立新的連線。您必須選擇 `SNOWFLAKE` 類型連線，而不是設定為連線至 Snowflake 的 `JDBC` 類型連線。請依照下列程序建立 AWS Glue Snowflake 連線： **建立 Snowflake 連線** 1. 在 Snowflake 中產生一個使用者、*snowflakeUser* 和密碼 *snowflakePassword*。 1. 確定此使用者將與哪個 Snowflake 倉儲 (*snowflakeWarehouse*) 互動。可將其設定為 Snowflake 中 *snowflakeUser* 的 `DEFAULT_WAREHOUSE`，或是記住此資訊以供下一步使用。 1. 在 中 AWS Secrets Manager，使用您的 Snowflake 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html#create_secret_cli)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 選取**鍵值對**時，使用索引鍵 `sfUser` 為 *snowflakeUser* 建立鍵值對。 + 選取**鍵值對**時，使用索引鍵 `sfPassword` 為 *snowflakePassword* 建立鍵值對。 + 選取**鍵值對**時，使用索引鍵 `sfWarehouse` 為 *snowflakeWarehouse* 建立鍵值對。如果 Snowflake 中設定了預設值，則不需要此操作。 1. 在 AWS Glue 資料目錄中，依照[新增連線中的步驟建立 AWS Glue 連線](https://docs.aws.amazon.com//glue/latest/dg/console-connections.html)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Snowflake。 + 選取 **Snowflake URL** 時，請提供 Snowflake 執行個體的主機名稱。URL 將在表單 `account_identifier.snowflakecomputing.com` 中使用 hostname。 + 選取 **AWS 機密**時，請提供 *secretName*。 # 建立 Snowflake 來源節點 ## 需要的許可 AWS Glue Studio 使用 Snowflake 資料來源的任務需要額外的許可。如需有關如何向 ETL 任務新增許可的詳細資訊，請參閱 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。 `SNOWFLAKE` AWS Glue 連線使用 AWS Secrets Manager 秘密來提供登入資料資訊。您在 中的任務和資料預覽角色 AWS Glue Studio 必須具有讀取此秘密的許可。 ## 新增 Snowflake 資料來源 **先決條件：** + Snowflake 登入資料的 AWS Secrets Manager 秘密 + Snowflake 類型 AWS Glue Data Catalog 連線 **若要新增**資料來源 – Snowflake** 節點：** 1. 選擇 Snowflake 資料來源的連線。假設連線已存在，您可以從現有的連線中進行選擇。如果您需要建立連線，請選擇**建立 Snowflake 連線**。如需詳細資訊，請參閱 [Overview of using connectors and connections ](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。隨即會顯示連線的相關資訊，包括 URL、安全群組、子網路、可用區域、說明，以及建立的 (UTC) 和上次更新的 (UTC) 時間戳記。 1. 選擇 Snowflake 來源選項： + **選擇單一資料表**：此資料表包含您要從單一 Snowflake 資料表存取的資料。 + **輸入自訂查詢**：可讓您根據自訂查詢從多個 Snowflake 資料表存取資料集。 1. 如果您選擇單一資料表，請輸入 Snowflake 結構描述的名稱。 或者，選擇**輸入自訂查詢**。選擇此選項可從多個 Snowflake 資料表存取自訂資料集。當您選擇此選項時，請輸入 Snowflake 查詢。 1. 在**效能和安全性**選項 (選用) 中， + **啟用查詢下推**：選擇是否要將工作卸載至 Snowflake 執行個體。 1. 在**自訂 Snowflake 屬性** (選用) 中，根據需要輸入參數和值。 # 建立 Snowflake 目標節點 ## 需要的許可 AWS Glue Studio 使用 Snowflake 資料來源的任務需要額外的許可。如需有關如何向 ETL 任務新增許可的詳細資訊，請參閱 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。 `SNOWFLAKE` AWS Glue 連線使用 AWS Secrets Manager 秘密來提供登入資料資訊。您在 中的任務和資料預覽角色 AWS Glue Studio 必須具有讀取此秘密的許可。 ## 新增 Snowflake 資料目標 **若要建立 Snowflake 目標節點：** 1. 選擇現有的 Snowflake 資料表作為目標，或輸入新的資料表名稱。 1. 當您使用**資料目標 - Snowflake** 目標節點時，您可以從下列選項中進行選擇： + **附加**：如果資料表已存在，請將所有新資料以插入方式傾印到資料表中。如果資料表不存在，請建立資料表，然後插入所有新資料。 + **合併**：AWS Glue 會根據您指定的條件，將資料更新或附加至目標資料表。 選擇選項： + **選擇索引鍵和簡單動作**：選擇要用作來源資料與目標資料集之間相符索引鍵的資料欄。 符合時指定下列選項： + 使用來源中的資料更新目標資料集中的記錄。 + 刪除目標資料集中的記錄。 不符合時指定下列選項： + 將來源資料作為新列插入目標資料集。 + 什麼都不做。 + **輸入自訂 MERGE 陳述式**：然後您可以選擇**驗證 Merge 陳述式**，以驗證陳述式是有效還是無效。 + **截斷**：如果資料表已存在，請先清除目標資料表的內容來截斷資料表資料。如果截斷成功，則插入所有資料。如果資料表不存在，請建立資料表並插入所有資料。如果截斷未成功，則操作將會失敗。 + **刪除**：如果資料表已存在，請刪除資料表中繼資料和資料。如果刪除成功，則插入所有資料。如果資料表不存在，請建立資料表並插入所有資料。如果刪除未成功，則操作將會失敗。 ## 進階選項 請參閱 AWS Glue 開發人員指南中的 [ Snowflake 連線](https://docs.aws.amazon.com//glue/latest/dg/aws-glue-programming-etl-connect-snowflake-home.html)。 # 在 AWS Glue Studio 中連線至 Stripe Stripe 是一個面向企業的線上付款處理和信用卡處理平台。Stripe 平台可讓企業接受線上付款、為電子商務建立訂閱 (經常性計費)，以及設定銀行帳戶以接收付款。Stripe 也支援多方付款，可讓企業設定其市場，並允許收集付款，然後透過「連線」帳戶付款給賣方或服務供應商。 **Topics** + [AWS Glue 支援 Stripe](stripe-support.md) + [包含用於建立和使用連線的 API 操作的政策](stripe-configuring-iam-permissions.md) + [設定 Stripe](stripe-configuring.md) + [設定 Stripe 連線](stripe-configuring-connections.md) + [從 Stripe 實體中讀取](stripe-reading-from-entities.md) + [Stripe 連線選項](stripe-connection-options.md) + [限制](stripe-limitations.md) + [建立新的 Stripe 帳戶並設定用戶端應用程式](stripe-new-account-creation.md) # AWS Glue 支援 Stripe AWS Glue 支援 Stripe，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Stripe 查詢資料。 **支援作為目標？** 否。 **支援的 Slack API 版本** v1。 # 包含用於建立和使用連線的 API 操作的政策 下列範例政策描述建立和使用連線所需的 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 Amazon CloudWatch Logs、IAM 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。 + [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接到的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。 # 設定 Stripe 您必須先符合下列要求，才能使用 從 Stripe AWS Glue 傳輸資料： ## 最低需求 + 必須擁有一個帶有電子郵件和密碼的 Stripe 帳戶。如需詳細資訊，請參閱[建立新的 Stripe 帳戶並設定用戶端應用程式](stripe-new-account-creation.md)。 + 您的 Stripe 帳戶已啟用 API 存取。所有 Stripe API 的使用皆免費。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Stripe 帳戶。 # 設定 Stripe 連線 Stripe 支援自訂身分驗證。如需產生自訂授權所需 API 金鑰的詳細資訊，請參閱 [STRIPE REST API 文件](https://docs.stripe.com/api/authentication)。 若要設定 Stripe 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密。必須為 AWS Glue中的每個連線建立機密。 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，選取 Stripe。 1. 選取 AWS Glue 可以擔任並具有下列動作許可的 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`。 # 從 Stripe 實體中讀取 **先決條件** + 您要從中讀取的 Stripe 物件。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 餘額 | 否 | 否 | 否 | 是 | 否 | | 餘額交易 | 是 | 是 | 否 | 是 | 是 | | 費用 | 是 | 是 | 否 | 是 | 是 | | 爭論 | 是 | 是 | 否 | 是 | 是 | | 檔案連結 | 是 | 是 | 否 | 是 | 是 | | PaymentIntents | 是 | 是 | 否 | 是 | 是 | | SetupIntents | 是 | 是 | 否 | 是 | 是 | | 支出 | 是 | 是 | 否 | 是 | 是 | | 退款 | 是 | 是 | 否 | 是 | 是 | | 產品 | 是 | 是 | 否 | 是 | 是 | | 價格 | 是 | 是 | 否 | 是 | 是 | | 優惠券 | 是 | 是 | 否 | 是 | 是 | | 促銷代碼 | 是 | 是 | 否 | 是 | 是 | | 稅務代碼 | 否 | 是 | 否 | 是 | 否 | | 稅率 | 是 | 是 | 否 | 是 | 是 | | 運費 | 是 | 是 | 否 | 是 | 是 | | 工作階段 | 是 | 是 | 否 | 是 | 是 | | 貸記通知單 | 是 | 是 | 否 | 是 | 是 | | 客戶 | 是 | 是 | 否 | 是 | 是 | | 發票 | 是 | 是 | 否 | 是 | 是 | | 發票項目 | 是 | 是 | 否 | 是 | 否 | | 計劃 | 是 | 是 | 否 | 是 | 是 | | 報價 | 是 | 是 | 否 | 是 | 否 | | Subscriptions | 是 | 是 | 否 | 是 | | | 訂閱項目 | 否 | 是 | 否 | 是 | 否 | | 訂閱排程 | 是 | 是 | 否 | 是 | 是 | | 帳戶 | 否 | 是 | 否 | 是 | 是 | | 應用程式費用 | 是 | 是 | 否 | 是 | 是 | | 國家/地區規格 | 否 | 是 | 否 | 是 | 否 | | 轉接 | 是 | 是 | 否 | 是 | 是 | | 早期詐騙警告 | 是 | 是 | 否 | 是 | 是 | | 報告類型 | 否 | 否 | 否 | 是 | 否 | **範例** ``` stripe_read = glueContext.create_dynamic_frame.from_options( connection_type="stripe", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1" } ) ``` **Stripe 實體和欄位詳細資訊** | 實體 | 欄位 | 資料類型 | 支援的運算子 | | --- | --- | --- | --- | | 餘額 | | | | | | 有用 | 清單 | | | | connect\$1reserved | 清單 | | | | 待定 | 清單 | | | | livemode | Boolean | | | | object | String | | | | instant\$1available | 清單 | | | | issuing | Struct | | | 餘額交易 | | | | | | id | String | | | | object | String | | | | amount | Integer | | | | available\$1on | DateTime | =, >=, <=,<,> | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | 描述 | String | | | | exchange\$1rate | BigDecimal | | | | fee | Integer | | | | fee\$1details | 清單 | | | | net | Integer | | | | report\$1category | String | | | | source | String | = | | | status | String | | | | type | String | = | | | cross\$1border\$1classification | String | | | 費用 | | | | | | id | String | | | | object | String | | | | amount | Integer | =, <, > | | | amount\$1captured | Integer | | | | amount\$1refunded | Integer | | | | 應用程式 | String | | | | application\$1fee | String | | | | application\$1fee\$1amount | Integer | | | | balance\$1transaction | String | | | | billing\$1details | Struct | | | | calculated\$1statement\$1descriptor | String | | | | captured | Boolean | | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | customer | String | = | | | 描述 | String | | | | 目的地 | String | | | | dispute | String | | | | disputed | Boolean | = | | | failure\$1balance\$1transaction | String | | | | failure\$1code | String | | | | failure\$1message | String | | | | fraud\$1details | Struct | | | | 發票 | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | on\$1behalf\$1of | String | | | | order | String | | | | outcome | Struct | | | | paid | Boolean | | | | payment\$1intent | String | = | | | payment\$1method | String | | | | payment\$1method\$1details | Struct | | | | receipt\$1email | String | | | | receipt\$1number | String | | | | receipt\$1url | String | | | | refunded | Boolean | = | | | refunds | Struct | | | | review | String | | | | shipping | Struct | | | | source | Struct | | | | source\$1transfer | String | | | | statement\$1descriptor | String | | | | statement\$1descriptor\$1suffix | String | | | | status | String | | | | 傳輸 | String | | | | transfer\$1data | Struct | | | | transfer\$1group | String | = | | 爭論 | | | | | | id | String | | | | object | String | | | | amount | Integer | =, <, > | | | balance\$1transaction | String | | | | balance\$1transactions | 清單 | | | | charge | String | = | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | evidence | Struct | | | | evidence\$1details | Struct | | | | is\$1charge\$1refundable | Boolean | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | payment\$1intent | String | = | | | reason | String | = | | | status | String | | | | payment\$1method\$1details | Struct | | | 檔案連結 | | | | | | id | String | | | | object | String | | | | 已建立 | DateTime | =, >=, <=,<,> | | | expired | Boolean | = | | | expires\$1at | DateTime | | | | file | String | = | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | url | String | | | PaymentIntents | | | | | | id | String | | | | object | String | | | | amount | Integer | | | | amount\$1capturable | Integer | | | | amount\$1details | Struct | | | | amount\$1received | Integer | | | | 應用程式 | String | | | | application\$1fee\$1amount | Integer | | | | auto\$1payment\$1methods | Struct | | | | canceled\$1at | DateTime | | | | cancellation\$1reason | String | | | | capture\$1method | String | | | | client\$1secret | String | | | | confirmation\$1method | String | | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | customer | String | = | | | 描述 | String | | | | 發票 | String | | | | last\$1payment\$1error | Struct | | | | latest\$1charge | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | next\$1action | Struct | | | | on\$1behalf\$1of | String | | | | payment\$1method | String | | | | payment\$1method\$1options | Struct | | | | payment\$1method\$1types | 清單 | | | | payment\$1method\$1configuration\$1details | Struct | | | | 處理 | Struct | | | | receipt\$1email | String | | | | review | String | | | | setup\$1future\$1usage | String | | | | shipping | Struct | | | | source | String | | | | statement\$1descriptor | String | | | | statement\$1descriptor\$1suffix | String | | | | status | String | | | | transfer\$1data | Struct | | | | transfer\$1group | String | | | SetupIntents | | | | | | id | String | | | | object | String | | | | 應用程式 | String | | | | cancellation\$1reason | String | | | | client\$1secret | String | | | | 已建立 | DateTime | =, >=, <=,<,> | | | customer | String | = | | | 描述 | String | | | | flow\$1directions | 清單 | | | | last\$1setup\$1error | Struct | | | | latest\$1attempt | String | | | | livemode | Boolean | | | | mandate | String | | | | 中繼資料 | Struct | | | | next\$1action | Struct | | | | on\$1behalf\$1of | String | | | | payment\$1method | String | | | | payment\$1method\$1options | Struct | | | | payment\$1method\$1types | 清單 | | | | single\$1use\$1mandate | String | | | | status | String | | | | 使用方式 | String | | | | auto\$1payment\$1methods | Struct | | | 支出 | | | | | | id | String | | | | object | String | | | | amount | Integer | =, <, > | | | arrival\$1date | DateTime | =, >=, <=,<,> | | | automatic | Boolean | | | | balance\$1transaction | String | | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | 描述 | String | = | | | 目的地 | String | | | | failure\$1balance\$1transaction | String | | | | failure\$1code | String | | | | failure\$1message | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | 方法 | String | | | | original\$1payout | String | | | | reversed\$1by | String | | | | reconciliation\$1status | String | | | | source\$1type | String | | | | statement\$1descriptor | String | | | | status | String | | | | type | String | | | | application\$1fee | String | | | | application\$1fee\$1amount | Integer | | | 退款 | | | | | | id | String | | | | object | String | | | | amount | Integer | | | | balance\$1transaction | String | | | | charge | String | = | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | 中繼資料 | Struct | | | | destination\$1details | Struct | | | | payment\$1intent | String | = | | | reason | String | | | | receipt\$1number | String | | | | source\$1transfer\$1reversal | String | | | | status | String | | | | transfer\$1reversal | String | | | 產品 | | | | | | id | String | | | | object | String | | | | active | Boolean | = | | | 屬性 | 清單 | | | | 已建立 | DateTime | =, >=, <=,<,> | | | default\$1price | String | | | | 描述 | String | | | | images | 清單 | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | name | String | | | | package\$1dimensions | Struct | | | | shippable | Boolean | | | | statement\$1descriptor | String | | | | tax\$1code | String | | | | type | String | = | | | unit\$1label | String | | | | 已更新 | DateTime | | | | url | String | | | | 功能 | 清單 | | | 價格 | | | | | | id | String | | | | object | String | | | | active | Boolean | = | | | billing\$1scheme | String | | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | = | | | custom\$1unit\$1amount | Struct | | | | livemode | Boolean | | | | lookup\$1key | String | | | | 中繼資料 | Struct | | | | nickname | String | | | | product | String | = | | | recurring | Struct | | | | tax\$1behavior | String | | | | tiers\$1mode | String | | | | transform\$1quantity | Struct | | | | type | String | = | | | unit\$1amount | Integer | | | | unit\$1amount\$1decimal | String | | | 優惠券 | | | | | | Id | String | | | | object | String | | | | amount\$1off | Integer | | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | = | | | duration | String | = | | | duration\$1in\$1months | Integer | =,<,> | | | livemode | Boolean | | | | max\$1redemptions | Integer | =, <, > | | | 中繼資料 | Struct | | | | name | String | | | | percent\$1off | Double | = | | | redeem\$1by | DateTime | =, >=, <=, <, > | | | times\$1redeemed | Integer | | | | 有效 | Boolean | | | 促銷代碼 | | | | | | Id | String | | | | object | String | | | | active | Boolean | = | | | code | String | = | | | coupon | Struct | | | | 已建立 | DateTime | =,>=,<=,<,> | | | customer | String | | | | expires\$1at | DateTime | | | | livemode | Boolean | | | | max\$1redemptions | Integer | | | | 中繼資料 | Struct | | | | 限制 | Struct | | | | times\$1redeemed | Integer | | | 稅務代碼 | | | | | | Id | String | | | | object | String | | | | 描述 | String | | | | name | String | | | 稅率 | | | | | | Id | String | | | | object | String | | | | active | Boolean | = | | | 國家/地區 | String | | | | 已建立 | DateTime | =, >=, <=, <, > | | | 描述 | String | | | | display\$1name | String | | | | inclusive | Boolean | = | | | jurisdiction | String | | | | jurisdiction\$1level | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | 百分比 | Double | | | | effective\$1percentage | Double | | | | state | String | | | | tax\$1type | String | | | 運費 | | | | | | Id | String | | | | object | String | | | | active | Boolean | = | | | 已建立 | DateTime | =, >=, <=, <, > | | | delivery\$1estimate | Struct | | | | display\$1name | String | | | | fixed\$1amount | Struct | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | tax\$1behavior | String | | | | tax\$1code | String | | | | type | String | | | 工作階段 | | | | | | id | String | | | | object | String | | | | after\$1expiration | Struct | | | | allow\$1promotion\$1codes | Boolean | | | | amount\$1subtotal | Integer | | | | amount\$1total | Integer | | | | auto\$1tax | Struct | | | | billing\$1address\$1collection | String | | | | cancel\$1url | String | | | | client\$1reference\$1id | String | | | | consent | Struct | | | | consent\$1collection | Struct | | | | 已建立 | DateTime | =, >=, <=, <, > | | | currency | String | | | | custom\$1text | Struct | | | | customer | String | | | | customer\$1creation | String | | | | customer\$1details | Struct | | | | customer\$1email | String | | | | expires\$1at | DateTime | | | | 發票 | String | | | | invoice\$1creation | Struct | | | | livemode | Boolean | | | | locale | String | | | | 中繼資料 | Struct | | | | 模式 | String | | | | payment\$1intent | String | = | | | payment\$1link | String | | | | payment\$1method\$1collection | String | | | | payment\$1method\$1options | Struct | | | | payment\$1method\$1types | 清單 | | | | payment\$1status | String | | | | phone\$1number\$1collection | Struct | | | | recovered\$1from | String | | | | setup\$1intent | String | | | | shipping\$1address\$1collection | Struct | | | | shipping\$1cost | Struct | | | | shipping\$1details | Struct | | | | shipping\$1options | 清單 | | | | status | String | | | | submit\$1type | String | | | | 訂閱 | String | | | | success\$1url | String | | | | tax\$1id\$1collection | Struct | | | | total\$1details | Struct | | | | url | String | | | | ui\$1mode | String | | | 貸記通知單 | | | | | | id | String | | | | object | String | | | | amount | Integer | | | | 已建立 | DateTime | =, >=, <=, <, > | | | currency | String | | | | customer | String | = | | | customer\$1balance\$1transaction | String | | | | discount\$1amount | Integer | | | | discount\$1amounts | 清單 | | | | 發票 | String | = | | | lines | Struct | | | | livemode | Boolean | | | | memo | String | | | | 中繼資料 | Struct | | | | number | String | | | | out\$1of\$1band\$1amount | Integer | | | | pdf | String | | | | reason | String | | | | refund | String | | | | status | String | | | | subtotal | Integer | | | | subtotal\$1excluding\$1tax | Integer | | | | tax\$1amounts | 清單 | | | | total | Integer | | | | total\$1excluding\$1tax | Integer | | | | type | String | | | | voided\$1at | DateTime | | | | amount\$1shipping | Integer | | | | effective\$1at | DateTime | | | | shipping\$1cost | Struct | | | 客戶 | | | | | | id | String | | | | object | String | | | | address | Struct | | | | balance | Integer | | | | 已建立 | DateTime | | | | currency | String | =, >=, <=, <, > | | | default\$1source | String | | | | delinquent | Boolean | = | | | 描述 | String | | | | discount | Struct | | | | email | String | = | | | invoice\$1prefix | String | | | | invoice\$1settings | Struct | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | name | String | | | | next\$1invoice\$1sequence | Integer | | | | phone | String | | | | preferred\$1locales | 清單 | | | | shipping | Struct | | | | tax\$1exempt | String | | | | test\$1clock | String | | | 發票 | | | | | | id | String | | | | object | String | | | | account\$1country | String | | | | account\$1name | String | | | | account\$1tax\$1ids | 清單 | | | | amount\$1due | Integer | | | | amount\$1paid | Integer | | | | amount\$1remaining | Integer | | | | 應用程式 | String | | | | application\$1fee\$1amount | Integer | | | | attempt\$1count | Integer | | | | attempted | Boolean | = | | | auto\$1advance | Boolean | = | | | auto\$1tax | Struct | | | | billing\$1reason | String | | | | charge | String | | | | collection\$1method | String | = | | | 已建立 | DateTime | =, >=, <=, <, > | | | currency | String | | | | custom\$1fields | 清單 | | | | customer | String | = | | | customer\$1address | Struct | | | | customer\$1email | String | | | | customer\$1name | String | | | | customer\$1phone | String | | | | customer\$1shipping | Struct | | | | customer\$1tax\$1exempt | String | | | | customer\$1tax\$1ids | 清單 | | | | default\$1payment\$1method | String | | | | default\$1source | String | | | | default\$1tax\$1rates | 清單 | | | | 描述 | String | | | | discount | Struct | | | | discounts | 清單 | | | | due\$1date | DateTime | =, >=, <=, <, > | | | ending\$1balance | Integer | | | | footer | String | | | | from\$1invoice | Struct | | | | hosted\$1invoice\$1url | String | | | | invoice\$1pdf | String | | | | last\$1finalization\$1error | Struct | | | | latest\$1revision | String | | | | lines | Struct | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | next\$1payment\$1attempt | DateTime | | | | number | String | | | | on\$1behalf\$1of | String | | | | paid | Boolean | = | | | paid\$1out\$1of\$1band | Boolean | | | | payment\$1intent | String | | | | payment\$1settings | Struct | | | | period\$1end | DateTime | =, >=, <=, <, > | | | period\$1start | DateTime | =, >=, <=, <, > | | | post\$1payment\$1credit\$1notes\$1amount | Integer | | | | pre\$1payment\$1credit\$1notes\$1amount | Integer | | | | quote | String | | | | receipt\$1number | String | | | | rendering | Struct | | | | rendering\$1options | Struct | | | | start\$1balance | Integer | | | | statement\$1descriptor | String | | | | status | String | = | | | status\$1transitions | Struct | | | | 訂閱 | String | | | | subscription\$1details | Struct | | | | subtotal | Integer | =, <, > | | | subtotal\$1excluding\$1tax | Integer | | | | tax | Integer | | | | test\$1clock | String | | | | total | Integer | =, <, > | | | total\$1discount\$1amounts | 清單 | | | | total\$1excluding\$1tax | Integer | | | | total\$1tax\$1amounts | 清單 | | | | transfer\$1data | Struct | | | | webhooks\$1delivered\$1at | DateTime | | | | automatically\$1finalizes\$1at | DateTime | | | | effective\$1at | DateTime | | | | 發行者 | Struct | | | 發票項目 | | | | | | id | String | | | | object | String | | | | amount | Integer | =, <, > | | | currency | String | | | | customer | String | = | | | date | DateTime | | | | 描述 | String | | | | discountable | Boolean | | | | discounts | 清單 | | | | 發票 | String | = | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | period | Struct | | | | plan | Struct | | | | 價格 | Struct | | | | proration | Boolean | = | | | 數量 | Integer | | | | 訂閱 | String | | | | subscription\$1item | String | | | | tax\$1rates | 清單 | | | | test\$1clock | String | | | | unit\$1amount | Integer | | | | unit\$1amount\$1decimal | String | | | 計劃 | | | | | | id | String | | | | object | String | | | | active | Boolean | = | | | aggregate\$1usage | String | | | | amount | Integer | | | | amount\$1decimal | String | | | | billing\$1scheme | String | | | | 已建立 | DateTime | =, >=, <=, <, > | | | currency | String | = | | | 間隔 | String | = | | | interval\$1count | Integer | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | nickname | String | | | | product | String | = | | | tiers\$1mode | String | | | | transform\$1usage | Struct | | | | trial\$1period\$1days | Integer | =, <, > | | | usage\$1type | String | | | | meter | String | | | 報價 | | | | | | id | String | | | | object | String | | | | amount\$1subtotal | Integer | | | | amount\$1total | Integer | | | | 應用程式 | String | | | | application\$1fee\$1amount | Integer | | | | application\$1fee\$1percent | Double | | | | auto\$1tax | Struct | | | | collection\$1method | String | | | | computed | Struct | | | | 已建立 | DateTime | | | | currency | String | | | | customer | String | = | | | default\$1tax\$1rates | 清單 | | | | 描述 | String | | | | discounts | 清單 | | | | expires\$1at | DateTime | | | | footer | String | | | | from\$1quote | Struct | | | | header | String | | | | 發票 | String | | | | invoice\$1settings | Struct | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | number | String | | | | on\$1behalf\$1of | String | | | | status | String | = | | | status\$1transitions | Struct | | | | 訂閱 | String | | | | subscription\$1data | Struct | | | | subscription\$1schedule | String | | | | test\$1clock | String | | | | total\$1details | Struct | | | | transfer\$1data | Struct | | | Subscriptions | | | | | | id | String | | | | object | String | | | | 應用程式 | String | | | | application\$1fee\$1percent | Double | | | | auto\$1tax | Struct | | | | billing\$1cycle\$1anchor | DateTime | | | | billing\$1thresholds | Struct | | | | cancel\$1at | DateTime | | | | cancel\$1at\$1period\$1end | Boolean | | | | canceled\$1at | DateTime | | | | collection\$1method | String | = | | | 已建立 | DateTime | =, >=, <=,<,> | | | currency | String | | | | current\$1period\$1end | DateTime | =, >=, <= | | | current\$1period\$1start | DateTime | =, >=, <= | | | customer | String | = | | | days\$1until\$1due | Integer | | | | default\$1payment\$1method | String | | | | default\$1source | String | | | | default\$1tax\$1rates | 清單 | | | | 描述 | String | | | | discount | Struct | | | | ended\$1at | DateTime | | | | items | Struct | | | | latest\$1invoice | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | next\$1pending\$1invoice\$1item\$1invoice | DateTime | | | | pause\$1collection | Struct | | | | payment\$1settings | Struct | | | | pending\$1invoice\$1item\$1interval | Struct | | | | pending\$1setup\$1intent | String | | | | pending\$1update | Struct | | | | plan | Struct | | | | 數量 | Integer | | | | schedule | String | | | | start\$1date | DateTime | | | | status | String | = | | | test\$1clock | String | | | | transfer\$1data | Struct | | | | trial\$1end | DateTime | | | | trial\$1start | DateTime | | | 訂閱項目 | | | | | | Id | String | | | | object | String | | | | billing\$1thresholds | Struct | | | | 已建立 | DateTime | =, >=, <=, <, > | | | 中繼資料 | Struct | | | | plan | Struct | | | | 價格 | Struct | | | | 訂閱 | String | | | | tax\$1rates | 清單 | | | | discounts | 清單 | | | 訂閱排程 | | | | | | object | String | | | | 應用程式 | String | | | | canceled\$1at | DateTime | | | | completed\$1at | DateTime | | | | 已建立 | DateTime | | | | current\$1phase | Struct | | | | customer | String | = | | | default\$1settings | Struct | | | | end\$1behavior | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | 階段 | 清單 | | | | released\$1at | DateTime | | | | released\$1subscription | String | | | | renewal\$1interval | String | | | | status | String | | | | 訂閱 | String | | | | test\$1clock | String | | | 帳戶 | | | | | | details\$1submitted | Boolean | | | | tos\$1acceptance | Struct | | | | type | String | | | | 中繼資料 | Struct | | | | id | String | | | | object | String | | | | default\$1currency | String | | | | capabilities | Struct | | | | charges\$1enabled | Boolean | | | | 設定 | Struct | | | | requirements | Struct | | | | payouts\$1enabled | Boolean | | | | future\$1requirements | Struct | | | | external\$1accounts | Struct | | | | 控制器 | Struct | | | | 國家/地區 | String | | | | email | String | | | | 已建立 | DateTime | =, >=, <=, <, > | | | business\$1profile | Struct | | | | business\$1type | String | | | | company | Struct | | | 應用程式費用 | | | | | | id | String | | | | object | String | | | | 帳戶 | String | | | | amount | Integer | =, <, > | | | amount\$1refunded | Integer | =, <, > | | | 應用程式 | String | | | | balance\$1transaction | String | | | | charge | String | = | | | 已建立 | DateTime | | | | currency | String | | | | livemode | Boolean | | | | originating\$1transaction | String | | | | refunded | Boolean | = | | | refunds | Struct | | | | fee\$1source | Struct | | | 國家/地區規格 | | | | | | id | String | | | | object | String | | | | default\$1currency | String | | | | supported\$1bank\$1account\$1currencies | Struct | | | | supported\$1payment\$1currencies | 清單 | | | | supported\$1payment\$1methods | 清單 | | | | supported\$1transfer\$1countries | 清單 | | | | verification\$1fields | Struct | | | 轉接 | | | | | | id | String | | | | object | String | | | | amount | Integer | =, <, > | | | amount\$1reversed | Integer | | | | balance\$1transaction | String | | | | 已建立 | DateTime | =, >=, <=, <, > | | | currency | String | = | | | 描述 | String | | | | 目的地 | String | = | | | destination\$1payment | String | | | | livemode | Boolean | | | | 中繼資料 | Struct | | | | reversals | Struct | | | | reversed | Boolean | | | | source\$1transaction | String | | | | source\$1type | String | | | | transfer\$1group | String | = | | 早期詐騙警告 | | | | | | id | String | | | | object | String | | | | actionable | Boolean | | | | charge | String | = | | | 已建立 | DateTime | =, >=, <=, <, > | | | fraud\$1type | String | | | | livemode | Boolean | | | | payment\$1intent | String | = | | 報告類型 | | | | | | id | String | | | | object | String | | | | data\$1available\$1end | DateTime | | | | data\$1available\$1start | DateTime | | | | default\$1columns | 清單 | | | | livemode | Boolean | | | | name | String | | | | 已更新 | DateTime | | | | version | Integer | | **分區查詢** 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、`NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值範例：`"2024-07-01T00:00:00.000Z"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示。 | 實體名稱 | 分區欄位 | 資料類型 | | --- | --- | --- | | 餘額交易 | 已建立 | DateTime | | 費用 | 已建立 | DateTime | | 爭論 | 已建立 | DateTime | | 檔案連結 | 已建立 | DateTime | | PaymentIntents | 已建立 | DateTime | | SetupIntents | 已建立 | DateTime | | 支出 | 已建立 | DateTime | | 退款 | 已建立 | DateTime | | 產品 | 已建立 | DateTime | | 價格 | 已建立 | DateTime | | 優惠券 | 已建立 | DateTime | | 促銷代碼 | 已建立 | DateTime | | 稅率 | 已建立 | DateTime | | 運費 | 已建立 | DateTime | | 工作階段 | 已建立 | DateTime | | 貸記通知單 | 已建立 | DateTime | | 客戶 | 已建立 | DateTime | | 發票 | 已建立 | DateTime | | 計劃 | 已建立 | DateTime | | Subscriptions | 已建立 | DateTime | | 訂閱排程 | 已建立 | DateTime | | 帳戶 | 已建立 | DateTime | | 應用程式費用 | 已建立 | DateTime | | 轉接 | 已建立 | DateTime | | 早期詐騙警告 | 已建立 | DateTime | **範例** ``` stripe_read = glueContext.create_dynamic_frame.from_options( connection_type="stripe", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "created" "LOWER_BOUND": "2024-05-01T20:55:02.000Z" "UPPER_BOUND": "2024-07-11T20:55:02.000Z" "NUM_PARTITIONS": "10" } ) ``` # Stripe 連線選項 以下是 Stripe 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取/寫入。Stripe 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Stripe Rest API 版本。範例：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。用於讀取。要讀取的分區數目。 # 限制 以下是 Stripe 連接器的限制： + 連接器僅支援欄位型分區。 + 連接器不支援記錄型分區，沒有擷取記錄總數的佈建。 + 主索引鍵資料類型為字串，因此連接器不支援基於 ID 的分區。 # 建立新的 Stripe 帳戶並設定用戶端應用程式 **建立 Stripe 帳戶** 1. 選擇連結 **https://dashboard.stripe.com/register**。 1. 輸入電子郵件、全名、密碼，然後選擇**建立帳戶**。 1. 使用帳戶登入後，請選擇**開啟 Gmail** 來驗證帳戶。 1. 按一下電子郵件中收到的驗證連結來驗證帳戶。 1. 按一下驗證電子郵件地址後，其會重新導向至另一個頁面 1. 按一下**啟用付款**以啟用帳戶後，其會重新導向至「啟用付款」頁面 (**https://dashboard.stripe.com/welcome**)，並確保填寫全部有效的詳細資訊，然後選擇**繼續**按鈕。 **建立 Slack 開發人員應用程式** 1. 登入 [Stripe](https://dashboard.stripe.com/login)。 1. 選擇如下圖頂端顯示的**開發人員**。 1. 在「開發人員」下選擇 **API 金鑰**。 1. 選擇**顯示測試金鑰**以取得 API 金鑰。 # 在 AWS Glue Studio 中連線至 Teradata Vantage AWS Glue 會提供 Teradata Vantage 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 Teradata、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 AWS Glue Studio 會為 Teradata Vantage 建立統一連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 **Topics** + [建立 Teradata Vantage 連線](creating-teradata-connection.md) + [建立 Teradata 來源節點](creating-teradata-source-node.md) + [建立 Teradata 目標節點](creating-teradata-target-node.md) + [進階選項](#creating-teradata-connection-advanced-options) # 建立 Teradata Vantage 連線 若要從 連線至 Teradata Vantage AWS Glue，您需要在 AWS Secrets Manager 秘密中建立和存放 Teradata 登入資料，然後將該秘密與 AWS Glue Teradata 連線建立關聯。 **先決條件：** + 如果您透過 Amazon VPC 存取 Teradata 環境，請將 Amazon VPC 設定為允許 AWS Glue 任務與 Teradata 環境通訊。我們不建議透過公有網際網路存取 Teradata 環境。 在 Amazon VPC 中，識別或建立 AWS Glue 將在執行任務時使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 Teradata 執行個體與此位置之間的網路流量。您的任務將需要與 Teradata 用戶端連接埠建立 TCP 連線。如需有關 Teradata 連接埠的詳細資訊，請參閱 [Teradata 文件](https://docs.teradata.com/r/Teradata-VantageTM-on-AWS-DIY-Installation-and-Administration-Guide/April-2020/Before-Deploying-Vantage-on-AWS-DIY/Security-Groups-and-Ports)。 根據您的網路配置，安全 VPC 連線可能需要變更 Amazon VPC 和其他網路服務。如需 AWS 連線的詳細資訊，請參閱 Teradata 文件中的[AWS 連線選項](https://docs.teradata.com/r/Teradata-VantageCloud-Enterprise/Get-Started/Connecting-Your-Environment/AWS-Connectivity-Options)。 **若要設定 AWS Glue Teradata 連線：** 1. 在您的 Teradata 組態中，識別或建立 AWS Glue 將與 *teradataUser* 和 *teradataPassword* 連線的使用者和密碼。如需詳細資訊，請參閱《Teradata 文件》中的 [Vantage 安全概觀](https://docs.teradata.com/r/Configuring-Teradata-VantageTM-After-Installation/January-2021/Security-Overview/Vantage-Security-Overview)。 1. 在 中 AWS Secrets Manager，使用您的 Teradata 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *teradataUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *teradataPassword* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Teradata。 + 提供 **JDBC URL** 時，請提供執行個體的 URL。您也可在 JDBC URL 中，針對特定逗號分隔的連線參數進行硬編碼。URL 必須符合下列格式：`jdbc:teradata://teradataHostname/ParameterName=ParameterValue,ParameterName=ParameterValue` 支援的 URL 參數包括： + `DATABASE`：依預設要存取之主機的資料庫名稱。 + `DBS_PORT`：在非標準連接埠上執行時所使用的資料庫連接埠。 + 選取**憑證類型**時，請選取 **AWS Secrets Manager**，然後將 **AWS 密碼** 設定為 *secretName*。 1. 在下列情況中，您可能需要其他組態： + 對於 Amazon VPC AWS 中託管於 的 Teradata 執行個體 + 您需要提供 Amazon VPC 連線資訊給定義 Teradata 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 # 建立 Teradata 來源節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue Teradata Vantage 連線，如上節所述：[建立 Teradata Vantage 連線](creating-teradata-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要讀取的 Teradata 資料表 *tableName* 或查詢 *targetQuery*。 ## 新增 Teradata 資料來源 **新增**資料來源 – Teradata** 節點：** 1. 選擇 Teradata 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立新連線**。如需詳細資訊，請參閱前一 [建立 Teradata Vantage 連線](creating-teradata-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇 **Teradata 來源**選項： + **選擇單一資料表**：從單一資料表存取所有資料。 + **輸入自訂查詢**：根據自訂查詢從多個資料表存取資料集。 1. 如果您選擇單一資料表，請輸入 *tableName*。 如果您選擇**輸入自訂查詢**，請輸入 SQL SELECT 查詢。 1. 在**自訂 Teradata 屬性**中，視需要輸入參數和值。 # 建立 Teradata 目標節點 ## 必要先決條件 + 使用 AWS Secrets Manager 秘密設定的 AWS Glue Teradata Vantage 連線，如上節所述：[建立 Teradata Vantage 連線](creating-teradata-connection.md)。 + 針對您任務的適當許可，以讀取連線所使用的秘密。 + 您想要寫入的 Teradata 資料表 *tableName*。 ## 新增 Teradata 資料目標 **新增**資料目標 – Teradata** 節點：** 1. 選擇 Teradata 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Teradata 連線**。如需詳細資訊，請參閱 [Overview of using connectors and connections ](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 透過提供 *tableName* 來設定**資料表名稱**。 1. 在**自訂 Teradata 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 Teradata 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[Teradata Vantage 連線](aws-glue-programming-etl-connect-teradata-home.md)。 # 連線至 Twilio Twilio 提供可程式設計的通訊工具，用於撥打和接聽電話、傳送和接收簡訊，以及使用 Web 服務 API 執行其他通訊功能。Twilio 的 API 為其通訊平台提供支援。這些 API 背後是一個軟體層，其連接並最佳化世界各地的通訊網路，可讓您的使用者呼叫和傳送訊息給全球的任何人。身為 Twilio 使用者，您可以 AWS Glue 連線至您的 Twilio 帳戶。然後，您可以在 ETL 任務中使用 Twilio 作為資料來源。執行這些任務以在 Twilio AWS 和服務或其他支援的應用程式之間傳輸資料。 **Topics** + [AWS Glue 支援 Twilio](twilio-support.md) + [包含用於建立和使用連線的 API 操作的政策](twilio-configuring-iam-permissions.md) + [設定 Twilio](twilio-configuring.md) + [設定 Twilio 連線](twilio-configuring-connections.md) + [從 Twilio 實體中讀取](twilio-reading-from-entities.md) + [Twilio 連線選項](twilio-connection-options.md) + [Twilio 連接器的限制和備註](twilio-connector-limitations.md) # AWS Glue 支援 Twilio AWS Glue 支援 Twilio，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Twilio 查詢資料。 **支援作為目標？** 否。 **支援的 Twilio API 版本** 支援以下 Twilio API 版本： + v1 + 2010-04-01 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Twilio 您必須先符合下列要求，才能使用 從 Twilio AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個帶有使用者名稱和密碼的 Twilio 帳戶。 + 您的 Twilio 帳戶已啟用 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Twilio 帳戶。對於一般連線，您不需要在 Twilio 中執行任何其他操作。 # 設定 Twilio 連線 Twilio 支援基本身分驗證的使用者名稱和密碼。基本身分驗證是一種簡單的身分驗證方法，其中用戶端會直接提供登入資料來存取受保護的資源。 AWS Glue 能夠使用使用者名稱 （帳戶 SID) 和密碼 （身分驗證字符） 來驗證 Twilio APIs。 如需基本身分驗證流程的公有 Twilio 文件，請參閱[基本身分驗證 \$1 Twilio](https://www.twilio.com/docs/glossary/what-is-basic-authentication)。 若要設定 Twilio 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： + 對於基本身分驗證：機密應包含具有**帳戶 SID** (使用者名稱) 和**身分驗證字符** (密碼) 的已連線應用程式消費者機密。 **注意** 您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**連線類型**時，選取 Twilio。 1. 提供您要連線的 Twilio 執行個體的 `[Edge\$1Location](https://www.twilio.com/docs/global-infrastructure/edge-locations)`。 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`。 # 從 Twilio 實體中讀取 **必要條件** 您要從中讀取的 Twilio 物件。您將需要物件名稱，例如 `SMS-Message` 或 `SMS-CountryPricing`。 **來源的支援實體**： | 實體 | 介面 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | --- | | SMS-Message | REST | 是 | 是 | 否 | 是 | 是 | | SMS-CountryPricing | REST | 否 | 否 | 否 | 是 | 否 | | Voice-Call | REST | 是 | 是 | 否 | 是 | 否 | | Voice-Application | REST | 是 | 是 | 否 | 是 | 否 | | Voice-OutgoingCallerID | REST | 是 | 是 | 否 | 是 | 否 | | Voice-Queue | REST | 是 | 是 | 否 | 是 | 否 | | Conversations-Conversation | REST | 是 | 是 | 否 | 是 | 否 | | Conversations-User | REST | 否 | 是 | 否 | 是 | 否 | | Conversations-Role | REST | 否 | 是 | 否 | 是 | 否 | | Conversations-Configuration | REST | 否 | 否 | 否 | 是 | 否 | | Conversations-AddressConfiguration | REST | 是 | 是 | 否 | 是 | 否 | | Conversations-WebhookConfiguration | REST | 否 | 否 | 否 | 是 | 否 | | Conversations-ParticipantConversation | REST | 否 | 否 | 否 | 是 | 否 | | Conversations-Credential | REST | 否 | 是 | 否 | 是 | 否 | | Conversations-ConversationService | REST | 否 | 是 | 否 | 是 | 否 | **範例**： ``` twilio_read = glueContext.create_dynamic_frame.from_options( connection_type="twilio", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "sms-message", "API_VERSION": "2010-04-01", "Edge_Location": "sydney.us1" } ``` **Twilio 實體和欄位詳細資訊**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/twilio-reading-from-entities.html) ## 分區查詢 **支援分區的欄位**： 在 Twilio 中，DateTime 資料類型欄位支援欄位型分區。 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-05-01T20:55:02.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` twilio_read = glueContext.create_dynamic_frame.from_options( connection_type="twilio", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "sms-message", "API_VERSION": "2010-04-01", "PARTITION_FIELD": "date_sent" "LOWER_BOUND": "2024-05-01T20:55:02.000Z" "UPPER_BOUND": "2024-06-01T20:55:02.000Z" "NUM_PARTITIONS": "10" } ``` # Twilio 連線選項 以下是 Twilio 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Twilio 中的物件名稱。 + `EDGE_LOCATION`(字串) - (必要) 有效的 Twilio 邊緣節點。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Twilio Rest API 版本。Twilio 支援兩個 API 版本：「v1」和「2010-04-01」。 + `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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 Twilio 執行個體 URL。 # Twilio 連接器的限制和備註 以下是 Twilio 連接器的限制或備註： + 不支援記錄型分區，因為沒有從 Twilio 擷取記錄總數的佈建。 + 欄位 `date_sent`、`start_time` 和 `end_time` 屬於 Datetime 資料類型，但在篩選時，其僅支援日期值 (不考慮時間元件)。 + 只有在值不包含任何字首 (例如通訊協定或標籤) 時，篩選 "from" 或 "to" 欄位才有效。如果有字首，則無法篩選相應欄位。例如，如果傳遞 "to": "whatsapp:\$114xxxxxxxxxx" 作為篩選條件，則 Twilio 不會傳回一個回應。需要將其傳遞為 "to": "\$114xxxxxxxx"，如果記錄存在的話，則會傳回記錄。 + 查詢 `conversation-participant-conversation` 實體時，"identity" 欄位篩選條件為必要項目。 # 在 AWS Glue Studio 中連線至 Vertica AWS Glue 會提供 Vertica 的內建支援。AWS Glue Studio 會提供視覺化介面以連線至 Vertica、撰寫資料整合任務，以及在 AWS Glue Studio 無伺服器 Spark 執行期上執行此類任務。 AWS Glue Studio 會為 Vertica 建立統一連線。如需詳細資訊，請參閱[考量事項](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。 **Topics** + [建立 Vertica 連線](creating-vertica-connection.md) + [建立 Vertica 來源節點](creating-vertica-source-node.md) + [建立 Vertica 目標節點](creating-vertica-target-node.md) + [進階選項](#creating-vertica-connection-advanced-options) # 建立 Vertica 連線 **先決條件：** + 從資料庫讀取和寫入資料庫時用於暫存空間的 Amazon S3 儲存貯體或資料夾 (稱為 *tempS3Path*)。 **注意** 在 AWS Glue 任務資料預覽中使用 Vertica 時，可能不會自動從 *tempS3Path* 中移除暫存檔案。若要確保移除暫存檔案，請選擇**資料預覽**窗格中的**結束工作階段**，直接結束資料預覽工作階段。 如果無法保證資料預覽工作階段會直接結束，請考慮設定 Amazon S3 生命週期組態以移除舊資料。根據最長任務執行期和餘裕，我們建議移除超過 49 小時的資料。如需有關設定 Amazon S3 生命週期的詳細資訊，請參閱《Amazon S3 文件》中的[管理您的儲存空間生命週期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)。 + IAM 政策，具有與 AWS Glue 任務角色建立關聯之 Amazon S3 路徑的適當許可。 + 如果您的 Vertica 執行個體位於 Amazon VPC 中，請設定 Amazon VPC 以允許您的 AWS Glue 任務與 Vertica 執行個體通訊，而不會讓流量周遊公有網際網路。 在 Amazon VPC 中，識別或建立 AWS Glue 將在執行任務時使用的 **VPC**、**子網路**和**安全群組**。此外，您也需要確保 Amazon VPC 已完成設定，以允許 Vertica 執行個體與此位置之間的網路流量。您的任務將需要與 Vertica 用戶端連接埠建立 TCP 連線 (預設 5433)。根據您的網路配置，這可能需要變更安全群組規則、網路 ACL、NAT 閘道及對等連線。 **設定連至 Vertica 的連線：** 1. 在 中 AWS Secrets Manager，使用您的 Vertica 登入資料 *verticaUsername* 和 *verticaPassword* 建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。 + 在選取**鍵/值組**時，請使用 *verticaUsername* 值來建立 `user` 金鑰對。 + 在選取**鍵/值組**時，請使用 *verticaPassword* 值來建立 `password` 金鑰對。 1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 *connectionName*，以便進行下一個步驟。 + 選取**連線類型**時，請選取 Vertica。 + 選取 **Vertica 主機**後，請提供 Vertica 安裝的主機名稱。 + 選取 **Vertica 連接埠**時，您可透過該連接埠安裝 Vertica。 + 選取 **AWS 機密**時，請提供 *secretName*。 1. 在下列情況中，您可能需要其他組態： + 對於 Amazon VPC AWS 中託管於 的 Vertica 執行個體 + 將 Amazon VPC 連線資訊提供給定義 Vertica 安全登入資料的 AWS Glue 連線。建立或更新連線時，請在**網路選項**中設定 **VPC**、**子網路**及**安全群組**。 您必須先執行下列步驟，才能執行 AWS Glue 任務： + 將與您的 AWS Glue 任務許可相關聯的 IAM 角色授予 *tempS3Path*。 + 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 *secretName* 的許可。 # 建立 Vertica 來源節點 ## 必要先決條件 + Vertica 類型 AWS Glue Data Catalog 連線、*connectionName* 和暫時 Amazon S3 位置 *tempS3Path*，如上一節 所述[建立 Vertica 連線](creating-vertica-connection.md)。 + 您想要讀取的 Vertica 資料表 *tableName* 或查詢 *targetQuery*。 ## 新增 Vertica 資料來源 **新增**資料來源 – Vertica** 節點：** 1. 選擇 Vertica 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Vertica 連線**。如需詳細資訊，請參閱前一 [建立 Vertica 連線](creating-vertica-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇包含資料表的**資料庫**。 1. 選擇 **Amazon S3 中的暫存區域**，將 S3A URI 輸入 *tempS3Path*。 1. 選擇 **Verica 來源**。 + **選擇單一資料表**：從單一資料表存取所有資料。 + **輸入自訂查詢**：根據自訂查詢從多個資料表存取資料集。 1. 如果您選擇單一資料表，請輸入 *tableName*，然後選擇性選取**結構描述**。 如果您選擇**輸入自訂查詢**，請輸入 SQL SELECT 查詢，然後選擇性選取**結構描述**。 1. 在**自訂 Vertica 屬性**中，視需要輸入參數和值。 # 建立 Vertica 目標節點 ## 必要先決條件 + Vertica 類型 AWS Glue Data Catalog 連線、*connectionName* 和暫時 Amazon S3 位置 *tempS3Path*，如上一節 所述[建立 Vertica 連線](creating-vertica-connection.md)。 ## 新增 Vertica 資料目標 **新增**資料目標 – Vertica** 節點：** 1. 選擇 Vertica 資料來源的連線。由於您已建立連線，其應可用於下拉式清單中。如果您需要建立連線，請選擇**建立 Vertica 連線**。如需詳細資訊，請參閱前一 [建立 Vertica 連線](creating-vertica-connection.md) 節。 選擇連線之後，您可以按一下**檢視屬性**來檢視連線屬性。 1. 選擇包含資料表的**資料庫**。 1. 選擇 **Amazon S3 中的暫存區域**，將 S3A URI 輸入 *tempS3Path*。 1. 輸入 *tableName*，然後選擇性選取**結構描述**。 1. 在**自訂 Vertica 屬性**中，視需要輸入參數和值。 ## 進階選項 您可以在建立 Vertica 節點時提供進階選項。這些選項與 AWS Glue Spark 指令碼程式設計時可用的選項相同。 請參閱[Vertica 連線](aws-glue-programming-etl-connect-vertica-home.md)。 # 連線至 WooCommerce WooCommerce 是針對以 WordPress 為基礎的網站建置的開放原始碼彈性軟體解決方案。通常用於建立線上電子商務商店。透過此軟體解決方案，任何人都可以將一般網站轉換為功能完整的線上商店。 **Topics** + [AWS Glue 支援 WooCommerce](woocommerce-support.md) + [包含用於建立和使用連線的 API 操作的政策](woocommerce-configuring-iam-permissions.md) + [設定 WooCommerce](woocommerce-configuring.md) + [設定 WooCommerce 連線](woocommerce-configuring-connections.md) + [從 WooCommerce 實體中讀取](woocommerce-reading-from-entities.md) + [WooCommerce 連線選項](woocommerce-connection-options.md) # AWS Glue 支援 WooCommerce AWS Glue 支援 WooCommerce，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 WooCommerce 查詢資料。 **支援作為目標？** 否。 **支援的 WooCommerce API 版本** 支援下列 WooCommerce API 版本： + v3 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 WooCommerce 您必須先符合下列要求，才能使用 從 WooCommerce AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個具有 `consumerKey` 和 `consumerSecret` 的 WooCommerce 帳戶。 + 您的 WooCommerce 帳戶具有包含有效授權的 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到您的 WooCommerce 帳戶。對於一般連線，您不需要在 WooCommerce 中執行任何其他操作。 # 設定 WooCommerce 連線 WooCommerce 支援自訂身分驗證。如需有關產生自訂授權所需 API 金鑰的公有 WooCommerce 文件，請參閱[身分驗證 – WooCommerce REST API 文件](https://woocommerce.github.io/woocommerce-rest-api-docs/#authentication)。 若要設定 WooCommerce 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： + 對於客戶管理的連線應用程式，機密應包含以 `consumerKey` 和 `consumerSecret` 作為金鑰的連線應用程式消費者機密。注意：您必須在 AWS Glue中為每個連線建立機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 WooCommerce。 1. 提供您要連線的 WooCommerce 執行個體的 `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`。 # 從 WooCommerce 實體中讀取 **必要條件** 您要從中讀取的 WooCommerce 物件。將需要物件名稱，例如優惠券、訂單、產品等。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 優惠券 | 是 | 是 | 是 | 是 | 是 | | 優惠券總計 | 否 | 否 | 否 | 是 | 否 | | 客戶總計 | 否 | 否 | 否 | 是 | 否 | | 順序 | 是 | 是 | 是 | 是 | 是 | | 訂單總計 | 否 | 否 | 否 | 是 | 否 | | 付款閘道 | 否 | 否 | 否 | 是 | 否 | | 產品 | 是 | 是 | 是 | 是 | 是 | | 產品屬性 | 是 | 是 | 是 | 是 | 是 | | 產品類別 | 是 | 是 | 是 | 是 | 是 | | 產品評論 | 是 | 是 | 是 | 是 | 是 | | 產品運輸類別 | 是 | 是 | 是 | 是 | 是 | | 產品標籤 | 是 | 是 | 是 | 是 | 是 | | 產品變化 | 是 | 是 | 是 | 是 | 是 | | 產品總計 | 否 | 否 | 否 | 是 | 否 | | 報告 (清單) | 否 | 否 | 否 | 是 | 否 | | 檢閱總計 | 否 | 否 | 否 | 是 | 否 | | 銷售報告 | 是 | 否 | 否 | 是 | 否 | | 運輸方法 | 否 | 否 | 否 | 是 | 否 | | 運輸區域 | 否 | 否 | 否 | 是 | 否 | | 運輸區域位置 | 否 | 否 | 否 | 是 | 否 | | 運算區域方法 | 否 | 否 | 否 | 是 | 否 | | 稅率 | 是 | 是 | 是 | 是 | 是 | | 稅種 | 否 | 否 | 否 | 是 | 否 | | 熱門賣家報告 | 是 | 否 | 否 | 是 | 否 | **範例**： ``` woocommerce_read = glueContext.create_dynamic_frame.from_options( connection_type="glue.spark.woocommerce", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupon", "API_VERSION": "v3", "INSTANCE_URL": "instanceUrl" } ``` **WooCommerce 實體和欄位詳細資訊**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/woocommerce-reading-from-entities.html) **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型，DateTime 資料類型會轉換為 Timestamp。 ## 分區查詢 **記錄型分區**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 在記錄型分區中，會從 WooCommerce API 中查詢存在的記錄總數，並除以提供的 `NUM_PARTITIONS` 數目。然後，每個子查詢都會同時擷取產生的記錄數目。 + `NUM_PARTITIONS`：分區數目。 下列實體支援記錄型分區： + coupon + order + product + product-attribute + product-attribute-term + product-category + product-review + product-shipping-class + product-tag + product-variation + tax-rate 範例： ``` woocommerce_read = glueContext.create_dynamic_frame.from_options( connection_type="glue.spark.woocommerce", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupon", "API_VERSION": "v3", "INSTANCE_URL": "instanceUrl" "NUM_PARTITIONS": "10" } ``` **記錄型分區**： 原始查詢會分區為 Spark 任務可同時執行的子查詢的 `NUM_PARTITIONS` 數目： + `NUM_PARTITIONS`：分區數目。 範例： ``` WooCommerce_read = glueContext.create_dynamic_frame.from_options( connection_type="WooCommerce", connection_options={ "connectionName": "connectionName", "REALMID": "1234567890123456789", "ENTITY_NAME": "Bill", "API_VERSION": "v3", "NUM_PARTITIONS": "10" } ``` # WooCommerce 連線選項 以下是 WooCommerce 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。WooCommerce 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 WooCommerce Rest API 版本。 + `REALM_ID`(String) - 一個 ID，其識別您在其中傳送請求的單個 WooCommerce 線上公司。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `INSTANCE_URL`(String) - (必要) 有效的 WooCommerce 執行個體 URL，格式為：https://.wpcomstaging.com + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # 連線至 Zendesk Zendesk 是以雲端為基礎的服務台管理解決方案，提供可自訂的工具來建置客戶服務入口網站、知識庫和線上社群。 **Topics** + [AWS Glue 支援 Zendesk](zendesk-support.md) + [包含用於建立和使用連線的 API 操作的政策](zendesk-configuring-iam-permissions.md) + [設定 Zendesk](zendesk-configuring.md) + [設定 Zendesk 連線](zendesk-configuring-connections.md) + [從 Zendesk 實體中讀取](zendesk-reading-from-entities.md) + [Zendesk 連線選項](zendesk-connection-options.md) + [限制](zendesk-limitations.md) # AWS Glue 支援 Zendesk AWS Glue 支援 Zendesk，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Zendesk 查詢資料。 **支援作為目標？** 否。 **支援的 Zendesk API 版本** 支援下列 Zendesk API 版本 +   v2 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Zendesk 您必須先符合下列要求，才能使用 從 Zendesk AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Zendesk 帳戶。如需詳細資訊，請參閱[建立 Zendesk 帳戶](#zendesk-configuring-creating-account)。 + 您的 Zendesk 帳戶已啟用 API 存取。 + 您的 Zendesk 帳戶可讓您安裝連線的應用程式。 如果您符合這些要求，就可以 AWS Glue 連線到 Zendesk 帳戶。 ## 建立 Zendesk 帳戶 若要建立 Zendesk 帳戶： 1. 前往 https://www.zendesk.com/in/register/ 1. 輸入詳細資訊，例如工作電子郵件、名字、姓氏、電話號碼、職稱、公司名稱、公司員工人數、密碼和偏好的語言。然後選擇**完成試用註冊**。 1. 建立帳戶後，請完成您收到的驗證連結，以驗證您的電子郵件地址。 1. 驗證工作電子郵件地址後，系統會將您重新導向至 Zendesk 帳戶。針對您偏好的計劃選擇**購買 Zendesk 選項**。注意：對於 Zendesk 連接器，建議購買 Suite Enterprise 計劃。 ## 建立用戶端應用程式和 OAuth 2.0 憑證 若要建立用戶端應用程式和 OAuth 2.0 憑證： 1. 登入您要在其中建立 OAuth 2.0 應用程式的 Zendesk 帳戶 https://www.zendesk.com/in/login/ 1. 按一下齒輪圖示。選擇**前往管理中心**連結以開啟管理中心頁面。 1. 在左側邊欄中選擇**應用程式和整合**，然後選取 **API** > **Zendesk API**。 1. 在 Zendesk API 頁面上，選擇 **OAuth 用戶端**索引標籤。 1. 選擇右側的**新增 Oauth 用戶端**。 1. 完成下列欄位以建立用戶端： 1. 用戶端名稱 - 輸入應用程式名稱。這是使用者在被要求授權應用程式存取權時，以及當他們檢查可存取其 Zendesk 的第三方應用程式清單時，將會看到的名稱。 1. 說明 - 選用。當使用者被要求為您的應用程式授予存取權時會看到的簡短說明。 1. 公司 - 選用。當使用者被要求為您的應用程式授予存取權時會看到的公司名稱。這些資訊可以協助他們了解授予存取權的對象。 1. 標誌 - 選用。這是使用者在被要求授予應用程式存取權時將會看到的標誌。影像格式可以是 JPG、GIF 或 PNG。為了獲得最佳結果，請上傳方形影像。其會針對授權頁面調整大小。 1. 唯一識別符 - 欄位會自動填入您為應用程式輸入之名稱的重新格式化版本。若您希望的話，可以變更。 1. 重新導向 URL - 輸入一個或多個 URL，Zendesk 應使用其來傳送使用者的決策，以授權您的應用程式。 例如：https://us-east-1.console.aws.amazon.com/gluestudio/oauth 1. 按一下 **Save (儲存)**。 1. 頁面重新整理後，下方會出現新的預先填入**機密**欄位。這是 OAuth2 規格中指定的 "client\$1secret" 值。將機密值複製到剪貼簿，並將其儲存在安全的地方。注意：字元可能會超出文字方塊的寬度，因此請務必在複製之前選取所有項目。 1. 按一下 **Save (儲存)**。 # 設定 Zendesk 連線 Zendesk 連接器支援授權碼授予類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。根據預設，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式AWS Glue（受管用戶端應用程式），除了其 Zendesk 執行個體 URL 之外，不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Zendesk，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Zendesk 執行個體。 + 您仍然可以選擇在 Zendesk 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，您仍會重新導向至 Zendesk 以登入並授權 AWS Glue 存取您的 資源。 + 此授權類型會產生存取字符。存取字符永遠不會過期。 如需為授權碼 OAuth 流程建立連線應用程式的公有 Zendesk 文件，請參閱[授權類型的 OAuth 字符](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/)。 若要設定 Zendesk 連線： 1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密： 1. 對於 AuthorizationCode 授權類型：對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須在 AWS Glue中為每個連線建立機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Zendesk。 1. 提供您要連線之 Zendesk 的 INSTANCE\$1URL。 1. 提供 Zendesk 環境。 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`。 # 從 Zendesk 實體中讀取 **必要條件** 您要從中讀取的 Zendesk 物件。您將需要物件名稱，例如票證或使用者或文章，如下表所述。 | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 票證 | Y | Y | Y | Y | N | | 使用者 | Y | Y | Y | Y | N | | 組織 | Y | Y | Y | Y | N | | 文章 | Y | Y | N | Y | N | | 票證事件 | Y | Y | N | Y | N | | 票證指標事件 | Y | Y | N | Y | N | | 票證評論 | Y | Y | Y | Y | N | | 票證欄位 | Y | Y | N | Y | N | | 票證指標 | Y | Y | N | Y | N | | 票證活動 | Y | Y | N | Y | N | | 略過票證 | N | Y | N | Y | N | | Group | Y | Y | Y | Y | N | | 群組成員資格 | N | Y | Y | Y | N | | 滿意度評分 | Y | Y | N | Y | N | | 檢視 | Y | Y | Y | Y | N | | 觸發條件 | Y | Y | Y | Y | N | | 觸發條件類別 | N | Y | Y | Y | N | | 巨集 | Y | Y | Y | Y | N | |  自動化 | N | Y | Y | Y | N | **範例**： ``` Zendesk_read = glueContext.create_dynamic_frame.from_options( connection_type="Zendesk", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v2" } ``` **Zendesk 實體和欄位詳細資訊**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/zendesk-reading-from-entities.html) **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。 ## 分區查詢 Zendesk 不支援分區。 # Zendesk 連線選項 以下是 Zendesk 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Zendesk 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Zendesk Rest API 版本。例如：v2。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。例如：id、name、url、created\$1at + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。例如：group\$1id = 100 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。例如："SELECT id,url FROM users WHERE role=\$1"end-user\$1"" + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。預設欄位為 `update_at`，其適用於支援增量匯出 API 的實體 (`created_at` 適用於 `ticket-events`，`time` 適用於 `ticket-metric-events`)。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。選用；如果任務選項中未提供此選項，則連接器會處理此選項。預設值 - "2024-05-01T20:55:02.000Z + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。選用；如果任務選項中未提供此選項，則連接器會處理此選項。預設值：1。 + `IMPORT_DELETED_RECORDS`(String) - 預設：FALSE。用於讀取。在查詢時取得刪除記錄。 + `ACCESS_TOKEN` - 要在請求中使用的存取字符。 + `INSTANCE_URL` - 使用者想要執行操作的執行個體 URL。例如：https://\$1subdomain\$1/.zendesk.com # 限制 以下是 Zendesk 連接器的限制： + 位移型分區會將可擷取的頁面數限制為 100，但不建議這樣做，因為可擷取的記錄總數為 10,000。不過，針對 Zendesk 連接器實作的游標型分區可克服此限制。Zendesk API 僅支援 EQUAL\$1TO 篩選條件運算子。 因此，Zendesk 連接器不支援分區。 + 對於「票證事件」實體，「速率限制」為每分鐘 10 個請求。執行 AWS Glue ETL 任務時，您可能會收到 429 （太多請求） 錯誤。 # 連線至 Zoho CRM Zoho CRM 作為單一儲存庫，將銷售、行銷和客戶支援活動整合在一起，並在單一平台上簡化程序、政策和人員。Zoho CRM 可以輕鬆自訂，以滿足任何商業類型和大小的特定需求。 Zoho CRM 的開發人員平台為企業提供適當的低程式碼和專業程式碼工具組合，以自動化工作、跨企業堆疊整合資料，以及為 Web 和行動裝置建立自訂解決方案。 **Topics** + [AWS Glue 支援 Zoho CRM](zoho-crm-support.md) + [包含用於建立和使用連線的 API 操作的政策](zoho-crm-configuring-iam-permissions.md) + [設定 Zoho CRM](zoho-crm-configuring.md) + [設定 Zoho CRM 連線](zoho-crm-configuring-connections.md) + [從 Zoho CRM 實體中讀取](zoho-crm-reading-from-entities.md) + [Zoho CRM 連線選項](zoho-crm-connection-options.md) + [Zoho CRM 連接器的限制和備註](zoho-crm-connector-limitations.md) # AWS Glue 支援 Zoho CRM AWS Glue 支援 Zoho CRM，如下所示： **支援作為來源？** 是 – 同步和非同步。您可以使用 AWS Glue ETL 任務從 Zoho CRM 查詢資料。 **支援作為目標？** 否。 **支援的 Zoho CRM API 版本** 支援下列 Zoho CRM API 版本： + v7 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Zoho CRM 您必須先符合下列要求，才能使用 從 Zoho CRM AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有 Zoho CRM 帳戶。 + 您的 Zoho CRM 帳戶已啟用 API 存取。 + 您可以在 API 主控台下擁有已註冊的 API 用戶端，來取得 OAuth 憑證。 # 設定 Zoho CRM 連線 授予類型決定 如何與 Zoho CRM AWS Glue 通訊，以請求存取您的資料。您的選擇會影響您在建立連線之前必須滿足的要求。Zoho CRM 僅支援 OAuth 2.0 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 AWS Glue 主控台會將使用者重新導向至 Zoho CRM，使用者必須在其中登入，並允許 Glue 請求的許可存取其 Zoho CRM 執行個體。 + 使用者仍可選擇在 Zoho CRM 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID、身分驗證 URL、字符 URL 和執行個體 URL。在此案例中，它們仍會重新導向至 Zoho CRM 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符的有效期為一小時，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關為授權碼 OAuth 流程建立連線應用程式的公有 Zoho CRM 文件，請參閱[身分驗證](https://www.zoho.com/crm/developer/docs/api/v7/oauth-overview.html)。 若要設定 Zoho CRM 連線： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Zoho CRM。 1. 提供您要連線的 Zoho CRM 執行個體的 `INSTANCE_URL`。 1. 提供使用者用戶端應用程式用戶端 ID。 1. 從下拉式清單中選取適當的**身分驗證 URL**。 1. 從下拉式清單中選取適當的**字符 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`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Zoho CRM 實體中讀取 **必要條件** 您想要讀取的 Zoho CRM 物件。將需要物件名稱。 **同步來源支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 產品 | 是 | 是 | 是 | 是 | 是 | | 報價 | 是 | 是 | 是 | 是 | 是 | | 購買訂單 | 是 | 是 | 是 | 是 | 是 | | 解決方案 | 是 | 是 | 是 | 是 | 是 | | 呼叫 | 是 | 是 | 是 | 是 | 是 | | 任務 | 是 | 是 | 是 | 是 | 是 | | 事件 | 是 | 是 | 是 | 是 | 是 | | 發票 | 是 | 是 | 是 | 是 | 是 | | 帳戶 | 是 | 是 | 是 | 是 | 是 | | 聯絡 | 是 | 是 | 是 | 是 | 是 | | 廠商 | 是 | 是 | 是 | 是 | 是 | | 行銷活動 | 是 | 是 | 是 | 是 | 是 | | 交易 | 是 | 是 | 是 | 是 | 是 | | 潛在客戶 | 是 | 是 | 是 | 是 | 是 | | 自訂模組 | 是 | 是 | 是 | 是 | 是 | | 銷售訂單 | 是 | 是 | 是 | 是 | 是 | | 價目表 | 是 | 是 | 是 | 是 | 是 | | 案例 | 是 | 是 | 是 | 是 | 是 | **範例**： ``` zoho_read = glueContext.create_dynamic_frame.from_options( connection_type="ZOHO", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v7", "INSTANCE_URL": "https://www.zohoapis.in/" } ``` **非同步來源支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 產品 | 是 | 否 | 否 | 是 | 否 | | 報價 | 是 | 否 | 否 | 是 | 否 | | 購買訂單 | 是 | 否 | 否 | 是 | 否 | | 解決方案 | 是 | 否 | 否 | 是 | 否 | | 呼叫 | 是 | 否 | 否 | 是 | 否 | | 任務 | 是 | 否 | 否 | 是 | 否 | | 事件 | 是 | 否 | 否 | 是 | 否 | | 發票 | 是 | 否 | 否 | 是 | 否 | | 帳戶 | 是 | 否 | 否 | 是 | 否 | | 聯絡 | 是 | 否 | 否 | 是 | 否 | | 廠商 | 是 | 否 | 否 | 是 | 否 | | 行銷活動 | 是 | 否 | 否 | 是 | 否 | | 交易 | 是 | 否 | 否 | 是 | 否 | | 潛在客戶 | 是 | 否 | 否 | 是 | 否 | | 自訂模組 | 是 | 否 | 否 | 是 | 否 | | 銷售訂單 | 是 | 否 | 否 | 是 | 否 | | 價目表 | 是 | 否 | 否 | 是 | 否 | | 案例 | 是 | 否 | 否 | 是 | 否 | **範例**： ``` zoho_read = glueContext.create_dynamic_frame.from_options( connection_type="ZOHO", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v7", "INSTANCE_URL": "https://www.zohoapis.in/", "TRANSFER_MODE": "ASYNC" } ``` **Zoho CRM 欄位詳細資訊**： Zoho CRM 提供端點，可動態擷取支援實體的中繼資料。因此，運算子支援是在資料類型層級擷取的。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/zoho-crm-reading-from-entities.html) ## 分區查詢 非同步模式中不支援分區。 **基於篩選條件的分區 (同步模式)**： 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 Datetime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值的範例： ``` "2024-09-30T01:01:01.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 範例： ``` zoho_read = glueContext.create_dynamic_frame.from_options( connection_type="zohocrm", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v7", "PARTITION_FIELD": "Created_Time" "LOWER_BOUND": "2022-01-01T01:01:01.000Z" "UPPER_BOUND": "2024-01-01T01:01:01.000Z" "NUM_PARTITIONS": "10" } ``` # Zoho CRM 連線選項 以下是 Zoho CRM 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Zoho CRM 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Zoho CRM 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。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。有效的 Zoho CRM 執行個體 URL。 + `TRANSFER_MODE`(String) - 用於指示是否應在非同步模式下執行查詢。 # Zoho CRM 連接器的限制和備註 以下是 Zoho CRM 連接器的限制或備註： + 使用 API 版本 v7，最多可以擷取 100,000 筆記錄。請參閱 [Zoho 文件](https://www.zoho.com/crm/developer/docs/api/v7/get-records.html)。 + 對於 Event 實體，會顯示標籤 "Meeting"，如 [Zoho 文件](https://www.zoho.com/crm/developer/docs/api/v7/modules-api.html)所述。 + 對於「選取所有功能」： + 對於 GET 和 POST 呼叫，最多可以從 SaaS 中擷取 50 個欄位。 + 如果想要獲取不屬於前 50 個欄位的某些特定欄位的資料，則需要手動提供所選欄位的清單。 + 如果選取超過 50 個欄位，則會修剪 50 個欄位以外的任何欄位，並在 Amazon S3 中包含 null 資料。 + 如果是篩選條件表達式，若使用者提供的 50 個欄位清單不包含 "id" 和 "Created\$1Time"，則會引發自訂例外狀況，以提示使用者包含這些欄位。 + 即使具有相同的資料類型，篩選條件運算子也可能因欄位而有所不同。因此，必須為 SaaS 平台中觸發錯誤的任何欄位手動指定不同的運算子。 + 對於「排序依據」功能： + 如果沒有篩選條件表達式，則只能按單一欄位對資料進行排序，而當套用篩選條件表達式時，可以按多個欄位對資料進行排序。 + 如果未指定所選欄位的排序順序，則預設會以遞增順序擷取資料。 + 支援 Zoho CRM 連接器的區域為美國、歐洲、印度、澳洲和日本。 + 非同步讀取功能[限制：](https://www.zoho.com/crm/developer/docs/api/v7/bulk-read/limitations.html) + 非同步模式中不支援限制排序依據和分區。 + 在非同步模式中，我們最多可以傳輸 500 頁的資料，每頁 200,000 筆記錄。 + 在一分鐘間隔內，僅允許下載 10 個請求。當超過下載限制時，系統會傳回 HTTP 429 錯誤，並將所有下載請求暫停一分鐘，然後才能繼續處理。 + 完成大量任務後，只能在一天內存取可下載的檔案。之後，就無法透過端點存取檔案。 + 透過端點最多可提供 200 個選取欄位。如果在端點中指定超過 200 個選取欄位，系統會自動匯出該模組的所有可用欄位。 + Bulk Read API 不支援在任何模組中建立的外部欄位。 + 透過此 API 端點不支援排序和 `Group_by` 子句。 + 只有當合規設定中的**透過 API 限制資料存取**選項**停用**時，才會擷取具有敏感運作狀態資料的欄位值。如果啟用該選項，則結果中的值將為**空**。 + 篩選/條件限制 + 可在查詢中使用的條件數目上限為 25。 + 不支援多行文字欄位的篩選/條件。 # 連線至 Zoom Meetings Zoom Meetings 是一種以雲端為基礎的視訊會議平台，可用於視訊會議、音訊會議、網路研討會、會議錄音和即時聊天。 **Topics** + [AWS Glue 支援 Zoom 會議](zoom-meetings-support.md) + [包含用於建立和使用連線的 API 操作的政策](zoom-meetings-configuring-iam-permissions.md) + [設定 Zoom Meetings](zoom-meetings-configuring.md) + [設定 Zoom Meetings 用戶端應用程式](zoom-meetings-configuring-client-app.md) + [設定 Zoom Meetings 連線](zoom-meetings-configuring-connections.md) + [從 Zoom Meetings 實體中讀取](zoom-meetings-reading-from-entities.md) + [Zoom Meetings 連線選項](zoom-meetings-connection-options.md) + [Zoom Meetings 限制](zoom-meetings-limitations.md) # AWS Glue 支援 Zoom 會議 AWS Glue 支援 Zoom 會議，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Zoom Meetings 查詢資料。 **支援作為目標？** 否。 **支援的 Zoom Meetings API 版本** 支援下列 Zoom Meetings API 版本： +   v2 # 包含用於建立和使用連線的 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 主控台的使用者。 # 設定 Zoom Meetings 您必須先符合下列要求，才能使用 從 Zoom Meetings AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您擁有一個 Zoom Meetings 帳戶。 + 您的 Zoom 帳戶已啟用 API 存取。 + 您已在 Zoom Meetings 帳戶中建立 OAuth2 應用程式。此整合提供登入資料， AWS Glue 用於在對您的帳戶進行驗證呼叫時安全地存取您的資料。如需詳細資訊，請參閱[設定 Zoom Meetings 用戶端應用程式](zoom-meetings-configuring-client-app.md)。 如果您符合這些要求，就可以 AWS Glue 連線到 Zoom Meetings 帳戶。對於一般連線，您不需要在 Zoom Meetings 中執行任何其他操作。 # 設定 Zoom Meetings 用戶端應用程式 1. 登入 Zoom App Marketplace。 1. 選擇**開發** > **建置應用程式**。 1. 針對基於 OAuth 2.0 的應用程式，選擇**一般應用程式**。 1. 在**基本資訊**頁面中，新增或更新應用程式的相關資訊，例如應用程式名稱、應用程式管理方式、應用程式憑證和 OAuth 資訊。 1. 在**選取應用程式管理方法**區段中，確認您希望如何管理應用程式： 1. **由管理員管理**：帳戶管理員新增和管理應用程式 1. **由使用者管理**：個別使用者新增和管理應用程式。應用程式只能存取使用者授權的資料。 1. **應用程式憑證**：建置流程會自動為您的應用程式產生應用程式憑證 (用戶端 ID 和用戶端機密)。 1. 在「OAuth 資訊」區段中，為您的應用程式設定 OAuth。 1. **OAuth 重新導向 URL** (必要)：輸入重新導向 URL 或端點，以在應用程式和 Zoom 之間設定 OAuth。 1. **使用嚴格模式 URL** (選用) 1. **子網域檢查** (選用) 1. **OAuth 允許清單** (必要)：新增 Zoom 應允許作為 OAuth 流程有效重新導向的唯一 URL。 1. 在**範圍**頁面中，選取允許應用程式呼叫的 Zoom API 方法。這些範圍會定義您的使用者可使用哪些資訊和功能。選取下列精細範圍： + user:read:list\$1users:admin + zoom\$1rooms:read:list\$1rooms:admin + group:read:list\$1members:admin + group:read:administrator:admin + group:read:list\$1groups:admin + report:read:admin + role:read:list\$1roles, role:read:list\$1roles:admin 新增範圍後，請選擇**繼續**，即可使用應用程式。 如需有關 OAuth 2.0 設定的詳細資訊，請參閱[整合 (OAuth 應用程式)](https://developers.zoom.us/docs/integrations/)。 # 設定 Zoom Meetings 連線 Zoom Meetings 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。授予類型決定 如何與 Zoom Meetings AWS Glue 通訊，以請求存取您的資料。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。在透過 AWS Glue 主控台建立連線時使用。建立連線的使用者需要為 Zoom Meetings 用戶端應用程式提供 OAuth 相關資訊，例如用戶端 ID 和用戶端機密。 AWS Glue 主控台會將使用者重新導向至 Zoom，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Zoom Meetings 執行個體。 + 使用者仍然可以選擇在 Zoom Meetings 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Zoom Meetings 以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。 + 如需有關建立授權碼 OAuth 流程之連線應用程式的公有 Zoom Meetings 文件，請參閱[使用 OAuth 2.0](https://developers.zoom.us/docs/api/using-zoom-apis/#using-oauth-20)。 若要設定 Zoom Meetings 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須為 中的連線建立秘密 AWS Glue。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 選取**連線類型**時，請選取 Zoom Meetings。 1. 提供您要連線的 Zoom Meetings 環境。 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`。 # 從 Zoom Meetings 實體中讀取 **必要條件** 您想要從中讀取的 Zoom Meetings 物件。需要物件名稱，例如 `Group` 或 `Zoom Rooms`。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | Zoom Rooms | 否 | 是 | 否 | 是 | 否 | | Group | 否 | 否 | 否 | 是 | 否 | | 群組成員 | 是 | 是 | 否 | 是 | 否 | | 群組管理員 | 否 | 是 | 否 | 是 | 否 | | 報告 (每日) | 是 | 否 | 否 | 是 | 否 | | 角色 | 否 | 否 | 否 | 是 | 否 | | 使用者 | 是 | 是 | 否 | 是 | 否 | **範例**： ``` zoom_read = glueContext.create_dynamic_frame.from_options( connection_type="zoom", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "organization", "API_VERSION": "v2" } ) ``` **Zoom Meetings 實體和欄位詳細資訊**： Zoom Meetings 會在選取的實體下動態載入可用欄位。視欄位的資料類型而定，其支援下列篩選條件運算子。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/zoom-meetings-reading-from-entities.html) ## 分區查詢 Zoom Meetings 不支援篩選條件型分區或記錄型分區。 # Zoom Meetings 連線選項 以下是 Zoom Meetings 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Zoom Meetings 實體的名稱。例如 `group`。 + `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Zoom Meetings Rest API 版本。該值將為 `v2`，因為 Zoom Meetings 目前僅支援 v2 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為所選實體選取的資料欄的以逗號分隔的資料欄清單。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 # Zoom Meetings 限制 以下是 Zoom Meetings 的限制或備註： + Zoom Meetings 不支援 orderby。 + Zoom Meetings 不支援基於篩選條件的分區，因為沒有欄位可以滿足必要的條件。 + Zoom Meetings 不支援記錄型分區，因為不支援分頁限制和基於位移的分頁。 # 使用自己的 JDBC 驅動程式新增 JDBC 連線 使用 JDBC 連線時，您可以使用自己的 JDBC 驅動程式。當 AWS Glue 爬蟲程式使用的預設驅動程式無法連線至資料庫時，您可以使用自己的 JDBC 驅動程式。例如，如果您想將 SHA-256 與 Postgres 資料庫搭配使用，而較舊的 Postgres 驅動程式不支援此功能，則可以使用自己的 JDBC 驅動程式。 ## 支援的資料來源 | 支援的資料來源 | 不支援的資料來源 | | --- | --- | | MySQL | Snowflake | | Postgres | | | Oracle | | | Redshift | | | SQL Server | | | Aurora\$1 | | \$1 如果正在使用原生的 JDBC 驅動程式，則支援此功能。並非所有驅動程式功能都可供運用。 ## 將 JDBC 驅動程式新增至 JDBC 連線 **注意** 如果您選擇使用自己的 JDBC 驅動程式版本， AWS Glue 爬蟲程式將使用 AWS Glue 任務和 Amazon S3 儲存貯體中的資源，以確保您提供的驅動程式在您的環境中執行。帳戶中將反映資源的額外使用量。 AWS Glue 爬蟲程式和任務的成本在計費中的 AWS Glue 類別下。此外，提供您的 JDBC 驅動程式，並不代表爬蟲程式能夠運用驅動程式的所有功能。 **若要將自己的 JDBC 驅動程式新增至 JDBC 連線：** 1. 將 JDBC 驅動程式檔案新增至 Amazon S3 位置。您可以建立儲存貯體和/或資料夾，或使用現有的儲存貯體和/或資料夾。 1. 在 AWS Glue 主控台中，選擇 **Data Catalog** 下左側選單中的**連線**，然後建立新的連線。 1. 填寫**連線屬性**欄位，然後選擇 JDBC 作為**連線類型**。 1. 在**連線存取**中，輸入 **JDBC URL** 和 **JDBC 驅動程式類別名稱**：*選用*。驅動程式類別名稱必須是 AWS Glue 爬蟲程式支援的資料來源。 ![\[螢幕擷取畫面顯示已選取 JDBC 的資料來源，以及「新增資料來源」視窗中的連線。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/add-connection-connection-access.png) 1. 選擇 **JDBC 驅動程式 Amazon S3 路徑**中 JDBC 驅動程式所在的 Amazon S3 路徑：*選用*欄位。 1. 如果輸入使用者名稱和密碼或機密，請填寫「憑證」類型的欄位。完成時，選擇**建立連線**。 **注意** 目前不支援測試連線。使用您提供的 JDBC 驅動程式針對資料來源進行網路爬取時，爬蟲程式會略過此步驟。 1. 將新建立的連線新增至爬蟲程式。在 AWS Glue 主控台中，選擇 **Data Catalog** 下左側選單中的**爬蟲程式**，然後建立新的爬蟲程式。 1. 在**新增爬蟲程式**精靈的步驟 2 中，選擇**新增資料來源**。 ![\[螢幕擷取畫面顯示已選取 JDBC 的資料來源，以及「新增資料來源」視窗中的連線。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/add-crawler-add-data-source.png) 1. 選擇 **JDBC** 作為資料來源，然後選擇在先前步驟中建立的連線。完成 1. 若要搭配 AWS Glue 爬蟲程式使用您自己的 JDBC 驅動程式，請將下列許可新增至爬蟲程式使用的角色： + 授予下列任務動作的許可：`CreateJob`、`DeleteJob`、`GetJob`、`GetJobRun`、`StartJobRun`。 + 授予 IAM 動作的許可：`iam:PassRole` + 授予 Amazon S3 動作的許可：`s3:DeleteObjects`、`s3:GetObject`、`s3:ListBucket`、`s3:PutObject`。 + 在 IAM 政策中授予服務主體對儲存貯體/資料夾的存取權。 IAM 政策範例： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/driver-parent-folder/driver.jar", "arn:aws:s3:::amzn-s3-demo-bucket" ] } ] } ``` ------ AWS Glue 爬蟲程式會建立兩個資料夾：\$1glue\$1job\$1crawler 和 \$1crawler。 如果驅動程式 jar 位於 `s3://amzn-s3-demo-bucket/driver.jar"` 資料夾中，請新增下列資源： ``` "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/_glue_job_crawler/*", "arn:aws:s3:::amzn-s3-demo-bucket/_crawler/*" ] ``` 如果驅動程式 jar 位於 `s3://amzn-s3-demo-bucket/tmp/driver/subfolder/driver.jar"` 資料夾中，請新增下列資源： ``` "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/tmp/_glue_job_crawler/*", "arn:aws:s3:::amzn-s3-demo-bucket/tmp/_crawler/*" ] ``` 1. 如果您使用的是 VPC，則必須建立介面 AWS Glue 端點並將其新增至路由表，以允許存取端點。如需詳細資訊，請參閱[建立 的介面 VPC 端點 AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html#vpc-endpoint-create) 1. 如果您在 Data Catalog 中使用加密，請建立 AWS KMS 介面端點並將其新增至您的路由表。如需詳細資訊，請參閱[為 AWS KMS建立 VPC 端點](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html#vpce-create-endpoint)。