如何在Ballerina中连接Gmail API？基于ballerinax/googleapis.gmail连接器

所需凭据类型 #

你需要准备OAuth 2.0 客户端凭据，这些凭据从Google Cloud Console获取，包含：

• 客户端ID（Client ID）
• 客户端密钥（Client Secret）
• 重定向URI（建议设为http://localhost:9095/oauth2_callback，匹配Ballerina OAuth2客户端的默认回调地址）

如果是服务器端无交互场景，也可以使用服务账号凭据（JSON格式），但本地开发或桌面应用优先用OAuth2客户端凭据。

具体操作步骤 #

1. 在Google Cloud Console配置Gmail API #

• 登录Google Cloud Console，创建或选择一个现有项目
• 进入「API和服务」>「库」，搜索并启用Gmail API
• 切换到「凭据」页面，点击「创建凭据」>「OAuth客户端ID」
• 应用类型选择「桌面应用」（本地开发场景），填写名称后设置重定向URI为http://localhost:9095/oauth2_callback
• 创建完成后，下载JSON格式的凭据文件，里面包含你需要的client_id和client_secret

2. 初始化Ballerina项目并添加依赖 #

• 打开终端，创建新的Ballerina项目：

  bal new gmail-integration
  cd gmail-integration
  

• 添加Gmail连接器依赖：

  bal add ballerinax/googleapis.gmail
  

3. 编写连接代码 #

在项目的main.bal文件中写入以下代码，替换占位符为你的凭据信息：

import ballerinax/googleapis.gmail;
import ballerina/oauth2;
import ballerina/io;

public function main() returns error? {
    // 配置OAuth2客户端参数
    oauth2:OAuth2ClientConfig oauthConfig = {
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET",
        refreshToken: "YOUR_REFRESH_TOKEN",
        tokenUrl: "https://oauth2.googleapis.com/token",
        authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
        scopes: ["https://www.googleapis.com/auth/gmail.readonly"]
    };

    // 初始化Gmail客户端
    gmail:Client gmailClient = check new (oauthConfig);

    // 测试连接：获取当前用户邮箱信息
    gmail:Profile userProfile = check gmailClient->getProfile();
    io:println("已成功连接，当前用户邮箱: ", userProfile.emailAddress);
}

关于刷新令牌（Refresh Token）的获取

首次运行代码时，Ballerina会自动打开浏览器引导你完成Google账号授权，授权成功后会在终端输出refreshToken值，把这个值填入代码的YOUR_REFRESH_TOKEN占位符即可，后续运行无需重复授权。

4. 运行并验证连接 #

执行以下命令启动项目：

bal run

如果配置正确，终端会输出当前用户的邮箱地址，说明连接已成功建立。

注意事项 #

• 根据你的业务需求调整scopes参数，比如需要发送邮件就添加https://www.googleapis.com/auth/gmail.send，需要完全访问则用https://mail.google.com/
• 服务账号场景下，需要在Google Cloud Console中为服务账号启用域范围委派，并使用gmail:ServiceAccountConfig替代OAuth2配置

内容的提问来源于stack exchange，提问作者Tharmigan Krishnananthalingam