GetMyBot 知识库

数据源与密钥

保存外部服务的地址和密钥,在反应中读取目录或写入订单。

本页内容

如果商品保存在你的网站,机器人可以通过网站的 API 读取目录,并在用户下单后写回订单。API 是程序之间交换数据的接口。先在数据源保存服务连接(连接器),再在密钥添加访问凭据。反应中选择查询数据源或写入数据源动作。已有现成连接方式时,先看集成。

连接器(数据源)

打开数据源 → 连接器。连接器包含名称、类型、基础 URL、关联的凭据和请求头。

类型用途注意事项
REST任意 HTTP/JSON API填写外部服务的地址和访问凭据
OzmaDBOzmaDB/FunDB 数据库填写实例 REST API 的根地址;匿名视图(view)的读取配置更简单
IMAP–不能新建;已保存的连接仍显示为“不再支持”,可正常删除

检查会发送测试请求并显示状态、耗时或错误,便于核对 URL 和密钥。

凭据(密钥)

打开密钥 → 凭据,按外部服务的文档选择授权方式。密钥会加密保存。

方式所需信息
API 密钥密钥和请求头名称,默认 Authorization
Bearer 令牌用于 Authorization: Bearer 请求头的令牌
OAuth2(password)Token URL、Client ID/Secret、用户名、密码、scope
OAuth2(refresh)Token URL、Client ID/Secret、refresh 令牌、scope

GetMyBot 会获取并缓存 OAuth2 访问令牌,在过期或服务返回 401 后更新;如果服务轮换 refresh 令牌,新令牌也会保存。编辑时密钥字段留空表示保留原值。

在反应中读写数据

  • 查询数据源(ds_query)读取数据并存入反应临时数据 ctx。填写请求路径、列表在响应中的 JSONPath 和结果名称。例如将商品列表存为 products,供动态按钮或列表循环使用。
  • 写入数据源(ds_write)通过 POST、PUT 或 DELETE 发送 JSON 数据。

请求体、重试与响应检查

网页请求和写入数据源的 POST/PUT 请求体可按 JSON 树编辑。每个值可选字符串、数字、布尔值、JSON 或 null 类型,并使用变量替换。数字不会意外变成字符串,嵌套对象也无需手动转义:

{
  "customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
  "amount": 4900,
  "paid": false
}

原有文本请求体仍可使用,切换模式不会丢失已输入的内容。重试(retry_count)仅针对网络错误、429 和 5xx,其他 4xx 不会重试。GET、HEAD、OPTIONS、PUT、DELETE 可以重试;POST 和 PATCH 仅在你明确设置 Idempotency-Key 请求头时重试。这表示接收方 API 会按此键去重。平台也会附带自己的步骤执行键,但只有这个键不会启用 POST/PATCH 重试,避免重复创建订单。集成和 CRM 写入若结果不明确,平台不会自行重试;带你设置的 Idempotency-Key 的网页请求是例外。

REST 连接器编辑器中的检查响应会按已保存连接发送一次 GET,使用指定路径和参数,不进行变量替换。它显示状态、类型和最多 64 KB 的响应体,不写入数据。JSON 响应可用作解析响应的样例。解析响应适用于网页请求、数据源查询和写入、AI、Google 表格、Google 云端硬盘、GetCourse 及 CRM 动作。可选规范化的“动作结果”或处理前的“完整响应”。规则整体执行:任何一条失败,都不会写入变量。

单次请求可用网页请求,下载网页文本可用加载 URL。详见动作。

OzmaDB 命名视图与表

保存 OzmaDB 连接后,在数据源动作中选择它并开启 OzmaDB 模式。已有 HTTP 请求保留通用模式和参数;显式切换时 HTTP 字段仍留在动作中,编辑器打开期间可恢复 Ozma 配置。

读取时填写固定的模式(schema)和视图(view)名称,或点击加载目录。加载更多会追加目录页并保留所选对象。加载参数和字段从元数据获取参数提示;为每个参数填写名称、类型和值。目录访问被拒绝时也可手动输入。视图是可合并表和计算值的已保存查询,用于读取。创建或更新记录则选择 Entity 表。

例如读取 usr.people_by_team,传入数字参数 team_id:

{
  "connection": "ozma",
  "ozma": {
    "schema": "usr",
    "view": "people_by_team",
    "args": { "team_id": { "type": "number", "value": "42" } },
    "limit": 100,
    "offset": 0
  },
  "save_to_ctx": "people"
}

ctx.people 保存按列名组织的对象数组,例如 [{"id":7,"name":"Alex"}],可在后续动作或列表循环使用。默认每页 100 条,最多 500 条,offset 范围 0–100000。读取多页时应在视图中设置稳定排序。读取预览只读且最多返回 20 行;参数必须是字面值,不能使用事件变量。测试带变量的动作时,暂时改为测试值。写入没有预览。

写入时填写模式和表(entity),选择创建或更新,再添加带类型的字段。更新需要正整数记录 ID,也可取自前一个动作:

{
  "connection": "ozma",
  "ozma": {
    "schema": "usr",
    "entity": "person",
    "operation": "update",
    "id": "{{ctx.person_id}}",
    "fields": {
      "name": { "type": "string", "value": "{{text}}" },
      "active": { "type": "boolean", "value": "true" },
      "details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
      "note": { "type": "null", "value": "" }
    }
  },
  "save_to_ctx": "saved_person"
}

可选的结果键保存事务响应,首条记录 ID 位于 ctx.saved_person.results[0].id。创建时使用 insert,不填 id;创建时空 fields 使用 entity 默认值,更新则至少要有一个字段。元数据提示排除计算字段及当前操作无权写入的字段,最终权限和约束由 OzmaDB 检查。

支持 string、number、boolean、json、null。动作 JSON 中的 value 始终是字符串,执行时先替换变量再按选定类型转换。数字文本保留精度,string 不会被当成 JSON 语法。无效 JSON 会报错。模式、对象和字段名称必须固定,不能使用变量。发送写入后若响应丢失,结果可能无法确定,重试前应在 OzmaDB 核对数据。没有确认去重机制时自动重试不安全。显式批量事务仍可使用 HTTP 请求模式。

从 JSON 提取数据

两个数据源动作(包括 HTTP 模式)都有解析响应。可从经过 result_path 或 Ozma 规范化后的动作结果提取,也可从处理前的完整响应提取。主结果键仍生效,规则另外写入指定的 ctx 键。

运行读取预览后,返回行会出现在解析树中;预览本身不会开启解析或更改动作。点击字段创建变量,点击从所有记录收集可取得每行的值,例如把 id 收集为 ids。新规则附加到已有规则,重名时自动加后缀。变量名可改,替换表达式可复制。完整响应、第一条记录和所有 ID提供快速选择,后两者需要样例中有合适数组。写入动作的已创建记录 ID会添加必填 created_id 变量,不会试写。新解析默认使用完整响应,已有解析保留原来源,也可手动切换。可粘贴 JSON 样例并在高级设置修改路径、模式和嵌套 JSON 字符串的解析。大树只显示一部分。样例不写入动作参数或场景分析。检查解析只解析样例,不访问数据源。

例如响应包含嵌套数组和 JSON 字符串:

{
  "results": [{ "id": 9007199254740993 }],
  "groups": [
    { "members": [{ "name": "Alex", "active": false }] },
    { "members": [{ "name": "Sam", "active": true }] }
  ],
  "extra": "{\"status\":{\"ready\":false}}"
}

添加以下解析参数:

{
  "response_parser": {
    "source": "raw",
    "decode_json_strings": true,
    "rules": [
      { "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
      { "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
      { "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
    ]
  }
}

结果保留精确的 created_id,取得 ["Alex","Sam"],并保存布尔值 false。创建成功后,可把 {{ctx.created_id}} 用作下次更新的记录 ID。可提取字符串、数字、布尔值、对象、数组、null,或用 $ 选择整个根对象。解析字符串中的 JSON也会在样例树中展开有效的嵌套 JSON。

路径支持 .name、带 JSON 转义的 ["a.b"]、正负索引([0]、[-1])、通配([*]、.*)、切片([1:3])及 RFC 6901 JSON Pointer。键 a/b 写作 /a~1b,~ 写作 ~0,/ 指向空键名。不支持过滤器、表达式或脚本。单值模式遇到多个匹配会报错;通配路径应选值列表。必填规则未匹配会报错;可选规则未匹配时,单值为 null、列表为 []。预览可区分“找到 null”和“未找到”。所有规则计算完毕后才修改上下文。限制:32 条规则、路径 1024 字节、输入和输出各 1 MiB、每条规则 1000 个匹配,并限制遍历深度与数据量。

Ozma 行 ID 与关联值显示文本

包含主记录 ID(mainId)与包含关联值显示文本(pun)分别启用。include_main_id: true 保存行的 mainId;parse_pun: true 将带显示文本的单元格变为 { "id": 42, "data": "显示文本" }。若与已有 mainId 列冲突会报错。这些选项不改变完整原始响应。读取后可在解析高级设置切换规范化行与完整响应。已有解析会显示对应来源的样例;更换对象、参数或读取标志会清除旧的自动样例。数据树可直接查看,JSON 样例和 JSON 响应按需展开;样例超限时提示和编辑器自动打开。下一动作的变量替换 → 来自之前的动作可找到 created_id,点击 {{ctx.created_id}} 旁的插入,写入光标位置。列表只包含当前块此前动作的结果,重命名、删除或重排会立即更新。

搜索目录与对象元数据

新建 Ozma 读取动作时,上下文中的结果键位于对象设置之前;选中 Ozma 时建议 ozma_rows,重名则加后缀。已有名称和手动清空的字段保留。读取必须填写结果键,写入可以不填,缺失时字段旁会显示错误。

加载目录每页取得 50 个读取视图或写入表。打开从目录选择对象,可按 schema.name 搜索整个远程目录。搜索是不区分大小写的字面子串,_ 和 % 是普通字符。加载更多沿用服务端偏移量。所选对象在其他请求期间保留;目录访问被拒绝时仍可手动填写。可修改查询或重试失败页,无需重填对象。加载参数和字段显示参数是否必填、关联目标、列类型和主表。其他元数据展示未知字段及编码成 JSON 字符串的对象或数组。数字保留精确写法;数据过大或过深时显示限制提示。查看元数据不会改动作或解析规则。

完整的 Ozma 设置流程

连接表单区分名称和类型、实例地址和保存的密钥。其他 HTTP 请求头为空时折叠,有设置时展开。连接检查及结果位于一起,密钥通过链接选择。修改设置后旧检查状态隐藏;旧请求迟到的响应不会验证新设置。

动作中连接与模式相邻,结果键在表单前部,所选 schema.view 或 schema.entity 显示在对象设置上方。手动填写模式和名称对已配置对象折叠,名称为空、无效或访问被拒绝时展开。参数和写入字段按名称、类型、值、删除排列;必填提示常驻,详细说明在类型和变量替换中。读取参数包含分页、主 ID 和关联值显示文本,默认值折叠,非默认值或分页错误时展开。检查读取先以表格展示规范化记录,再按需显示 JSON 响应;空结果给出排查提示,精确数值保留。规范化 JSON 和完整 OzmaDB 响应分别可展开。解析区域按快速选择、结果变量、选择器高级设置、本地样例和检查结果分组。已有 HTTP 动作保留原界面与解析行为。其他元数据直接展开到字段。

下一步