本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 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 和精細度預設值。請參閱上面的表格。