用户导出 API¶
用户导出 API 允许开发者将用户批量导出为 CSV 或 ndjson 文件。
导出过程是异步的，也就是说该过程在后台运行。因此，您需要先调用一个端点发起导出任务，然后再调用另一个端点获取该导出任务的状态。
身份验证 ¶
如需使用用户导出 API，您的应用必须先使用 Admin API JWT 令牌完成身份验证。
获取有效的 Admin API JWT 后，您可以将其设置为 Bearer Authorization 请求头，用于访问用户导出 API 的各个端点。如果使用的 JWT 无效，API 将返回 "403 Forbidden" 错误。
端点¶
用户导出 API 有以下两个端点：
发起导出任务 ¶
POST /_api/admin/users/export
使用此端点创建新的用户导出任务。
请求头
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <Admin API JWT Token> |
| Host | <Your Authgear Project domain> |
请求体
发起导出端点通过 HTTP(S) 请求体接收 JSON 格式的输入，以下是输入示例：
{
"format": "csv",
"csv": {
"fields": [
{
"pointer": "/sub",
"field_name": "user_id"
},
{
"pointer": "/email"
}
]
}
}
format字段用于指定导出文件的格式，取值可以是csv或ndjson。csv：当format设置为csv时使用此字段。其值是一个包含fields属性的对象。csv.fields：可以使用此字段列出您想要包含在 CSV 文件中的所有用户属性字段。其值应为数组，数组中的每一项都是一个对象，包含pointer属性和可选的field_name属性，用于描述一个用户属性。
用户资料属性指针¶
以下是支持的指针完整列表：
| Pointer | Description | Value |
|---|---|---|
/sub |
sub 是 "subject"（主体）的缩写，是 OIDC 中的标准字段。其值是 Authany 为该用户生成的唯一 ID |
String |
/preferred_username |
用户设置的用户名。 | String |
/email |
与当前用户账号关联的邮箱地址 | String |
/phone_number |
与当前用户账号关联的手机号码 | String |
/email_verified |
一个布尔值，表示用户邮箱当前的验证状态。取值可以是 true 或 false。 |
Boolean |
/phone_number_verified |
如果关联的手机号码已验证，返回 true；未验证则返回 false。 |
Boolean |
/name |
用户的显示名称。 | String |
/given_name |
用户的名字 | String |
/middle_name |
用户的中间名 | String |
/nickname |
用户设置的昵称。 | String |
/profile |
用户资料的链接 | String |
/picture |
包含用户头像的 URL。 | String |
/website |
用户的网站，即用户在资料中网站属性所设置的值。 | String |
/gender |
保存当前用户设置的性别值（male、female 或其他字符串）。 | String |
/birthdate |
用户在资料的标准属性中设置的生日。 | String |
/zoneinfo |
用户的时区，例如 Asia/Hong_Kong、Europe/London。 |
String |
/locale |
用户设置的显示语言，例如英语用 en 表示。 |
String |
/address/street_address |
用户在地址标准属性中为街道地址字段设置的值。 | String |
/address/locality |
用户在地址标准属性中为城市（locality）字段设置的值。 | String |
/address/region |
用户在地址标准属性中为"州 / 省 / 地区"字段设置的值。 | String |
/address/postal_code |
用户地址标准属性中的邮政编码。 | String |
/address/country |
用户在地址标准属性中为国家字段设置的值。 | String |
/roles |
分配给当前用户的所有角色列表。 | Array |
/groups |
用户已加入的所有访问管理用户组列表。 | Array |
/disabled |
用户账号的状态。账号未禁用时值为 false，已禁用时值为 true。 |
Boolean |
/identities |
与用户账号关联的所有身份的列表。其值的结构如下：[{"claims":{"email":"user@gmail.com"},"login_id":{"key":"email","original_value":"user@gmail.com","type":"email","value":"user@gmail.com"},"type":"login_id"},{"claims":{"phone_number":"+447012341234"},"login_id":{"key":"phone","original_value":"+44712341234","type":"phone","value":"+447012341234"},"type":"login_id"}] |
Array |
/mfa/emails |
用户添加的、用于接收双重验证登录链接或 OTP 的邮箱地址列表。 | Array |
/mfa/phone_numbers |
用户添加的、用于通过短信或 WhatsApp 接收 OTP 的手机号码列表。 | Array |
/mfa/totps |
一份 JSON 对象的列表，其中包含 secret 和 uri 等 TOTP 详细信息。以下是该字段数据结构的示例：[ { "secret":"ABCD1234EF...", "uri":"otpauth://totp/user@gmail.com?algorithm=SHA1\u0026digits=6\u0026issuer=https%3A%2F%2F127.0.0.1\u0026period=30\u0026secret=ABCD1234EF..." } ] |
Array |
/biometric_count |
用户已注册的生物识别数量。 | Integer |
/passkey_count |
用户已注册的通行密钥数量。 | Integer |
如果未指定 csv.fields，导出的 CSV 文件将包含上述所有指针作为字段。
自定义属性的 pointer 值遵循以下格式：
例如，名为 member_id 的自定义属性对应的值将是 {"pointer": "/custom_attributes/member_id"}。
如果未提供 field_name，则会根据以下规则从 pointer 派生：
- 令
parts为pointer中的引用标记（reference token）列表。 - 用字符
.连接parts。
例如，按照上述规则，{"pointer": "/address/formatted"} 派生出的 field_name 将是 address.formatted。
响应
发起导出端点的 HTTP(S) 请求体如下所示：
id：该字段的值是检查状态端点所需的导出任务 ID。created_at：包含导出任务的创建日期和时间。status：任务创建成功时返回pending。
错误响应
| Description | Name | Reason | Info |
|---|---|---|---|
| 当用户导出功能被禁用时 | InternalError |
UserExportDisabled |
- |
| 当超出速率限制时 | TooManyRequest |
RateLimited |
{"bucket_name": "UserExport"} |
| 当已有正在运行的导出任务时 | TooManyRequest |
MaximumConcurrentJobLimitExceeded |
- |
| 当输入未通过验证时 | Invalid |
ValidationFailed |
该信息应包含 JSON schema 验证的输出结果 |
| 当字段名称不唯一时 | Invalid |
UserExportNonUniqueFieldNames |
输出完整的 "field_names" 列表。例如 {"field_names": ["sub", "a", "b", "a"]} |
检查状态 ¶
GET /_api/admin/users/export/{Task ID}
使用此端点查询现有导出任务的状态。请将 {Task ID} 替换为发起导出端点响应体中返回的任务 id。
请求头
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <Admin API JWT Token> |
| Host | <Your Authgear Project domain> |
响应
以下是检查状态端点响应体的示例：
{
"result": {
"id": "userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ",
"created_at": "2024-10-07T21:06:24.361634372Z",
"completed_at": "2024-10-07T21:06:24.551711713Z",
"status": "completed",
"request": {
"format": "csv",
"csv": {
"fields": [
{
"pointer": "/sub",
"field_name": "user_id"
},
{
"pointer": "/email"
},
{
"pointer": "/mfa/emails"
}
]
}
},
"download_url": "https://storage.googleapis.com/authgear-userexport-staging/example-userexport_userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ-20241007210624Z.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=authgear-server%40oursky-kube.iam.gserviceaccount.com%2F20241007%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20241007T210641Z&X-Goog-Expires=59&X-Goog-Signature=abcd12e45&X-Goog-SignedHeaders=host"
}
}
status字段反映当前导出任务的进度。当值为completed时，表示导出已完成，您现在可以下载导出文件。download_url：这是一个签名 URL，可用于下载导出文件。
Note： 已完成的导出任务的结果会在 24 小时后过期。因此，超过 24 小时后，您将无法再使用该任务对应的任务 ID 生成新的下载链接。
错误响应
| Description | Name | Reason | Info |
|---|---|---|---|
| 当用户导出功能被禁用时 | InternalError |
UserExportDisabled |
- |
| 当给定的 ID 不对应任何导出任务时 | NotFound |
TaskNotFound |
- |
下载导出文件 ¶
检查状态端点的响应中会包含 download_url 字段，该字段是一个签名 URL，您可以打开它下载 CSV 或 ndjson 格式的用户导出文件。
该签名 URL 仅在 60 秒内有效，超时后，您需要使用任务 ID再次请求检查状态端点以获取新的 URL。
使用示例¶
如需了解如何使用用户导出 API 的详细示例，请参阅以下指南：