# 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":[]}' # リクエストボディの詳細は以下を参照してください
```

### エンドポイント

```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.  ユーザーをプッシュする際に所属部門がまだ作成されていない場合、その部門と関連付けることはできません。部門データがプッシュされた後に、再度ユーザーデータをプッシュしてください。
    :::