从单个单元格获取结果
安装 GenderAPI for Google Sheets 插件并在其 Formula 设置中保存密钥后，输入 =GENDER(A2) 即可分析单元格 A2 中的姓名。借助可选参数，您可以选择电子邮箱地址或用户名作为输入，并指定地理背景和额外的结果列。
GENDER 是插件自带的公式。它不接受 V2 的 JSON 请求对象，也不会返回 V2 的响应结构。
编写公式之前先保存密钥
- 打开“扩展程序”（Extensions）→ GenderAPI → Determine Gender，然后在侧边栏菜单中进入 Formula 页面。
- 选择一个已保存的 API 密钥，或输入您的密钥并保存。请把凭据保存在侧边栏中，而不要放在共享的单元格里。
- 在 A2 中输入一个具有代表性的值，并把公式放在另一个单元格中。如果您要请求额外信息，请在右侧预留空间。
- 把公式复制到其他行之前，请先检查结果以及侧边栏中当前的说明。
参数按以下顺序排列
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
input | 文本或单元格引用 | 必填 | 一个姓名、电子邮箱地址或用户名，例如 A2。 |
method | 文本 | name | 根据输入选择 name、email 或 username。 |
country_filter | 文本 | 不按国家/地区筛选 | 可选的两位字母国家/地区代码。如需在 additional_info 之前省略此参数，请使用空字符串。 |
additional_info | 布尔值 | FALSE | TRUE 会在相邻列中返回额外字段。FALSE 只返回性别。 |
每一行都是一个独立的公式。请选择与 A2 中的值相对应的方法。这些示例展示的是语法，并不保证得到特定的结果。根据表格的区域设置，参数分隔符可能是分号而不是逗号。
=GENDER(A2)
=GENDER(A2, "email")
=GENDER(A2, "username")
=GENDER(A2, "name", "IT", TRUE)
=GENDER(A2, "email", "", TRUE)为扩展结果预留空间
启用 additional_info 时，Google Sheets 侧边栏中当前的说明列出了四个值，顺序为：性别、国家/地区、probability 和规范化后的名字。这一顺序与 Excel 公式不同。设置列标题时，请查看已安装插件的说明。
请让所有目标单元格保持为空，以便数组能够展开。数组被阻挡、缺少密钥或平台错误都需要单独解决：它们不是结果为 unknown 的预测。
| 位置 | Sheets 当前说明 | 处理方式 |
|---|---|---|
| 1 | Gender | 把未解析的结果保存为 unknown，并与错误信息分开。 |
| 2 | Country | 查询返回的背景信息，而不是经过核实的位置。 |
| 3 | Probability | 把这个沿用下来的值与结果一起保存。不要把它重命名为 V2 的 confidence。 |
| 4 | Normalized name | 在其他地方使用之前，请检查根据您的输入得出的名字。 |
了解重新计算和缓存备注
该公式是动态的。输入发生变化或表格重新计算时，可能需要重新处理。插件可能会添加一条包含公式和缓存结果的备注，但这条备注并不能保证之后每次重新计算都不会发送新请求或消耗积分。
Google 对自定义函数和 URL Fetch 施加的执行限制与 GenderAPI 积分无关。根据 Google 当前的文档，每次执行自定义函数的时长上限为 30 秒。同时运行的公式过多或请求过慢都可能导致错误，即使您的账户仍有积分。
如果您需要一个稳定的快照，请复制已填写的结果，并以值的形式粘贴到另一个范围。这份副本不再依赖公式。同时请保存原始输入和核对日期。
规划积分、限制和重新运行
已注册的免费 GenderAPI 账户每天包含 200 个积分。这是账户余额，并不承诺每个工作流都能得到 200 个已识别的结果。开始之前，请检查所选密钥的余额以及该工具当前的处理选项。
插件和文件处理遵循各自的处理流程。V2 REST API 的批量限制、AI 选项和每个请求的计费字段并不会自动适用于这些工具。重新运行或重新计算可能会发送新的请求并消耗积分，因此不要默认它是免费的。
请先从小样本开始，保存已得到的结果，并在重新运行之前复核失败的行。如果您只需要修正一次导出或目标系统中的更新，请复用已有的结果。
何时直接使用 V2 API
如果您的应用需要明确的 AI 选项，并需要每个条目的 V2 status、source、confidence_kind 和 usage 信息，请配置单独的 HTTP 集成。请遵循 V2 的请求和响应契约：把 V2 字段名添加到插件自带的公式或现有插件中，并不会改变它们的行为。
常见问题
这个公式叫 GENDER_API 吗？
不是。Google Sheets 插件的文档说明的是 =GENDER(input, method, country_filter, additional_info)。Microsoft Excel 使用的是其他名称：GENDER.FROM_NAME、GENDER.FROM_EMAIL 和 GENDER.FROM_USERNAME。
不按国家/地区筛选时，可以请求额外字段吗？
可以。把第三个参数留空即可，例如 =GENDER(A2, "email", "", TRUE)。额外字段随后会展开到相邻的单元格中。
缓存备注能让重新计算免费吗？
已保存的结果可以复用，但这条备注并不能保证之后的每次执行都不会发送新请求。请关注积分，并在不需要动态重新计算时保存固定值。
所有编辑该表格的人都能自动使用这个公式吗？
不要默认如此。请确认插件对相关用户和该文档可用并已获得授权。如果接收者只需要已填写的结果，请只分享一份仅包含值的副本。
来源与文档
本指南最近一次审核于 。请在平台文档中确认安装方式；如需单独构建 V2 集成，请使用下列 API 文档。