預先發布版

這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

Google 日曆

支援的版本

這個連接器支援 Google 日曆 REST API。

事前準備

在 Google Cloud 專案中，執行下列工作：

• 確認已設定網路連線。詳情請參閱「網路連線」。
• 將 roles/connectors.admin IAM 角色授予設定連線器的使用者。
• 將 roles/secretmanager.viewer 和 roles/secretmanager.secretAccessor 身分與存取權管理角色授予要用於連結器的服務帳戶
• 啟用 secretmanager.googleapis.com (Secret Manager API) 和 connectors.googleapis.com (Connectors API)。 詳情請參閱「啟用服務」。

設定連接器

連線專屬於資料來源。也就是說，如果您有多個資料來源，則必須為每個資料來源建立個別的連線。如要建立連結，請按照下列步驟操作：

1. 在 Cloud 控制台中，前往「Integration Connectors」>「Connections」頁面，然後選取或建立 Google Cloud 專案。

   前往「Connections」(連線) 頁面

2. 按一下「+ 建立新連線」，開啟「建立連線」頁面。
3. 在「位置」部分中，完成下列步驟：
   1. 區域：從下拉式清單中選取位置。

      如需所有支援地區的清單，請參閱「位置」一文。

   2. 點選「下一步」。
4. 在「連線詳細資料」部分，完成下列步驟：
   1. 連接器：從可用連接器清單中選取「Google 日曆」。
   2. 連接器版本：從可用版本清單中選取連接器版本。
   3. 在「連線名稱」欄位中，輸入連線執行個體的名稱。連線名稱可使用小寫英文字母、數字或連字號，名稱開頭須為英文字母，結尾須為英文字母或數字，且長度不得超過 49 個半形字元。
   4. 說明：輸入連線執行個體的說明。
   5. 或者，可啟用 Cloud Logging，然後選取記錄層級。記錄層級預設為 Error。
   6. 服務帳戶：選取具備必要角色的服務帳戶。
   7. 連線逾時：視需要輸入連線逾時時間 (以秒為單位)。
   8. 視需要設定「連線節點設定」：
      • 節點數量下限：輸入連線節點數量下限。
      • 節點數量上限：輸入連線節點數量上限。

      節點是用來處理交易的連線單位 (或備用資源)。連線處理的交易量越多，就需要越多節點；反之，處理的交易量越少，需要的節點就越少。如要瞭解節點對連線器定價的影響，請參閱「 連線節點定價」。如未輸入任何值，系統預設會將節點下限設為 2 (提高可用性)，節點上限則設為 50。

   注意：只有預付費方案客戶可以自訂連線節點值。
   9. + 新增標籤：按一下這個選項，即可為連線新增鍵/值組合形式的標籤。
   10. 點選「下一步」。
5. 在「Authentication」(驗證) 部分，輸入驗證詳細資料。
   1. 選取「驗證類型」，然後輸入相關詳細資料。

      Google 日曆連線支援下列驗證類型：

      • 服務帳戶驗證
      • OAuth 2.0 - JWT 持有者
      • OAuth 2.0 - 授權碼

      如要瞭解如何設定這些驗證類型，請參閱「設定驗證」。

   2. 點選「下一步」。
6. 檢查：檢查連線和驗證詳細資料。
7. 點選「建立」。

設定驗證機制

根據要使用的驗證方式輸入詳細資料。

• 服務帳戶驗證：這類驗證不需要其他設定。系統會使用您在「連線詳細資料」部分選取的服務帳戶進行驗證。
• OAuth 2.0 - JWT 持有者
  • JWT 憑證：選取用於 JWT 驗證的憑證。
  • 密鑰版本：輸入 JWT 憑證的密鑰版本。
  • JWT 主體：輸入 JWT 主體。
• OAuth 2.0 - 授權碼
  • 「Client ID」(用戶端 ID)：輸入用於 OAuth 驗證的用戶端 ID。
  • 範圍：輸入所需範圍的清單。
  • 用戶端密鑰：輸入用於 OAuth 驗證的用戶端密鑰。
  • 密鑰版本：輸入用戶端密鑰的密鑰版本。

連線設定範例

本節列出您在建立連線時設定的各個欄位範例值。

服務帳戶連結類型

欄位名稱	詳細資料
位置	us-central1
連接器	Google 日曆
連接器版本	1
連線名稱	service-account-auth
啟用 Cloud Logging	是
服務帳戶	iam.gserviceaccount.com
節點數量下限	2
節點數量上限	50
驗證	是
服務帳戶驗證	是

OAuth 2.0 - JWT 持有者連線類型

欄位名稱	詳細資料
位置	us-central1
連接器	Google 日曆
連接器版本	1
連線名稱	jwt-bearer-auth
啟用 Cloud Logging	是
服務帳戶	iam.gserviceaccount.com
節點數量下限	2
節點數量上限	50
驗證	是
OAuth 2.0 - JWT 持有者	是
JWT 憑證	projects/google-cloud-project/secrets/jwt-cert/versions/1
密鑰版本	1

OAuth 2.0 - 授權碼連線類型

欄位名稱	詳細資料
位置	us-central1
連接器	Google 日曆
連接器版本	1
連線名稱	gcpcloud-googlecalendar-rest-conn
啟用 Cloud Logging	是
服務帳戶	iam.gserviceaccount.com
節點數量下限	2
節點數量上限	50
驗證	是
用戶端 ID	60875425788659-mt0cm1tguyiagvst468fvaw7.apps.googleusercontent.com
範圍	https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/drive
用戶端密鑰	ygdruoX-Rtyah9gzkdZc-7CB0Eng9hyaufD0VD
密鑰版本	1

系統限制

Google 日曆連接器每個節點每秒最多可處理 2 筆交易，超過此上限的交易都會遭到節流。根據預設，整合連接器會為連線分配 2 個節點 (提高可用性)。

如要瞭解 Integration Connectors 適用的限制，請參閱「限制」一文。

注意：整合連接器節點的數量會根據用量自動動態調整。不過，如果您想預留大量容量，不必等待自動調度資源，可以調整連線的節點數量下限。如要處理連線的更多交易，就需要更多節點。反之，如果連線處理的交易較少，則需要的節點也較少。如要設定節點值，請按照下列步驟操作：

• 如果您是隨用隨付方案客戶，請在編輯連線頁面中設定節點的最小值和最大值。
• 如果您是訂閱型客戶，請與支援團隊聯絡。

節點可處理的最大交易量取決於多項因素。因此，建議您先檢查後端系統是否已完成最佳化設定，可處理所需流量，再調整節點下限以提升輸送量。

在整合服務中使用 Google 日曆連線

建立連線後，Apigee Integration 和 Application Integration 都會提供該連線。您可以在整合中透過「連接器」工作使用連線。

• 如要瞭解如何在 Apigee Integration 中建立及使用連線器工作，請參閱「連線器工作」。
• 如要瞭解如何在 Application Integration 中建立及使用連線器工作，請參閱連線器工作。

實體作業範例

本節說明如何使用這個連接器執行部分 實體作業。

範例 - 列出所有日曆

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Calendars。
3. 選取「List」作業，然後按一下「完成」。
4. 在「連線器」工作的「工作輸入」部分，您可以根據客戶需求設定 filterClause。

您必須使用單引號 (') 括住 filterClause 的值。

您可以使用 filterClause，根據資料欄篩選記錄。

範例 - 取得日曆詳細資料

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Calendars。
3. 選取「Get」作業，然後按一下「完成」。
4. 將 entityId 設為要傳遞的鍵 "[e-mail]"。
5. 如要設定 entityId，請在「資料對應」的「資料對應工具」部分，按一下「開啟資料對應編輯器」，然後在「輸入值」欄位中輸入 "[e-mail]"，並將 entityId 設為本機變數。

entityId 的值應直接傳遞，例如 "[e-mail]"。這裡的 "[e-mail]" 是唯一主鍵值，必須傳遞。

在某些情況下，如果實體使用兩個複合鍵，傳遞 entityId 可能會擲回錯誤。在這種情況下，您可以使用 filterClause 傳遞值，例如 id='[e-mail]'。

範例 - 刪除日曆

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Calendars。
3. 選取「Delete」作業，然後按一下「完成」。
4. 將 entityId 設為 "[e-mail]"，這是要傳遞的鍵。如要設定 entityId，請在「資料對應」的「資料對應工具」部分，按一下「開啟資料對應編輯器」，然後在「輸入值」欄位中輸入 "[e-mail]"，並將 entityId 設為本機變數。

   如果實體有兩個複合式商家或主鍵，而非指定 entityId，您也可以將 filterClause 設為 id='[e-mail]'。

範例 - 建立日曆

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Calendars。
3. 選取「Create」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "New calendar"
   }
   

   如果整合成功，calendar 工作的 connectorOutputPayload 回應參數值會類似於下列內容：

   {
     "Id": "c_[e-mail]"
   }
   

範例 - 在日曆中建立活動

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 AllCalendars。
3. 選取「Create」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "New event",
     "CalendarId": "c_[e-mail]",
     "StartDate": "2025-09-01",
     "EndDate": "2025-09-02"
   }
   

   如果整合成功，calendar 工作的 connectorOutputPayload 回應參數值會類似於下列內容：

   {
     "Id": "fnf0p7292pbm2buk59ubc1a37k",
     "CalendarId": null
   }
   

範例 - 在主要日曆中建立活動

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取電子郵件 ID。
3. 選取「Create」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "new event for my calendar",
     "CalendarId": "[e-mail]",
     "StartDate": "2025-09-01",
     "EndDate": "2025-09-02"
   }
   

   如果整合成功，AllCalendars 工作的 connectorOutputPayload 回應參數值會類似於下列內容：

   {
     "Id": "fnf0p7292pbm2buk59ubc1a37k",
     "CalendarId": null
   }
   

範例 - 在日曆中建立活動類型

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 AllCalendars。
3. 選取「Create」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "EventType": "outOfOffice",
     "Summary": "outOfOffice",
     "CalendarId": "[e-mail]",
     "StartDateTime": "2025-09-03 14:00:00",
     "EndDateTime": "2025-09-03 15:00:00"
   }
   

   如果整合成功，AllCalendars 工作的 connectorOutputPayload 回應參數值會類似於下列內容：

   {
     "Id": "fnf0p7292pbm2buk59ubc1a37k",
     "CalendarId": null
   }
   

範例 - 在日曆中建立週期性活動

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 AllCalendars。
3. 選取「Create」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "Google Cloud Recurring event",
     "CalendarId": "[e-mail]",
     "StartDateTime": "2025-11-2 14:00:00",
     "EndDateTime": "2025-11-2 14:30:00",
     "Recurrences": "RRULE:FREQ=WEEKLY;BYDAY=TH;COUNT=5",
     "StartDateTimeZone": "America/Los_Angeles",
     "EndDateTimeZone": "America/Los_Angeles"
   }
   

   如果整合成功，AllCalendars 工作的 connectorOutputPayload 回應參數值會類似於下列內容：

   {
     "Id": "fnf0p7292pbm2buk59ubc1a37k",
     "CalendarId": null
   }
   

範例 - 更新日曆詳細資料

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Calendars。
3. 選取「Update」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "Updated from Google Cloud"
   }
   

5. 在資料對應工具中，將 entityId 設為日曆的實體。
6. 如要設定 entityId，請按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 entityId 設為區域變數。

   除了指定 entityId，您也可以將 filterClause 設為 id='[e-mail]'。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
     "Id": "c_[e-mail]"
   }
   

範例 - 更新所有日曆詳細資料

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 AllCalendars。
3. 選取「Update」作業，然後按一下「完成」。
4. 在「資料對應」工作的「資料對應器」部分，按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 connectorInputPayload 設為本機變數。

   {
     "Summary": "Great event"
   }
   

5. 在資料對應工具中，將 entityId 設為 AllCalendars 的實體。
6. 如要設定 entityId，請按一下 Open Data Mapping Editor，然後在 Input Value 欄位中輸入類似下列的值，並將 entityId 設為區域變數。

   除了指定 entityId，您也可以將 filterClause 設為 Summary='New sep event'。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
     "Id": "fnf0p7292pbm2buk59ubc1a37k",
     "CalendarId": null
   }
   

向 Google Cloud 社群尋求協助

如要發布問題及討論這個連接器，請前往 Cloud 論壇的 Google Cloud 社群。

後續步驟

• 瞭解如何暫停及恢復連線。
• 瞭解如何監控連結器用量。
• 瞭解如何查看連接器記錄。