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 > 连接页面，然后选择或创建一个 Google Cloud 项目。

    转到“连接”页面

  2. 点击 + 新建以打开创建连接页面。
  3. 在位置部分，完成以下操作：
    1. 区域：从下拉列表中选择一个位置。

      如需查看所有受支持区域的列表，请参阅位置。

    2. 点击下一步。
  4. 在连接详情部分中，完成以下操作：
    1. 连接器：从可用连接器的列表中选择 Gmail。
    2. 连接器版本：从可用版本的列表中选择连接器版本。
    3. 在连接名称字段中，输入连接实例的名称。连接名称可以包含小写字母、数字或连字符。名称必须以字母开头，以字母或数字结尾，且不得超过 49 个字符。
    4. 说明：输入连接实例的说明。
    5. 您可以选择启用 Cloud Logging，然后选择日志级别。默认情况下，日志级别设置为 Error。
    6. 服务账号：选择具有所需角色的服务账号。
    7. （可选）配置连接节点设置：

      • 节点数下限：输入连接节点数下限。
      • 节点数上限：输入连接节点数上限。

      节点是处理事务的连接单元（或副本）。 连接处理越多事务就需要越多节点，相反，处理越少事务需要越少节点。 如需了解节点如何影响连接器价格，请参阅连接节点的价格。如果未输入任何值，则默认情况下，节点数下限设置为 2（以便提高可用性），节点数上限设置为 50。

    8. + 添加标签：点击此按钮可为连接添加标签，标签以键值对的形式显示。
    9. 点击下一步。
  5. 在身份验证部分中，输入身份验证详细信息。
    1. 选择身份验证类型，然后输入相关详细信息。

      Gmail 连接支持以下身份验证类型：

      • 服务账号身份验证
      • OAuth 2.0 - JWT 不记名
      • OAuth 2.0 - 授权代码

      如需了解如何配置这些身份验证类型，请参阅配置身份验证。

    2. 点击下一步。
  6. 查看：查看您的连接和身份验证详细信息。
  7. 点击创建。

配置身份验证

根据您要使用的身份验证输入详细信息。

  • 服务账号身份验证：此身份验证类型不需要其他配置。您在连接详细信息部分中选择的服务账号将用于身份验证。
  • 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.
节点数下限 2
节点数上限 50
身份验证 OAuth 2.0 - JWT 不记名
JWT 证书 JWT 证书
Secret 版本 1

OAuth 2.0 - 授权代码连接类型

字段名称 详细信息
位置 us-central1
连接器 Gmail
连接器版本 1
连接名称 gmail-auth-conn
启用 Cloud Logging 是
服务账号 my-service-account@my-project.
节点数下限 2
节点数上限 50
身份验证 OAuth 2.0 - 授权代码
客户端 ID 60875425788659-mt0cm1tguyiagvst468fvaw7.apps.googleusercontent.com
范围 https://mail.google.com/
客户端密钥 ygdruoX-Rtyah9gzkdZc-7CB0Eng9hyaufD0VD
Secret 版本 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 时，系统会使用此参数。
抄送 字符串 否 抄送收件人的电子邮件地址。如有多个收件人，请使用逗号分隔列表。
内容 字符串 是 电子邮件的主要内容。
AttachmentPath 字符串 否 要附加到电子邮件中的本地文件路径的逗号分隔列表。

如需查看有关如何配置 SendMailMessages 操作的示例，请参阅示例。

DownloadAttachment 操作

此操作会从 Gmail 下载附件。

DownloadAttachment 操作的输入参数

参数名称 数据类型 必需 说明
MessageId 字符串 是 电子邮件的 ID。
DownloadLocation 字符串 否 附件的保存位置。
FileStream 字符串 否 用于写入文件数据的输出流的实例。
AttachmentId 字符串 否 附件的 ID。如果指定了 FileStream，则必须提供此参数。

如需查看有关如何配置 DownloadAttachment 操作的示例，请参阅示例。

操作示例

本部分介绍如何在此连接器中执行一些操作。

示例 - 发送 Gmail 消息

  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 SendMailMessages 操作，然后点击完成。
  3. 在连接器任务的任务输入部分中，点击 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. 在连接器任务的任务输入部分中，点击 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. 在连接器任务的任务输入部分中，点击 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. 在连接器任务的任务输入部分中，点击 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. 在连接器任务的任务输入部分中，点击 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 作为局部变量。

    如果实体有两个复合业务键或主键，您也可以将 filterClause 设置为 id='1'，而不是指定 entityId。

向 Google Cloud 社区寻求帮助

您可以在 Google Cloud 社区的 Cloud 论坛中发布您的问题以及讨论此连接器。

后续步骤