Gmail

透過 Gmail 連接器，您可以在 Gmail 中執行讀取和刪除作業。

支援的版本

這個連接器支援 Gmail REST API。

事前準備

使用 Gmail 連接器前，請先完成下列工作：

  • 在 Google Cloud 專案中：
    • 將 roles/connectors.admin IAM 角色授予設定連線器的使用者。
    • 將下列 IAM 角色授予要用於連接器的服務帳戶：
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      服務帳戶是特殊的 Google 帳戶類型，主要用於代表需要驗證且必須取得授權才能存取 Google API 資料的非人類使用者。如果您沒有服務帳戶，請建立服務帳戶。詳情請參閱「建立服務帳戶」。

    • 啟用下列服務：
      • 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. 連接器：從可用連接器清單中選取「Gmail」。
    2. 連接器版本：從可用版本清單中選取連接器版本。
    3. 在「連線名稱」欄位中，輸入連線執行個體的名稱。連線名稱可包含小寫英文字母、數字或連字號，名稱開頭須為英文字母，結尾須為英文字母或數字，且長度不得超過 49 個半形字元。
    4. 說明：輸入連線執行個體的說明。
    5. 或者，可啟用 Cloud Logging，然後選取記錄層級。記錄層級預設為 Error。
    6. 服務帳戶：選取具備必要角色的服務帳戶。
    7. 視需要設定「連線節點設定」：

      • 節點數量下限：輸入連線節點數量下限。
      • 節點數量上限：輸入連線節點數量上限。

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

    8. 「+ 新增標籤」：按一下這個選項，即可為連線新增鍵/值組合形式的標籤。
    9. 點選「下一步」。
  5. 在「Authentication」(驗證) 部分，輸入驗證詳細資料。
    1. 選取「驗證類型」，然後輸入相關詳細資料。

      Gmail 連結支援下列驗證類型：

      • 服務帳戶驗證
      • 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 驗證的用戶端密鑰。
    • 密鑰版本：輸入用戶端密鑰的密鑰版本。
    • 啟用驗證覆寫：啟用後即可覆寫驗證。

連線設定範例

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

OAuth 2.0 - JWT 持有者連線類型

欄位名稱 詳細資料
位置 asia-east1
連接器 Gmail
連接器版本 1
連線名稱 gmail-jwt-conn
啟用 Cloud Logging 是
服務帳戶 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 筆交易，超出此上限的交易都會遭到節流。根據預設，整合連接器會為連線分配 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 郵件

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SendMailMessages」動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
  "To": "testbristleconeemail@gmail.com",
  "Subject": "Data MapperCheck",
  "Content": "Gmail",
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
"Id": "199334f660ff462a"
}]

範例 - 傳送含有 JPG 附件的 Gmail 郵件

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SendMailMessages」動作，然後按一下「完成」。
  3. 在「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
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Id": "199334f660ff462a"
}]

範例 - 傳送含有 PDF 附件的 Gmail 郵件

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SendMailMessages」動作，然後按一下「完成」。
  3. 在「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
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Id": "1993341d558d7b07"
}]

範例 - 傳送含有 TXT 附件的 Gmail 郵件

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SendMailMessages」動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
  "To": "testbristleconeemail@gmail.com",
  "Subject": "Data Mapper Email Sep10",
  "Content": "Gmail",
  "AttachmentFileName": "TestSep10.txt",
  "AttachmentContent": "TestingwithAttachment",
  "AttachmentHasBytes": true
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
    "Id": "1993341d558d7b07"
}]

範例 - 從 Gmail 下載附件

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「DownloadAttachment」動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
  "MessageId": "198acdcde5c09ce5"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
    "Success": "true",
    "MessageId": "198acdcde5c09ce5",
    "AttachmentId": "1",
    "Size": "58005",
    "Data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoYWJvdXQ6YmxhbmspCi9DcmVhdG9yIChNb3ppbGxhLzUuMCBcKFgxMTsgTGludXggeDg2XzY0XCkgQXBwbGVXZWJLaXQvNTM3LjM2IFwoS0hUTUwsIGxpa2UgR2Vja29cKSBIZWFkbGVzc0Nocm9tZS8xMzguMC4wLjAgU2FmYXJpLzUzNy4zNikKL1Byb2R1Y2VyIChTa2lhL1BERiBtMTM4KQovQ3JlYXRpb25EYXRlIChEOjIwMjUwODE1MDgwMDE2KzAwJzAwJykKL01vZERhdGUgKEQ6MjAyNTA4MTUwODAwMTYrMDAnMDAnKT4-CmVuZG9iagozIDAgb2JqCjw8L2NhIDEKL0JNIC9Ob3JtYWw-PgplbmRvYmo",
    "Filename": "My_Store_404672162.pdf",
    "@isoutervalue": null
}]

實體作業範例

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

範例 - 列出所有 Gmail 郵件

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

    5. 您必須使用單引號 (') 括住 filterClause 的值。您可以使用 filterClause，根據資料欄篩選記錄。

範例 - 從收件匣取得 Gmail 郵件詳細資料

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

    5. entityId 的值必須直接傳遞，例如 "1"。其中 "1" 是傳遞的唯一主鍵值。

    在某些情況下，傳遞單一 entityId 可能會導致錯誤，因為實體有兩個複合鍵。在這種情況下，您可以使用 filterClause 並傳遞值，例如 id='1'。

範例 - 刪除 Gmail 郵件

  1. 在 Configure connector task 對話方塊中，按一下 Entities。
  2. 從 Entity 清單中選取 Messages。
  3. 選取「Delete」作業，然後按一下「完成」。
  4. 將 entityId 設為 1，也就是要傳遞的鍵。
  5. 如要設定 entityId，請在「資料對應」的「資料對應器」專區中，按一下「開啟資料對應編輯器」，然後在「輸入值」欄位中輸入 1，並選擇 entityId 做為本機變數。

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

向 Google Cloud 社群尋求協助

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

後續步驟