Gmail
透過 Gmail 連接器，您可以在 Gmail 中執行讀取和刪除作業。
支援的版本
這個連接器支援 Gmail REST API。
事前準備
使用 Gmail 連接器前，請先完成下列工作：
- 在 Google Cloud 專案中：
- 將 roles/connectors.admin IAM 角色授予設定連線器的使用者。
- 將下列 IAM 角色授予要用於連接器的服務帳戶：
roles/secretmanager.viewerroles/secretmanager.secretAccessor
服務帳戶是特殊的 Google 帳戶類型，主要用於代表需要驗證且必須取得授權才能存取 Google API 資料的非人類使用者。如果您沒有服務帳戶，請建立服務帳戶。詳情請參閱「建立服務帳戶」。
- 啟用下列服務：
secretmanager.googleapis.com(Secret Manager API)connectors.googleapis.com(Connectors API)
如要瞭解如何啟用服務，請參閱「啟用服務」。
如果先前未啟用這些服務或權限，系統會在設定連結器時提示您啟用。
設定連接器
連線專屬於資料來源。也就是說，如果有多個資料來源，您必須為每個資料來源建立個別的連結。如要建立連結，請按照下列步驟操作：
- 在 Cloud 控制台中，前往「Integration Connectors」>「Connections」頁面，然後選取或建立 Google Cloud 專案。
- 按一下「+ 建立新連線」，開啟「建立連線」頁面。
- 在「位置」部分，完成下列步驟：
- 區域：從下拉式清單中選取位置。
如需所有支援區域的清單，請參閱「地點」一文。
- 點選「下一步」。
- 區域：從下拉式清單中選取位置。
- 在「連線詳細資料」部分，完成下列步驟：
- 連接器：從可用連接器清單中選取「Gmail」。
- 連接器版本：從可用版本清單中選取連接器版本。
- 在「連線名稱」欄位中，輸入連線執行個體的名稱。連線名稱可包含小寫英文字母、數字或連字號，名稱開頭須為英文字母，結尾須為英文字母或數字，且長度不得超過 49 個半形字元。
- 說明：輸入連線執行個體的說明。
- 或者，可啟用 Cloud Logging，然後選取記錄層級。記錄層級預設為
Error。 - 服務帳戶：選取具備必要角色的服務帳戶。
- 視需要設定「連線節點設定」：
- 節點數下限：輸入連線節點的數量下限。
- 節點數上限：輸入連線節點數上限。
節點是用來處理交易的連線單位 (或備用資源)。如要處理更多連線交易，就需要更多節點；反之，如要處理較少的交易，則需要較少的節點。如要瞭解節點對連線器價格的影響，請參閱「 連線節點的定價」。如未輸入任何值，系統預設會將節點下限設為 2 (提高可用性)，節點上限則設為 50。
- 「+ 新增標籤」：按一下這個按鈕，即可新增鍵/值組合形式的連線標籤。
- 點選「下一步」。
-
在「Authentication」(驗證) 部分，輸入驗證詳細資料。
- 選取「驗證類型」，然後輸入相關詳細資料。
Gmail 連結支援下列驗證類型：
- 服務帳戶驗證
- OAuth 2.0 - JWT 持有者
- OAuth 2.0 - 授權碼
如要瞭解如何設定這些驗證類型，請參閱「設定驗證」。
- 點選「下一步」。
- 選取「驗證類型」，然後輸入相關詳細資料。
- 檢查：檢查連結和驗證詳細資料。
- 點選「建立」。
設定驗證機制
根據要使用的驗證方式輸入詳細資料。
- 服務帳戶驗證：這種驗證類型不需要其他設定。系統會使用您在「連線詳細資料」部分選取的服務帳戶進行驗證。
-
OAuth 2.0 - JWT 持有者
- JWT 憑證：選取用於 JWT 驗證的憑證。
- 密鑰版本：輸入 JWT 憑證的密鑰版本。
- JWT 主體：輸入 JWT 主體。
- 啟用驗證覆寫：啟用後即可覆寫驗證。
-
OAuth 2.0 - 授權碼
- 用戶端 ID：輸入用於 OAuth 驗證的用戶端 ID。
- 範圍：輸入所需範圍的清單。
- 用戶端密鑰：用於 OAuth 驗證的用戶端密鑰。
- 密鑰版本：輸入用戶端密鑰的密鑰版本。
- 啟用驗證覆寫：啟用後即可覆寫驗證。
連線設定範例
本節列出您在建立連線時設定的各個欄位範例值。
OAuth 2.0 - JWT 持有者連線類型
| 欄位名稱 | 詳細資料 |
|---|---|
| 位置 | asia-east1 |
| 連接器 | Gmail |
| 連接器版本 | 1 |
| 連線名稱 | gmail-jwt-conn |
| 啟用 Cloud Logging | true |
| 服務帳戶 | my-service-account@my-project.iam.gserviceaccount.com |
| 節點數量下限 | 2 |
| 節點數量上限 | 50 |
| 驗證 | OAuth 2.0 - JWT 持有者 |
| JWT 憑證 | JWT 憑證 |
| 密鑰版本 | 1 |
OAuth 2.0 - 授權碼連線類型
| 欄位名稱 | 詳細資料 |
|---|---|
| 位置 | us-central1 |
| 連接器 | Gmail |
| 連接器版本 | 1 |
| 連線名稱 | gmail-auth-conn |
| 啟用 Cloud Logging | 是 |
| 服務帳戶 | my-service-account@my-project.iam.gserviceaccount.com |
| 節點數量下限 | 2 |
| 節點數量上限 | 50 |
| 驗證 | OAuth 2.0 - 授權碼 |
| 用戶端 ID | 60875425788659-mt0cm1tguyiagvst468fvaw7.apps.googleusercontent.com |
| 範圍 | https://mail.google.com/ |
| 用戶端密鑰 | ygdruoX-Rtyah9gzkdZc-7CB0Eng9hyaufD0VD |
| 密鑰版本 | 1 |
系統限制
每個節點的 Gmail 連接器每秒最多可處理 1 筆交易，超出此限制的交易都會遭到節流。根據預設，Integration Connectors 會為連線分配 2 個節點 (提高可用性)。
如要瞭解 Integration Connectors 適用的限制，請參閱「限制」一文。
在整合服務中使用 Gmail 連線
建立連線後，Apigee Integration 和 Application Integration 都會提供該連線。您可以在整合中透過「連接器」工作使用連線。
- 如要瞭解如何在 Apigee Integration 中建立及使用連接器工作，請參閱「連接器工作」。
- 如要瞭解如何在 Application Integration 中建立及使用連接器工作，請參閱連接器工作。
動作
本節說明如何在這個連接器中執行部分動作。
SendMailMessages 動作
這項動作會傳送 Gmail 郵件。
SendMailMessages 動作的輸入參數
| 參數名稱 | 資料類型 | 必填 | 說明 |
|---|---|---|---|
| 收件者 | 字串 | 是 | 主要收件者的電子郵件地址。如有多位收件者，請以半形逗號分隔。 |
| AttachmentHasBytes | 字串 | 否 | 如果附件內容是以 AttachmentContentBytes (Base64 編碼) 提供，請將此屬性設為 true；如果內容是以字串形式在 AttachmentContent 中提供，請設為 false。預設值為 false。 |
| AttachmentFileName | 字串 | 否 | 要附加的檔案名稱。如果 AttachmentHasBytes 為 false 或未提供，系統就會使用這個參數。 |
| 主旨 | 字串 | 是 | 電子郵件主旨行。 |
| AttachmentContent | 字串 | 否 | 要附加的檔案字串內容。如果 AttachmentHasBytes 設為 false 或未提供，系統就會使用這個參數。 |
| 密件副本 | 字串 | 否 | 密件副本收件者的電子郵件地址。如有多位收件者，請以半形逗號分隔。 |
| AttachmentContentBytes | 字串 | 否 | 要附加的檔案內容 (Base64 編碼位元組)。如果 AttachmentHasBytes 設為 true，系統就會使用這項參數。 |
| CC | 字串 | 否 | 副本收件者的電子郵件地址。如有多位收件者，請以半形逗號分隔。 |
| 內容 | 字串 | 是 | 電子郵件訊息的主要內容。 |
| AttachmentPath | 字串 | 否 | 以半形逗號分隔的本機檔案路徑清單，用於附加至電子郵件。 |
如要瞭解如何設定 SendMailMessages 動作，請參閱範例。
DownloadAttachment 動作
這項動作會下載 Gmail 中的附件。
DownloadAttachment 動作的輸入參數
| 參數名稱 | 資料類型 | 必填 | 說明 |
|---|---|---|---|
| MessageId | 字串 | 是 | 電子郵件的 ID。 |
| DownloadLocation | 字串 | 否 | 附件的儲存位置。 |
| FileStream | 字串 | 否 | 輸出串流的執行個體，檔案資料會寫入其中。 |
| AttachmentId | 字串 | 否 | 附件的 ID。如果指定 FileStream，則必須提供這個欄位。 |
如要瞭解如何設定 DownloadAttachment 動作，請參閱範例。
動作範例
本節說明如何在這個連接器中執行部分動作。
範例 - 傳送 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Actions。 - 選取「
SendMailMessages」動作，然後按一下「完成」。 - 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下
connectorInputPayload，然後在Default Value欄位中輸入類似下列的值：{ "To": "testbristleconeemail@gmail.com", "Subject": "Data MapperCheck", "Content": "Gmail", }
如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：
[{
"Id": "199334f660ff462a"
}]
範例 - 傳送含有 JPG 附件的 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Actions。 - 選取「
SendMailMessages」動作，然後按一下「完成」。 - 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下
connectorInputPayload，然後在Default Value欄位中輸入類似下列的值：{ "To": "testbristleconeemail@gmail.com", "Subject": "Data Mapper Email Sep10 JPG", "Content": "Gmail", "AttachmentFileName": "TestSep10.jpg", "AttachmentContentBytes": "/9j/4AAQSkZJRgABAQEBLAEsAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCANUBdwDAREAAhEBAxEB/8QAHgABAAAGAwEAAAAAAAAAAAAAAAEDBAcICQIFBgr/xABsEAABAwMCBAMFBQQHAwUJACMBAgMEAAURBgcIEiExCRNBChQiUWEVIzJxgUJSkaEWFzNicrHBJEPRNFOCkqIYJTlEY4O14fDxJmRzdXZ3k7PCNTY4haOytLYZN1RVV8NIVmV0eJSWpNLT4v/EAB0BAQABBAMBAAAAAAAAAAAAAAAHAQQFBgIDCAn/xABXEQABAwURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIlESiJREoiURKIv/Z", "AttachmentHasBytes": true }
如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：
[{
"Id": "199334f660ff462a"
}]
範例 - 傳送含有 PDF 附件的 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Actions。 - 選取「
SendMailMessages」動作，然後按一下「完成」。 - 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下
connectorInputPayload，然後在Default Value欄位中輸入類似下列的值：{ "To": "testbristleconeemail@gmail.com", "Subject": "Data Mapper Email Sep10", "Content": "Gmail", "AttachmentFileName": "TestSep10.pdf", "AttachmentContent": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nD2OywoCMQxF9/mKu3YRk7bptDAIDuh+oOAP+AAXgrOZ37etjmSTe3ISIljpDYGwwrKxRwrKGcsNlx1e31mt5UFTIYucMFiqcrlif1ZobP0do6g48eIPKE+ydk6aM0roJG/RegwcNhDr5tChd+z+miTJnWqoT/3oUabOToVmmvEBy5IoCgplbmRzdHJlYW0KZW5kb2JqCgozIDAgb2JqCjEzNAplbmRvYmoKCjUgMCBvYmoKPDwvTGVuZ3RoIDYgMCBSL0ZpbHRlci9GbGF0ZURlY29kZS9MZW5ndGgxIDIzMTY0Pj4Kc3RyZWFtCnic7Xx5fFvVlf+59z0tdrzIu7xFz1G8Kl7i2HEWE8vxQlI3iRM71A6ksSwrsYptKZYUE9omYStgloZhaSlMMbTsbSPLAZwEGgNlusxQ0mHa0k4Z8muhlJb8ynQoZVpi/b736nkjgWlnfn/8Pp9fpNx3zz33bPecc899T4oVHA55KIEOkUJO96DLvyQxM5WI/omIpbr3BbU/3J61FPBpItOa3f49g1948t/vI4rLIzL8dM/A/t3vn77ZSpT0LlH8e/0eV98jn3k0mSj7bchY2Q/EpdNXm4hyIIOW9g8Gr+gyrq3EeAPGVQM+t+uw5VrQ51yBcc6g6wr/DywvGAHegbE25Br0bFR/ezPGR4kq6/y+QPCnVBYl2ijka/5hjz95S8kmok8kEFl8wDG8xQtjZhRjrqgGo8kcF7+I/r98GY5TnmwPU55aRIhb9PWZNu2Nvi7mRM9/C2flx5r+itA36KeshGk0wf5MWfQ+y2bLaSOp9CdkyxE6S3dSOnXSXSyVllImbaeNTAWNg25m90T3Rd+ii+jv6IHoU+zq6GOY/yL9A70PC/5NZVRHm0G/nTz0lvIGdUe/Qma6nhbRWtrGMslFP8H7j7DhdrqDvs0+F30fWtPpasirp0ZqjD4b/YDK6Gb1sOGVuCfoNjrBjFF31EuLaQmNckf0J9HXqIi66Wv0DdjkYFPqBiqgy+k6+jLLVv4B0J30dZpmCXy", "AttachmentHasBytes": true }
如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：
[{
"Id": "1993341d558d7b07"
}]
範例 - 傳送含有 TXT 附件的 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Actions。 - 選取「
SendMailMessages」動作，然後按一下「完成」。 - 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下
connectorInputPayload，然後在Default Value欄位中輸入類似下列的值：{ "To": "testbristleconeemail@gmail.com", "Subject": "Data Mapper Email Sep10", "Content": "Gmail", "AttachmentFileName": "TestSep10.txt", "AttachmentContent": "TestingwithAttachment", "AttachmentHasBytes": true }
如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：
[{
"Id": "1993341d558d7b07"
}]
範例 - 從 Gmail 下載附件
- 在
Configure connector task對話方塊中，按一下Actions。 - 選取「
DownloadAttachment」動作，然後按一下「完成」。 - 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下
connectorInputPayload，然後在Default Value欄位中輸入類似下列的值：{ "MessageId": "198acdcde5c09ce5" }
如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：
[{
"Success": "true",
"MessageId": "198acdcde5c09ce5",
"AttachmentId": "1",
"Size": "58005",
"Data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoYWJvdXQ6YmxhbmspCi9DcmVhdG9yIChNb3ppbGxhLzUuMCBcKFgxMTsgTGludXggeDg2XzY0XCkgQXBwbGVXZWJLaXQvNTM3LjM2IFwoS0hUTUwsIGxpa2UgR2Vja29cKSBIZWFkbGVzc0Nocm9tZS8xMzguMC4wLjAgU2FmYXJpLzUzNy4zNikKL1Byb2R1Y2VyIChTa2lhL1BERiBtMTM4KQovQ3JlYXRpb25EYXRlIChEOjIwMjUwODE1MDgwMDE2KzAwJzAwJykKL01vZERhdGUgKEQ6MjAyNTA4MTUwODAwMTYrMDAnMDAnKT4-CmVuZG9iagozIDAgb2JqCjw8L2NhIDEKL0JNIC9Ob3JtYWw-PgplbmRvYmo",
"Filename": "My_Store_404672162.pdf",
"@isoutervalue": null
}]
實體作業範例
本節說明如何在這個連接器中執行部分實體作業。
範例 - 列出所有 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Entities。 - 從
Entity清單中選取Messages。 - 選取
List作業，然後按一下「完成」。 - 在「連線器」工作的「工作輸入」部分，您可以根據客戶需求設定 filterClause。
您必須使用單引號 (') 括住 filterClause 的值。您可以使用 filterClause，根據資料欄篩選記錄。
範例 - 從收件匣取得 Gmail 郵件詳細資料
- 在
Configure connector task對話方塊中，按一下Entities。 - 從
Entity清單中選取Inbox。 - 選取
Get作業，然後按一下「完成」。 - 將 entityId 設為
1，這是要傳遞的金鑰。如要設定 entityId，請在「資料對應」的「資料對應器」部分，按一下「開啟資料對應編輯器」，然後在「輸入值」欄位中輸入1，並選擇 entityId 做為本機變數。
entityId 的值必須直接傳遞，例如 "1"。其中 "1" 是傳遞的不重複主鍵值。
在某些情況下，傳遞單一 entityId 可能會導致錯誤，因為實體有兩個複合鍵。在這種情況下，您可以使用 filterClause 並傳遞值，例如 id='1'。
範例 - 刪除 Gmail 郵件
- 在
Configure connector task對話方塊中，按一下Entities。 - 從
Entity清單中選取Messages。 - 選取
Delete作業，然後按一下「完成」。 - 將 entityId 設為
1，也就是要傳遞的鍵。 - 如要設定 entityId，請在「資料對應」的「資料對應器」專區中，按一下「開啟資料對應編輯器」，然後在「輸入值」欄位中輸入
1，並選擇 entityId 做為本機變數。如果實體有兩個複合式商家或主鍵，而非指定 entityId，您也可以將 filterClause 設為
id='1'。