Composio Google Calendar 集成指南OAuth 认证配置与触发器实战【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文基于 Composio 仓库中的 Google Calendar 支持文档与知识库内容系统讲解在 Composio 上接入 Google Calendar 时最常见的 OAuth 认证问题自定义凭据、App is blocked、invalid_scope、401 等以及事件数据、触发器与版本兼容性的实战要点帮助你快速定位并解决集成过程中的真实故障。引言Google Calendar 是 Composio 提供的核心工具包toolkit之一其工具与触发器通过已连接的账户connected account对外提供能力。无论你是要在 Agent 中读取日历事件、创建日程、查询忙闲状态还是基于日历变更触发工作流都绕不开认证配置这一关。本文以仓库中的 FAQ 文档docs/content/toolkits/faq/googlecalendar.md为主体骨架结合知识库指南docs/content/kb/guide/toolkits-google-calendar.mdx与认证相关文档给出可直接对照排查的完整方案。一、自定义 Google OAuth 凭据的配置默认情况下Composio 使用官方托管的 OAuth 应用完成 Google 各工具包的授权。当你的业务需要自己的品牌展示在同意屏幕consent screen上、需要请求自定义 scope、或希望获得独立的速率配额时就需要创建自定义的 Google OAuth 凭据。完整的操作指引在仓库中对应的是 How to create OAuth2 credentials for Google Apps 链接FAQ 原文引用其核心流程可概括为在 Google Cloud Console 中创建 OAuth 客户端在客户端中把授权重定向 URI设置为 Composio 的回调地址将 client ID 与 client secret 通过auth_configs.create()写入 Composio。仓库中的 programmatic-auth-configs.mdx 给出了程序化创建自定义 OAuth 配置的完整示例以 Notion 为例Google 工具包同理import os from composio import Composio composio Composio() auth_config composio.auth_configs.create( toolkitnotion, # 换成 googlecalendar 即适用于 Google Calendar options{ type: use_custom_auth, auth_scheme: OAUTH2, name: Notion, credentials: { client_id: os.environ[NOTION_CLIENT_ID], client_secret: os.environ[NOTION_CLIENT_SECRET], oauth_redirect_uri: https://backend.composio.dev/api/v1/auth-apps/add, }, }, )要点说明oauth_redirect_uri可省略省略时使用 Composio 默认回调只有当你需要把回调路由到自己的域名时才需要显式设置创建成功后会返回类似ac_xxxxxxxx的 auth config ID需要在创建 session 时通过auth_configs{googlecalendar: auth_config.id}传入session 才会使用你的自定义配置进行认证。二、常见 OAuth 错误排查2.1 App is blocked应用被阻止症状连接 Google Calendar 时Google 提示 OAuth 客户端被阻止。原因OAuth 客户端请求了 Google未对该客户端完成验证的 scope通常是因为你在默认 scope 之外额外添加了 scope。解决方案FAQ 原文给出的两条路径从你的 auth config 中移除额外添加的 scope回归默认 scope 集合创建自己的 OAuth 应用并向 Google 提交这些 scope 的验证申请。知识库 platform-google-oauth.mdx 进一步说明当 OAuth 应用请求敏感sensitive或受限restrictedscope且未经该应用批准时Google 会阻止登录。因此要么只使用所选 Composio auth config 上已有的 scope要么创建客户自有的 Google OAuth 应用并完成 Google 要求的验证流程。修改 scope 之后必须创建全新的连接让用户对新 scope 集合重新授权。2.2 Google Calendar API has not been used in projectAPI 未启用症状使用自定义 OAuth 凭据时报错提示 Google Calendar API 尚未在项目中使用。原因凭据所属的 Google Cloud 项目中没有启用 Google Calendar API。解决方案FAQ 原文在 Google Cloud Console 的APIs Services中启用 Google Calendar API等待几分钟后重试。2.3 Error 400: invalid_scope症状授权 URL 返回 400提示 scope 无效。原因请求的 scope 值无效或格式错误。解决方案FAQ 原文对照 Google OAuth scopes 文档 核对你的 scope 值如果你是通过代码程序化创建 auth config参考程序化 auth config 指南。关于 scope 的实际影响知识库强调调用事件列表/获取类工具时连接的账户必须具有https://www.googleapis.com/auth/calendar.eventsscope否则事件读取流程会失败——这是 Google Calendar 集成中最容易踩坑的 scope 前提。2.4 同意屏幕显示 Composio 而不是你的应用名症状OAuth 同意屏幕上出现 Composio wants to access your account而不是你自己的应用名称与 Logo。原因默认情况下同意屏幕使用的是Composio 的 OAuth 应用。解决方案FAQ 原文创建你自己的 OAuth 应用并设置自定义重定向 URL详见 White-labeling authentication 中的 Using your own OAuth apps 一节。仓库中的 white-labeling-authentication.mdx 提供了完整背景Composio 品牌会出现在四个位置——Connect Link 页面、OAuth 同意屏幕、浏览器地址栏backend.composio.dev闪现、认证后成功页。对于同意屏幕上的 Composio 字样唯一修复方式是使用你自己的 OAuth 应用若还想隐藏重定向路径中的 Composio 域名则需通过自有域名代理回调routing the callback through your domain。同时注意现有已连接账户与创建它们的 auth config 绑定切换为自定义 OAuth 应用只会影响新连接老用户需删除旧连接重新授权或在支持的场景下迁移凭据。2.5 工具调用返回 401症状调用 Google Calendar 工具时收到 401 错误。原因用户的访问令牌access token已失效。常见诱因包括FAQ 原文用户撤销了访问权限用户修改了密码或启用了 2FAWorkspace 管理员策略变更超过 Google 的刷新令牌上限每个账户约 50 个。解决方案重新认证该用户re-authenticating通常即可恢复。这里需要特别说明的是Google 对每个用户账户的刷新令牌数量存在上限反复创建连接而不清理旧令牌最终会导致刷新令牌被 Google 静默淘汰从而表现为周期性 401。三、事件数据与可用性实战要点3.1 用primary作为日历 IDme不是合法的 Google Calendar ID。对 Google Calendar 工具调用时应使用primary这类真实日历 ID。这是知识库明确记录的约束写代码时不要想当然地用me替代。3.2 RSVP 状态更新受与会者列表限制更新 RSVP/出席状态时Google Calendar 在事件存在多个与会者attendees的场景下会限制状态更新。知识库给出的规避方法是先更新认证用户的 RSVP然后重新添加与会者或用更新后的状态重新发送与会者列表。3.3 用 Find Free Slots 获取处理后的忙闲数据query-free/busy返回的是提供方原始数据不包含时区处理等额外加工如果你需要已处理的可用时间段应使用Find Free Slots工具由调用方自行处理 free/busy 的时区逻辑。3.4 会议链接读取自hangout_link创建或更新带会议conferencing的日历事件后生成的会议 URL 位于响应中的hangout_link字段读取该字段即可拿到 Google Meet 链接。四、Google Calendar 触发器配置4.1 取消/删除事件的触发GOOGLECALENDAR_EVENT_CANCELED_DELETED_TRIGGER会在事件被取消或删除时发送负载。触发器trigger的创建与管理方式可参考仓库中的 creating-triggers.mdx 与 managing-triggers.mdx。4.2 同一用户多个日历每个日历一个触发器实例多个触发器可以针对相同的 trigger slug 和相同的用户共存前提是每个触发器配置了不同的calendarId。也就是说需要为不同日历分别创建独立的触发器实例。4.3 新版触发器返回完整事件数据较新的 Google Calendar 新事件触发器new-event trigger负载包含完整事件数据而不只是事件 ID。背后的设计演变知识库原文说明Google Calendar 触发器行为已从 webhook 式投递转向轮询polling以便负载携带更多细节、减少后续的补充处理同时保留了既有触发器流程轮询按需独立引入。4.4 程序化获取触发器元数据可以使用trigger-types 端点程序化检索 Google Calendar 的触发器元数据触发器设置的具体指引参见 triggers 文档subscribing-to-events.mdx 等。五、事件过滤器被忽略的版本问题症状对事件列表工具传入timeMin/timeMax等过滤器返回结果与不传过滤器时完全一致。原因较旧的、被固定的pinnedGoogle Calendar 工具包版本可能在请求到达 Google 之前就丢弃或重映射了timeMin、timeMax这类过滤器。解决方案知识库原文升级到最新的工具包版本或采用v3.1/latest 行为当过滤器变更产生的结果完全相同时优先排查工具包版本。在 SDK 中指定工具包版本的方式见 custom-auth-params.mdx 中的GOOGLECALENDAR_LIST_EVENTS示例from composio import Composio composio Composio(toolkit_versions{googlecalendar: latest}) result composio.tools.execute( slugGOOGLECALENDAR_LIST_EVENTS, user_iduser_123, arguments{}, dangerously_skip_version_checkTrue, # 使用 latest 时必须开启 )六、绕过连接账户直接注入自定义令牌如果你自己管理 Google OAuth 令牌不想走连接账户 重定向流程可以在执行时通过custom_auth_params直接注入Authorization头from composio import Composio composio Composio(toolkit_versions{googlecalendar: latest}) result composio.tools.execute( slugGOOGLECALENDAR_LIST_EVENTS, user_iduser_123, arguments{}, dangerously_skip_version_checkTrue, custom_auth_params{ parameters: [ { name: Authorization, value: Bearer YOUR_ACCESS_TOKEN, in: header, } ], }, ) print(result)TypeScript 等价写法import { Composio } from composio/core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY, toolkitVersions: { googlecalendar: latest }, }); const result await composio.tools.execute( GOOGLECALENDAR_LIST_EVENTS, { userId: user_123, arguments: {}, dangerouslySkipVersionCheck: true, // 使用 latest 时必须开启 customAuthParams: { parameters: [ { in: header, name: Authorization, value: Bearer ${process.env.GOOGLE_ACCESS_TOKEN}, }, ], }, } ); console.log(JSON.stringify(result, null, 2));parameters数组中每个条目支持三个字段字段说明name参数名如Authorization、X-API-Keyvalue凭据值in注入位置header或query重要警告官方文档明确提示这种方式会绕过 Composio 的自动令牌刷新机制刷新过期令牌的责任完全在你自己。七、排查思路总结错误/现象根因处理动作App is blocked请求了未验证的 scope移除额外 scope 或自建 OAuth 应用并提交验证Calendar API 未启用项目未启用 Google Calendar API在 Cloud Console 启用 API400 invalid_scopescope 值无效或格式错误对照 Google 文档核对 scope同意屏幕显示 Composio使用 Composio 托管应用自建 OAuth 应用 自定义重定向401访问令牌失效/被撤销/刷新令牌超限重新认证用户过滤器被忽略工具包版本过旧升级到 latest 或 v3.1 行为延伸阅读Google Calendar 知识库指南事件、触发器与版本问题的完整细节程序化 auth config 指南在代码中创建与管理自定义认证配置白标认证移除 Composio 品牌、使用自有 OAuth 应用与回调域名Google OAuth 设置与同意scope 验证与客户自有应用的品牌控制创建触发器 / 订阅事件触发器的配置指引执行工具GOOGLECALENDAR_EVENTS_LIST等工具的执行方式【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Composio Google Calendar 集成指南：OAuth 认证配置与触发器实战
Composio Google Calendar 集成指南OAuth 认证配置与触发器实战【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文基于 Composio 仓库中的 Google Calendar 支持文档与知识库内容系统讲解在 Composio 上接入 Google Calendar 时最常见的 OAuth 认证问题自定义凭据、App is blocked、invalid_scope、401 等以及事件数据、触发器与版本兼容性的实战要点帮助你快速定位并解决集成过程中的真实故障。引言Google Calendar 是 Composio 提供的核心工具包toolkit之一其工具与触发器通过已连接的账户connected account对外提供能力。无论你是要在 Agent 中读取日历事件、创建日程、查询忙闲状态还是基于日历变更触发工作流都绕不开认证配置这一关。本文以仓库中的 FAQ 文档docs/content/toolkits/faq/googlecalendar.md为主体骨架结合知识库指南docs/content/kb/guide/toolkits-google-calendar.mdx与认证相关文档给出可直接对照排查的完整方案。一、自定义 Google OAuth 凭据的配置默认情况下Composio 使用官方托管的 OAuth 应用完成 Google 各工具包的授权。当你的业务需要自己的品牌展示在同意屏幕consent screen上、需要请求自定义 scope、或希望获得独立的速率配额时就需要创建自定义的 Google OAuth 凭据。完整的操作指引在仓库中对应的是 How to create OAuth2 credentials for Google Apps 链接FAQ 原文引用其核心流程可概括为在 Google Cloud Console 中创建 OAuth 客户端在客户端中把授权重定向 URI设置为 Composio 的回调地址将 client ID 与 client secret 通过auth_configs.create()写入 Composio。仓库中的 programmatic-auth-configs.mdx 给出了程序化创建自定义 OAuth 配置的完整示例以 Notion 为例Google 工具包同理import os from composio import Composio composio Composio() auth_config composio.auth_configs.create( toolkitnotion, # 换成 googlecalendar 即适用于 Google Calendar options{ type: use_custom_auth, auth_scheme: OAUTH2, name: Notion, credentials: { client_id: os.environ[NOTION_CLIENT_ID], client_secret: os.environ[NOTION_CLIENT_SECRET], oauth_redirect_uri: https://backend.composio.dev/api/v1/auth-apps/add, }, }, )要点说明oauth_redirect_uri可省略省略时使用 Composio 默认回调只有当你需要把回调路由到自己的域名时才需要显式设置创建成功后会返回类似ac_xxxxxxxx的 auth config ID需要在创建 session 时通过auth_configs{googlecalendar: auth_config.id}传入session 才会使用你的自定义配置进行认证。二、常见 OAuth 错误排查2.1 App is blocked应用被阻止症状连接 Google Calendar 时Google 提示 OAuth 客户端被阻止。原因OAuth 客户端请求了 Google未对该客户端完成验证的 scope通常是因为你在默认 scope 之外额外添加了 scope。解决方案FAQ 原文给出的两条路径从你的 auth config 中移除额外添加的 scope回归默认 scope 集合创建自己的 OAuth 应用并向 Google 提交这些 scope 的验证申请。知识库 platform-google-oauth.mdx 进一步说明当 OAuth 应用请求敏感sensitive或受限restrictedscope且未经该应用批准时Google 会阻止登录。因此要么只使用所选 Composio auth config 上已有的 scope要么创建客户自有的 Google OAuth 应用并完成 Google 要求的验证流程。修改 scope 之后必须创建全新的连接让用户对新 scope 集合重新授权。2.2 Google Calendar API has not been used in projectAPI 未启用症状使用自定义 OAuth 凭据时报错提示 Google Calendar API 尚未在项目中使用。原因凭据所属的 Google Cloud 项目中没有启用 Google Calendar API。解决方案FAQ 原文在 Google Cloud Console 的APIs Services中启用 Google Calendar API等待几分钟后重试。2.3 Error 400: invalid_scope症状授权 URL 返回 400提示 scope 无效。原因请求的 scope 值无效或格式错误。解决方案FAQ 原文对照 Google OAuth scopes 文档 核对你的 scope 值如果你是通过代码程序化创建 auth config参考程序化 auth config 指南。关于 scope 的实际影响知识库强调调用事件列表/获取类工具时连接的账户必须具有https://www.googleapis.com/auth/calendar.eventsscope否则事件读取流程会失败——这是 Google Calendar 集成中最容易踩坑的 scope 前提。2.4 同意屏幕显示 Composio 而不是你的应用名症状OAuth 同意屏幕上出现 Composio wants to access your account而不是你自己的应用名称与 Logo。原因默认情况下同意屏幕使用的是Composio 的 OAuth 应用。解决方案FAQ 原文创建你自己的 OAuth 应用并设置自定义重定向 URL详见 White-labeling authentication 中的 Using your own OAuth apps 一节。仓库中的 white-labeling-authentication.mdx 提供了完整背景Composio 品牌会出现在四个位置——Connect Link 页面、OAuth 同意屏幕、浏览器地址栏backend.composio.dev闪现、认证后成功页。对于同意屏幕上的 Composio 字样唯一修复方式是使用你自己的 OAuth 应用若还想隐藏重定向路径中的 Composio 域名则需通过自有域名代理回调routing the callback through your domain。同时注意现有已连接账户与创建它们的 auth config 绑定切换为自定义 OAuth 应用只会影响新连接老用户需删除旧连接重新授权或在支持的场景下迁移凭据。2.5 工具调用返回 401症状调用 Google Calendar 工具时收到 401 错误。原因用户的访问令牌access token已失效。常见诱因包括FAQ 原文用户撤销了访问权限用户修改了密码或启用了 2FAWorkspace 管理员策略变更超过 Google 的刷新令牌上限每个账户约 50 个。解决方案重新认证该用户re-authenticating通常即可恢复。这里需要特别说明的是Google 对每个用户账户的刷新令牌数量存在上限反复创建连接而不清理旧令牌最终会导致刷新令牌被 Google 静默淘汰从而表现为周期性 401。三、事件数据与可用性实战要点3.1 用primary作为日历 IDme不是合法的 Google Calendar ID。对 Google Calendar 工具调用时应使用primary这类真实日历 ID。这是知识库明确记录的约束写代码时不要想当然地用me替代。3.2 RSVP 状态更新受与会者列表限制更新 RSVP/出席状态时Google Calendar 在事件存在多个与会者attendees的场景下会限制状态更新。知识库给出的规避方法是先更新认证用户的 RSVP然后重新添加与会者或用更新后的状态重新发送与会者列表。3.3 用 Find Free Slots 获取处理后的忙闲数据query-free/busy返回的是提供方原始数据不包含时区处理等额外加工如果你需要已处理的可用时间段应使用Find Free Slots工具由调用方自行处理 free/busy 的时区逻辑。3.4 会议链接读取自hangout_link创建或更新带会议conferencing的日历事件后生成的会议 URL 位于响应中的hangout_link字段读取该字段即可拿到 Google Meet 链接。四、Google Calendar 触发器配置4.1 取消/删除事件的触发GOOGLECALENDAR_EVENT_CANCELED_DELETED_TRIGGER会在事件被取消或删除时发送负载。触发器trigger的创建与管理方式可参考仓库中的 creating-triggers.mdx 与 managing-triggers.mdx。4.2 同一用户多个日历每个日历一个触发器实例多个触发器可以针对相同的 trigger slug 和相同的用户共存前提是每个触发器配置了不同的calendarId。也就是说需要为不同日历分别创建独立的触发器实例。4.3 新版触发器返回完整事件数据较新的 Google Calendar 新事件触发器new-event trigger负载包含完整事件数据而不只是事件 ID。背后的设计演变知识库原文说明Google Calendar 触发器行为已从 webhook 式投递转向轮询polling以便负载携带更多细节、减少后续的补充处理同时保留了既有触发器流程轮询按需独立引入。4.4 程序化获取触发器元数据可以使用trigger-types 端点程序化检索 Google Calendar 的触发器元数据触发器设置的具体指引参见 triggers 文档subscribing-to-events.mdx 等。五、事件过滤器被忽略的版本问题症状对事件列表工具传入timeMin/timeMax等过滤器返回结果与不传过滤器时完全一致。原因较旧的、被固定的pinnedGoogle Calendar 工具包版本可能在请求到达 Google 之前就丢弃或重映射了timeMin、timeMax这类过滤器。解决方案知识库原文升级到最新的工具包版本或采用v3.1/latest 行为当过滤器变更产生的结果完全相同时优先排查工具包版本。在 SDK 中指定工具包版本的方式见 custom-auth-params.mdx 中的GOOGLECALENDAR_LIST_EVENTS示例from composio import Composio composio Composio(toolkit_versions{googlecalendar: latest}) result composio.tools.execute( slugGOOGLECALENDAR_LIST_EVENTS, user_iduser_123, arguments{}, dangerously_skip_version_checkTrue, # 使用 latest 时必须开启 )六、绕过连接账户直接注入自定义令牌如果你自己管理 Google OAuth 令牌不想走连接账户 重定向流程可以在执行时通过custom_auth_params直接注入Authorization头from composio import Composio composio Composio(toolkit_versions{googlecalendar: latest}) result composio.tools.execute( slugGOOGLECALENDAR_LIST_EVENTS, user_iduser_123, arguments{}, dangerously_skip_version_checkTrue, custom_auth_params{ parameters: [ { name: Authorization, value: Bearer YOUR_ACCESS_TOKEN, in: header, } ], }, ) print(result)TypeScript 等价写法import { Composio } from composio/core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY, toolkitVersions: { googlecalendar: latest }, }); const result await composio.tools.execute( GOOGLECALENDAR_LIST_EVENTS, { userId: user_123, arguments: {}, dangerouslySkipVersionCheck: true, // 使用 latest 时必须开启 customAuthParams: { parameters: [ { in: header, name: Authorization, value: Bearer ${process.env.GOOGLE_ACCESS_TOKEN}, }, ], }, } ); console.log(JSON.stringify(result, null, 2));parameters数组中每个条目支持三个字段字段说明name参数名如Authorization、X-API-Keyvalue凭据值in注入位置header或query重要警告官方文档明确提示这种方式会绕过 Composio 的自动令牌刷新机制刷新过期令牌的责任完全在你自己。七、排查思路总结错误/现象根因处理动作App is blocked请求了未验证的 scope移除额外 scope 或自建 OAuth 应用并提交验证Calendar API 未启用项目未启用 Google Calendar API在 Cloud Console 启用 API400 invalid_scopescope 值无效或格式错误对照 Google 文档核对 scope同意屏幕显示 Composio使用 Composio 托管应用自建 OAuth 应用 自定义重定向401访问令牌失效/被撤销/刷新令牌超限重新认证用户过滤器被忽略工具包版本过旧升级到 latest 或 v3.1 行为延伸阅读Google Calendar 知识库指南事件、触发器与版本问题的完整细节程序化 auth config 指南在代码中创建与管理自定义认证配置白标认证移除 Composio 品牌、使用自有 OAuth 应用与回调域名Google OAuth 设置与同意scope 验证与客户自有应用的品牌控制创建触发器 / 订阅事件触发器的配置指引执行工具GOOGLECALENDAR_EVENTS_LIST等工具的执行方式【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
