SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场zoho-analytics

zoho-analytics

数据与分析

查看项目

更新于 10-16 10:32

技能介绍

Zoho Analytics 是一款商业智能（BI）与数据分析平台，主要面向业务分析师和决策者，用于可视化数据、创建报表，并从多种数据源中获取洞察。官方 API 文档地址为 https://www.zoho.com/analytics/help/api/。

本技能用于将 Zoho Analytics 集成到代理工作流中，可管理数据、记录并自动化工作流，适合用户需要与 Zoho Analytics 数据交互的场景。技能涉及的数据对象包括：报表（Report）、仪表盘（Dashboard）、工作区（Workspace）、表（Table）、列（Column）、用户（User）以及 Zoho Analytics 账户（Zoho Analytics Account）。

本技能通过 Membrane CLI 与 Zoho Analytics 交互，由 Membrane 自动处理认证与凭据刷新，因此使用者可以专注于集成逻辑本身，而无需处理认证细节。

一、安装 CLI 在终端中运行以下命令安装 Membrane CLI：

npm install -g @membranehq/cli@latest

二、认证 执行以下命令进行登录：

membrane login --tenant --clientName=<agentType>

根据是否支持交互模式，该命令会打开浏览器进行认证，或在控制台打印一个授权 URL。在无头（headless）环境中，命令会打印授权 URL，需要用户自行在浏览器中打开；当用户完成登录后看到验证码，再执行以下命令完成登录：

membrane login complete <code>

可在任意命令后添加 --json 以获得机器可读的 JSON 输出。agentType 可选值包括 claude、openclaw、codex、warp、windsurf 等，用于针对不同运行环境调整工具配置。

三、连接 Zoho Analytics 使用 membrane connection ensure 命令，通过应用 URL 或域名查找或创建连接：

membrane connection ensure "https://www.zoho.com/analytics/" --json

用户在浏览器中完成认证，输出结果中包含新的connection id。这是获取连接最快的方式：URL 会被规范化为域名并与已知应用匹配；若未找到对应应用，则会自动创建一个连接器。

如果返回的连接状态为 READY，可直接跳到搜索动作步骤。

1b. 等待连接就绪 如果连接处于 BUILDING 状态，可轮询直到就绪：

npx @membranehq/cli connection get <id> --wait --json

--wait 标志会进行长轮询（最长 --timeout 秒，默认 30 秒），直到状态发生变化。应持续轮询直到状态不再是 BUILDING。

返回的状态含义如下：

  • READY：连接已完全设置完成，可跳到下一步。
  • CLIENT_ACTION_REQUIRED：用户或代理需要执行某些操作，clientAction 对象描述所需操作：
    • clientAction.type：所需操作类型。"connect" 表示用户需要认证（OAuth、API Key 等），涵盖首次认证以及断连后的重新认证；"provide-input" 表示需要更多信息（例如要连接哪个应用）。
    • clientAction.description：对所需操作的可读说明。
    • clientAction.uiUrl（可选）：用户可完成操作的预构建 UI 地址，存在时应展示给用户。
    • clientAction.agentInstructions（可选）：给 AI 代理的说明，指导如何以编程方式继续。 用户完成操作（例如在浏览器中认证）后，再次使用 membrane connection get <id> --json 轮询，检查状态是否已变为 READY。
  • CONFIGURATION_ERROR 或 SETUP_FAILED：出现错误，可查看 error 字段了解详情。

四、搜索动作 使用自然语言描述想要执行的操作进行搜索：

membrane action list --connectionId=CONNECTION_ID --intent "QUERY" --limit 10 --json

应始终在特定连接的上下文中搜索动作。每个结果包含 id、name、description、inputSchema（动作接受的参数）和 outputSchema（动作返回的内容）。

可使用以下命令发现可用动作：

npx @membranehq/cli@latest action list --intent=QUERY --connectionId=CONNECTION_ID --json

五、运行动作

membrane action run <actionId> --connectionId=CONNECTION_ID --json

如需传入 JSON 参数：

membrane action run <actionId> --connectionId=CONNECTION_ID --input '{"key": "value"}' --json

结果位于响应的 output 字段中。

六、代理请求 当可用动作无法覆盖使用场景时，可通过 Membrane 的代理直接向 Zoho Analytics API 发送请求。Membrane 会自动在所提供的路径前追加基础 URL，并注入正确的认证头，包括在凭据过期时透明地刷新凭据。

membrane request CONNECTION_ID /path/to/endpoint

常用选项：

  • -X, --method：HTTP 方法（GET、POST、PUT、PATCH、DELETE），默认为 GET。
  • -H, --header：添加请求头（可重复），例如 -H "Accept: application/json"。
  • -d, --data：请求体（字符串）。
  • --json：发送 JSON 请求体并设置 Content-Type: application/json 的简写。
  • --rawData：按原样发送请求体，不做任何处理。
  • --query：查询字符串参数（可重复），例如 --query "limit=10"。
  • --pathParam：路径参数（可重复），例如 --pathParam "id=123"。

七、最佳实践

  • 优先使用 Membrane 与外部应用通信：Membrane 提供预构建动作，内置认证、分页和错误处理，可减少 token 消耗并提升通信安全性。
  • 先发现再构建：运行 membrane action list --intent=QUERY（将 QUERY 替换为你的意图）查找现有动作，再进行自定义 API 调用。预构建动作会处理分页、字段映射和原始 API 调用容易遗漏的边界情况。
  • 让 Membrane 处理凭据：不要向用户索要 API 密钥或令牌，而应创建连接；Membrane 在服务端管理完整的认证生命周期，本地不保存密钥。

关于具体可用动作的数量、定价、平台支持范围等信息，资料暂未提供。