👥 ggLeap 用户导入

1. 🧭 介绍

将用户导入 ggLeap 需要配置 CSV 输入字段如何映射到 ggLeap 内部用户数据库。本指南说明支持的用户字段以及如何设置导入映射配置。

2. 📋 支持的用户字段

以下字段目前支持导入用户：

UniversityUserId（仅限大学和 K–12 中心）
Email
Username
FirstName
LastName

3. 📦 导入流程

ggLeap 的导入功能支持用户的创建、更新和归档。

如果您的 CSV 使用自定义列名，请向 ggCircuit 支持团队提交示例以帮助配置映射。
或者，您可以使用 API 自己配置映射（目前没有 UI 配置可用）。

4. ⚙️ 映射配置

4.1 分隔符设置

默认分隔符是 ,，但可以通过指定 null 将其设置为 "auto-detect"。

4.2 映射列：CSV → ggLeap 字段

示例映射配置：

{
"Config": {
"Mappings": {
"UniversityUserId": {
"TargetFieldName": "UniversityUserId",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "UniversityIdNumber"
},
"MembershipPlaytime": {
"TargetFieldName": "MembershipPlaytime",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "Playtime",
"IsCustomField": false
},
"Membership Start Date": {
"TargetFieldName": "Membership Start Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipStartDate",
"IsCustomField": true
},
"Membership End Date": {
"TargetFieldName": "Membership End Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipEndDate",
"IsCustomField": true
},
"Affiliation": {
"TargetFieldName": "Affiliation",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": null,
"IsCustomField": true
}
},
"Enabled": true,
"Delimiter": null,
"DateFormats": ["yyyy-MM-dd"],
"BooleanValues": {
"FalseValues": ["N", "F", "No", "False", "0"],
"TrueValues": ["Y", "T", "Yes", "True", "1"]
},
"NullValues": ["NULL"]
}
}

字段参考：

TargetFieldName：ggLeap 中的目标字段。
IgnoreField：设置为 true 可从导入中排除此字段。
RequireValue：指示是否需要非空值。
SourceHeaderName：源 CSV 中字段的名称。
IsCustomField：对于 ggLeap 中本地不存在的字段，设置为 true（确保这些字段存在于用户详情配置中）。

4.3 已删除字段

true：归档用户
false：取消归档用户

4.4 MembershipPlaytime

定义为导入用户提供的 Gamepass 游戏时间。

4.5 会员日期

为每个用户配置 Gamepass start 和 end 日期。

4.6 更新 CSV 导入配置

使用更新 CSV 导入配置 API 来修改映射。

4.7 获取当前配置

使用获取 CSV 导入配置 API 来获取现有配置。

4.8 取消导入作业

要中止运行中的导入，使用取消用户导入作业 API。

5. ✅ 布尔值

true/false 字段的接受值：

True：Y、T、Yes、True、1
False：N、F、No、False、0

6. 📅 日期格式

CSV 中支持的日期格式：

yyyy-MM-dd
dd/MM/yyyy
MM/dd/yy
dd.MM.yyyy

7. 🗺️ CSV 列映射提示

使用示例格式将源 CSV 标头映射到预期的 ggLeap 字段。您可以根据中心的结构和数据自定义此映射。

🧠 额外的导入逻辑与说明

匹配现有用户

尝试通过 UniversityIdNumber（映射到 StudentId）查找用户。
如果未找到，尝试通过 EmailAddress 匹配。
如果仍未找到：

如果另一个中心具有相同电子邮件：记录冲突，跳过该记录。
如果当前中心存在相同用户名：记录冲突，跳过该记录。
否则：创建新用户，可选择分配 Gamepass。

更新现有用户

更新 CSV 中的所有字段。
在更新 Username 之前，检查当前中心的唯一性。
在更新 EmailAddress 之前，检查全局 ggLeap 的唯一性。
如果用户已归档，设置为已删除。
如果会员值更改，更新或删除 Gamepass：

如果 MembershipStartDate 是 NULL：删除 Gamepass。
否则：替换为新的 MembershipPlaytime。

错误处理与日志

所有错误应在导入日志中记录。
如果发生 5+ 个内部错误，中止导入流程。
对于每个更新/添加的用户，记录操作。
每 2–5 秒更新导入状态/摘要。

更新于： 24/04/2026

这篇文章有帮助吗？

谢谢！