---
pkg: '@nocobase/plugin-user-data-sync'
title: "通过 HTTP API 同步用户数据"
description: "NocoBase 通过 HTTP API 同步用户数据：POST /api/userData:push、UserData/DepartmentData 格式、API 密钥、Bearer token。"
keywords: "HTTP API,用户数据同步,userData:push,API 密钥,Bearer token,NocoBase"
---

# 通过 HTTP API 同步用户数据

## 获取 API 密钥

参考 [API 密钥](/auth-verification/api-keys), 需要确保 API 密钥设置的角色具有用户数据同步权限。

## API 说明

### 示例

```bash
curl 'https://localhost:13000/api/userData:push' \
  -H 'Authorization: Bearer <token>' \
  --data-raw '{"dataType":"user","records":[]}' # 请求体见下文详细说明
```

### Endpoint

```bash
POST /api/userData:push
```

### 用户数据格式

#### UserData

| 参数名     | 类型                               | 说明                                                                     |
| ---------- | ---------------------------------- | ------------------------------------------------------------------------ |
| `dataType` | `'user' \| 'department'`           | 必填，推送的数据类型，推送用户数据填 `user`                              |
| `matchKey` | `'username' \| 'email' \| 'phone'` | 选填，会根据提供字段和推送数据中对应的字段值去查询系统已有用户，进行匹配 |
| `records`  | `UserRecord[]`                     | 必填，用户数据记录数组                                                   |

#### UserRecord

| 参数名        | 类型       | 说明                                                                                 |
| ------------- | ---------- | ------------------------------------------------------------------------------------ |
| `uid`         | `string`   | 必填，来源用户数据的唯一标识，用于关联来源原始数据和系统用户。对于同一个用户不可变。 |
| `nickname`    | `string`   | 可选，用户昵称                                                                       |
| `username`    | `string`   | 可选，用户名                                                                         |
| `email`       | `string`   | 可选，用户邮箱                                                                       |
| `phone`       | `string`   | 可选，手机号                                                                         |
| `departments` | `string[]` | 可选，用户所属部门 uid 数组                                                          |
| `isDeleted`   | `boolean`  | 可选，记录是否删除                                                                   |
| `<field>`     | `any`      | 可选，其他用户表中的自建字段数据                                                     |

### 部门数据格式

:::info
推送部门数据的前提是安装并开启[部门](../../departments)插件。
:::

#### DepartmentData

| 参数名     | 类型                     | 说明                                              |
| ---------- | ------------------------ | ------------------------------------------------- |
| `dataType` | `'user' \| 'department'` | 必填，推送的数据类型，推送部门数据填 `department` |
| `records`  | `DepartmentRecord[]`     | 必填，部门数据记录数组                            |

#### DepartmentRecord

| 参数名      | 类型      | 说明                                                                                 |
| ----------- | --------- | ------------------------------------------------------------------------------------ |
| `uid`       | `string`  | 必填，来源部门数据的唯一标识，用于关联来源原始数据和系统部门。对于同一个部门不可变。 |
| `title`     | `string`  | 必填，部门标题                                                                       |
| `parentUid` | `string`  | 可选，上级部门 uid                                                                   |
| `isDeleted` | `boolean` | 可选，记录是否删除                                                                   |
| `<field>`   | `any`     | 可选，其他部门表中的自建字段数据                                                     |

:::info

1. 数据多次推送幂等。
2. 如果推送部门时，父部门还未创建，则无法关联上，可再次推送数据。
3. 如果推送用户时，部门还未创建，则无法关联上所属部门，可在推送部门数据后，再次推送用户数据。
   :::
