> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 导入
> 使用CSV上传、REST API或手动输入在OneSignal中导入或更新用户。支持电子邮件、短信、标签等，实现无缝用户入门或迁移。
通过CSV文件或手动输入，在OneSignal控制面板中批量导入或更新用户。常见用例包括从另一个平台迁移用户、更新用户详细信息，以及使用[标签](./add-user-data-tags)和[分段](./segmentation)组织用户。
您也可以通过[REST API](/reference/create-user)更新或创建用户。
## CSV导入
使用CSV文件导入或更新电子邮件地址、电话号码、外部ID、[标签](./add-user-data-tags)、语言、时区、国家等。
### CSV要求
确保您的`.csv`文件符合以下要求：
* UTF-8编码（不带BOM）
* 没有不可打印字符（没有特殊字符或非ASCII字符）
* 清晰、唯一的列标题
* 文件大小低于150MB（约200万行）
* 至少包含以下标识符之一：
* `external_id` — 推荐。在所有[订阅](./subscriptions)中识别[用户](./users)。
* `email` — 创建新电子邮件订阅所必需。有关更多信息，请参阅[邮件地址验证](./email-address-validation)。
* `phone_number` — 创建新SMS订阅所必需。
* `subscription_id` — 仅建议在您的后端已跟踪订阅ID并希望设置`external_id`的情况下使用。
每行只允许一个每种类型的标识符。要将多个电子邮件或电话号码与同一用户关联，请使用共享相同`external_id`的单独行。
* 包含`external_id`以去重用户。确保它与SDK `login`方法中使用的ID匹配——否则当用户打开应用时会重置。
* 要更改订阅状态，行必须包含`email`、`phone_number`或`subscription_id`。仅`external_id`是不够的。
* `subscription_id`不会链接或合并订阅。使用`external_id`向现有用户添加新电子邮件或电话号码。
### 支持的列
您的用户ID。有关更多信息，请参阅[外部ID](./users#external-id)。应该是通过SDK `login`方法使用的相同ID。
用户的电子邮件地址。创建电子邮件[订阅](./subscriptions)。如果应用中已存在则去重。
用户的电话号码，使用[E.164格式](https://en.wikipedia.org/wiki/E.164)，如`+15555551234`。创建SMS[订阅](./subscriptions)。如果应用中已存在则去重。
仅建议在您的后端已跟踪OneSignal[订阅ID](./subscriptions)的情况下使用。
设置订阅状态。行必须包含`email`、`phone_number`或`subscription_id`——不能仅使用`external_id`。
与`email`一起使用以添加或从[抑制列表](./suppressions)中移除。
* `true`将电子邮件添加到抑制列表。
* `false`从抑制列表中移除电子邮件。
用户的时区，使用[IANA TZ格式](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。
用户的国家代码，使用[ISO 3166-2格式](https://www.iso.org/obp/ui/)。
用户的语言，使用[ISO 639-1格式](./multi-language-messaging#supported-languages)。
每次导入最多包含1,000个[标签](./add-user-data-tags)。在列标题中使用标签键，在行中使用标签值。您也可以使用单个`tags`列搭配JSON格式——详见[批量标签更新](#bulk-tag-updates)。
#### 标签限制和限制条件
标签[计划限制](https://onesignal.com/pricing)按用户计算，而不是按应用计算。例如，如果您的计划每个用户允许20个标签，而用户已有19个，则只能再添加1个——即使应用本身可以有无限数量的标签键。
* 使用[批量标签更新](#bulk-tag-updates)工作流程导出用户、清除不需要的标签值，并在启用删除选项的情况下重新导入。
* 避免在标签键中使用空格——请改用下划线。
**保留和受限的标签键**
以下标签键已被保留，不应使用：
* "user"
* "subscription"
* "message"
* "template"
* "app"
* "org"
* "custom\_data"
* "dynamic\_content"
如果您意外将其中一个设置为标签键，请通过[更新用户API](/reference/update-user)将其删除。
**标签覆盖和删除**
在CSV导入期间：
* CSV中包含的标签将被提供的值覆盖。
* CSV中未包含的标签在用户记录中保持不变。
如果导入后标签仍然存在，请验证：
* 标题列包含标签键。
* 行不包含任何值。
* 您在[审核屏幕](#review-and-confirm)中选择了"删除具有空值的标签"选项。
**被其他来源添加的标签**
如果删除的标签在导入后重新出现，可能是某个集成正在自动写回它们。常见来源包括：
* Segment
* HubSpot
* Journeys
* SDK标记方法
* 自定义API或ETL管道
检查集成映射和事件触发器，确保它们不会覆盖您的CSV更改。
#### 从单个列导入标签
您可以设置单个`tags`标头，每个用户行包含引号内所有键值对的JSON映射，而不是为每个标签键使用单独的列标头。如果您以前导出了带有标签的CSV并希望重新导入而无需重新格式化，这特别有用。
```text CSV标头示例 theme={null}
external_id,email,tags
```
标签必须格式化为JSON对象，每个键值对周围用2组双引号括起来。
```text CSV行示例 theme={null}
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
```
导入时，OneSignal自动将每个键值对转换为不同的标签。例如，上述行将转换为2个标签：`level:30`和`color:teal`。
**示例：批量删除标签**
要批量删除标签，请导出当前数据，清空标签值，然后启用删除选项重新导入CSV。
* 在OneSignal控制台中，导航到**受众 > 订阅**。仅启用**外部ID**、**订阅ID**和**标签**列（以及可选的**电子邮件**或**电话号码**）。
* 点击**导出**以导出CSV。
在文本编辑器中打开导出的CSV，将每个要删除的标签值设置为空字符串。
例如，编辑前包含标签值的行：
```text 编辑前的行 theme={null}
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
```
清除标签值后的同一行：
```text 清除标签值后的行 theme={null}
userA,example@email.com,"{""level"":"""",""color"":""""}"
```
这将从用户中删除标签`level`和`color`。
* 获取编辑后的CSV并导入。
* 在[审核](#审核并确认)屏幕上，为**删除空值标签**选择**是**。OneSignal在导入期间删除空值的标签。
要仅删除特定标签，请清除这些标签的值，并保持其他标签不变。启用删除选项时，仅删除空值。
需要帮助？
* 尝试上面的[在导入前使用AI检查您的CSV](#use-ai-to-check-your-csv-before-import)部分。
* 联系`support@onesignal.com`并分享您上传的CSV文件以及确认电子邮件的屏幕截图。我们很乐意查看！
#### 邮件地址验证
邮件地址验证在邮件到达您的受众之前检测邮件地址中的常见问题。它标记可能增加退信率或损害发送者声誉的拼写错误、无效域名、基于角色的地址和一次性邮件服务。
在 CSV 导入期间和批量验证邮件地址，以减少退信并保护您的发送者声誉。
#### 在导入前使用AI检查您的CSV
如果您的CSV格式存在错误或疑问，您可以向AI工具（如Claude、ChatGPT或类似工具）描述您的CSV问题，以便在再次导入之前自动清理或重建您的文件。
在导入数千条记录之前，始终使用小样本（5-10行）进行测试。
```text 删除不需要的标签的AI提示示例 theme={null}
我想从这个CSV中删除除"user_name"之外的所有标签。
请：
1. 仅保留"user_name"标签列。
2. 删除所有其他标签列。
3. 格式化CSV使其符合此文档中的OneSignal导入要求：
https://documentation.onesignal.com/docs/en/import
这是我的CSV：
[粘贴CSV]
```
```text 修复多个标签列格式的AI提示示例 theme={null}
我有多个标签列，如tag_first_name、tag_last_name和tag_city。
根据OneSignal导入文档，每个标签必须：
- 使用tag_前缀
- 仅包含字母数字字符和下划线
- 遵循支持的数据类型
您能查看我的CSV，识别格式不正确的内容，并返回符合这些要求的修正版本吗？
文档链接：
https://documentation.onesignal.com/docs/en/import
```
```text 识别缺失或无效格式的AI提示示例 theme={null}
OneSignal在导入期间拒绝了我的CSV。
请：
1. 验证我的CSV结构。
2. 识别任何格式问题（标题、ID列、标签格式、引用）。
3. 返回遵循此文档要求的修正版本：
https://documentation.onesignal.com/docs/en/import#prepare-your-csv
这是文件：
[粘贴CSV]
```
```text 修复无效电话号码格式（E.164）的AI提示示例 theme={null}
我的导入失败，因为电话号码不是E.164格式。
请：
1. 将所有电话号码转换为E.164格式。
2. 保持所有其他字段不变。
3. 确保CSV符合OneSignal的所需结构：
https://documentation.onesignal.com/docs/en/import
当前格式示例：(555) 555-1234
这是我的CSV：
[粘贴CSV]
```
```text 从其他平台迁移的AI提示示例 theme={null}
我正在从[平台名称]迁移到OneSignal。
您能将此CSV转换为符合OneSignal的导入格式吗？
包括：
- `external_id`
- 任何使用`tag_`前缀转换的标签（如果需要）
- E.164格式的电话号码（如果适用）
参考文档：
https://documentation.onesignal.com/docs/en/import
这是我的CSV：
[粘贴CSV]
```
### 导入步骤
导航至**受众 > 导入**并点击**启动CSV导入器**。
选择您准备好的CSV文件。
OneSignal自动将CSV标头映射到已知属性。在确认之前查看映射 — 使用`external_id`、`email`、`phone_number`和/或`subscription_id`作为**标识符**，而非标签。
要向现有用户添加新的电子邮件或电话号码，您**必须使用**`external_id`。**不要**使用`subscription_id` — 它不会链接或合并订阅。
如果OneSignal检测到格式问题，请修复CSV并重新上传（推荐），或取消选中受影响的列以跳过导入。
审核屏幕允许您：
* **自动创建分段** — 在每个导入的用户上添加标签并创建匹配的[分段](./segmentation)。注意您的[计划限制](https://onesignal.com/pricing)。
* **删除具有空值的标签** — 删除CSV中值为空白的任何标签。这有助于清除不需要的标签并保持在计划限制内。
* **配置邮件地址验证** — 配置[邮件地址验证](./email-address-validation)设置以减少退信并保护您的发送者声誉。
例如，给定以下CSV：
```csv theme={null}
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",
```
启用"删除具有空值的标签"后，`tag1`将从UserA中删除，`tag2`将从UserB中删除。
点击**确认并导入**。状态屏幕显示进度。
导入已开始。当导入完成时，您将收到来自`contact@onesignal.com`的确认邮件。
### 电子邮件确认
导入完成后，您将收到来自`contact@onesignal.com`的确认电子邮件，其中包含以下数据。请注意，单个[用户](./users)可以拥有多个[订阅](./subscriptions)（例如，电子邮件 + 推送），因此订阅计数可能高于您的行数。
**已添加的订阅记录** — 创建的新电子邮件或短信[订阅](./subscriptions)。`0` 表示未找到唯一的 `email` 或 `phone_number` 标识符。
**已修改的订阅记录** — 数据发生更改的[订阅](./subscriptions)（标签、属性等）。例如，10 个外部 ID，每个关联 20 个订阅 = 修改了 `200` 条记录。
**跳过的订阅更新** — 因所述原因跳过的[订阅](./subscriptions)。如果原因是"超过您应用的标签限制"，请删除标签并重新导入或升级您的计划。
**未导入** — 未更新或导入的行。常见原因：`external_id` 与任何现有订阅不匹配，或 `email`/`phone_number` 已存在且没有新数据可设置。
**创建的新分段** — 分段名称（如果您选择了该选项）。
在以上示例中：
* 从唯一电子邮件地址或电话号码创建了 `100` 个订阅（这些地址或号码之前不在应用中）。
* 更新了 `37,814` 个订阅（不是用户数量——每个用户可以有多个订阅）。
* `621,852` 行未导入，因为其外部 ID 与现有用户不匹配，或电子邮件/电话号码已存在且没有新数据。
[分段](./segmentation)仅计算**已订阅**的[订阅](./subscriptions)。未订阅的订阅通过导入更新，但不会反映在分段计数中。分段改进正在进行中。
## 手动输入
您可以通过OneSignal控制面板手动添加用户的电子邮件和电话号码订阅，方法是导航到**受众 > 用户 > 更新/导入用户 > 手动添加用户**。
在**新用户**屏幕上，包含您想要的数据并选择**创建用户**。
***
## 常见问题
### CSV导入需要多长时间？
持续时间取决于文件大小。大多数导入在几分钟内完成。导入完成后，您将收到来自`contact@onesignal.com`的电子邮件——将该地址添加到您的联系人以确保送达。
### 可以撤销CSV导入吗？
不可以。CSV导入没有内置的撤销功能。如果您需要撤销更改，请准备一个包含正确值的新CSV并重新导入。对于标签删除，请使用[批量标签更新](#批量标签更新)工作流程。
### 为什么我的段计数与CSV中的行数不匹配？
[段](./segmentation)仅计算**已订阅**的[订阅](./subscriptions)数量。取消订阅的订阅通过导入更新，但不会反映在段计数中。
### 为什么我的导入对某些行显示"未导入"？
当`external_id`与应用中的任何现有订阅不匹配，或者当`email`或`phone_number`已经存在且没有新数据可设置时，行会被跳过。查看[电子邮件确认](#电子邮件确认)部分了解每个状态的详细信息。
### 为什么删除的标签一直回来？
导入后，集成或SDK调用可能会重新添加标签。常见来源包括Segment、HubSpot、Journeys、SDK标签方法和自定义API。查看您的[集成映射](#标签被添加的其他来源)和事件触发器。