> ## 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.

# Amazon S3

> 将来自 Amazon S3 CSV 文件的自定义事件同步到 OneSignal，以根据用户行为触发自动化 Journey 和个性化消息活动。

export const PLATFORM_0 = "S3 CSV"

export const DATA_TYPE_0 = "file columns"

export const COLUMN_HEADER_0 = "CSV Column Example"

export const PROPERTIES_DESCRIPTION_0 = "Event properties as JSON string"

## 概述

OneSignal + Amazon S3 集成可以自动将存储在您的 S3 存储桶中的 CSV 文件中的自定义事件直接同步到 OneSignal 的自定义事件 API。这使您可以基于存储在数据仓库中的真实用户行为触发自动化 Journey 和个性化消息活动。

您可以同步购买、产品浏览、订阅更改或任何自定义用户操作等事件，以自动触发入门序列、重新参与活动、事务性消息以及跨推送通知、邮件、应用内消息和短信的定向促销。

***

## 要求

### OneSignal 要求

* **自定义事件**功能已启用（目前处于测试版 - 请联系 `support@onesignal.com`）

### Amazon S3 要求

* 具有 S3 存储桶访问权限的 **AWS 账户**
* 创建角色和策略的 **IAM 权限**
* 按照 OneSignal 要求格式化的包含事件数据的 **CSV 文件**
* 带有 `.csv` 扩展名的 **UTF-8 编码**逗号分隔文件

***

## 设置

### 准备您的事件 CSV 文件

您的 S3 存储桶必须包含 OneSignal 可以处理的正确格式化的包含事件数据的 CSV 文件：

**文件格式要求：**

* 未压缩、UTF-8 编码、带有 `.csv` 文件扩展名的逗号分隔 CSV 文件
* 包含标题行（OneSignal 将使用标题作为事件字段名称）
* 使用字符串 `#N/A` 表示空值
* 包含逗号的值应用双引号包裹
* 包含双引号的值应用第二个双引号转义

**文件结构：**
OneSignal 将每个**文件夹路径视为独特的数据源**，并将文件名视为该路径内数据的版本。在处理事件时，OneSignal 将始终根据时间戳在选定的文件夹路径中选择最新的数据。

在 S3 中更新事件数据时，您可以替换现有文件或添加更新的版本。OneSignal 将处理新事件并将其发送到自定义事件 API。

### 为 OneSignal 创建 IAM 角色

OneSignal 使用基于角色的身份验证连接到您的 S3 存储桶，遵循 AWS 安全最佳实践。

<Steps>
  <Step title="创建 IAM 角色">
    在您的 AWS 账户中创建一个 IAM 角色，为 OneSignal 的 AWS 账户 ID（`341876425553`）提供对您 S3 存储桶的只读访问权限：

    ```bash theme={null}
    aws iam create-role \
      --role-name OneSignalS3DataImport \
      --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole"
        }]
      }'
    ```

    <Info>
      保存返回的角色 ARN，您将在 OneSignal 配置中需要用到它。
    </Info>
  </Step>

  <Step title="授予 S3 权限">
    为您新创建的角色授予对 S3 存储桶的只读访问权限：

    ```bash theme={null}
    aws iam put-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-name OneSignalS3Access \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:GetBucketLocation"
          ],
          "Resource": [
            "arn:aws:s3:::YOUR_BUCKET_NAME",
            "arn:aws:s3:::YOUR_BUCKET_NAME/*"
          ]
        }]
      }'
    ```

    <Warning>
      将 `YOUR_BUCKET_NAME` 替换为您实际的 S3 存储桶名称。
    </Warning>
  </Step>
</Steps>

### 配置 OneSignal S3 连接

<Steps>
  <Step title="转到数据源">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。
  </Step>

  <Step title="选择 Amazon S3">
    从可用集成列表中选择 **Amazon S3**。
  </Step>

  <Step title="输入连接详细信息">
    提供以下信息：

    * **区域：** 您的 S3 存储桶区域
    * **存储桶名称：** 您的 S3 存储桶名称
    * **角色 ARN：** 第 1 步中的 IAM 角色 ARN
    * **前缀：** 包含您事件 CSV 文件的文件夹路径（可选）
  </Step>

  <Step title="完成安全验证">
    OneSignal 将生成一个独特的外部 ID 并在下一个屏幕上显示。更新您的 IAM 角色以要求此外部 ID：

    ```bash theme={null}
    aws iam update-assume-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
        }]
      }'
    ```

    <Info>
      将 `GENERATED_EXTERNAL_ID` 替换为 OneSignal 仪表板中显示的外部 ID。
    </Info>
  </Step>

  <Step title="测试连接">
    在 OneSignal 中点击**测试连接**以验证设置是否正常工作。
  </Step>
</Steps>

***

## CSV 处理模式

OneSignal 在从您的 S3 存储桶读取事件 CSV 文件时支持两种模式：

### 最新文件模式（默认）

OneSignal 仅处理配置的 S3 前缀和文件夹组中的最新文件。单个文件被解释为要处理的完整事件集。此模式适用于：

* 单个文件包含某个时间段的所有事件
* 随时间添加带有更新事件数据的新版本文件
* 您希望一次处理完整的事件批次

### 合并所有文件模式

OneSignal 获取配置的 S3 前缀和文件夹组中的每个文件，并在处理事件之前将它们合并为单个数据集。此模式适用于：

* 您的事件数据已分拆成多个文件
* 您希望处理来自多个源的事件
* 文件正在以新事件逐步添加

<Warning>
  在合并所有文件模式中，所有 CSV 文件必须具有完全相同的列名称和顺序。
</Warning>

***

## 事件数据映射

连接后，您需要将 CSV 列映射到 OneSignal 自定义事件字段：

<Steps>
  <Step title="查看检测的字段">
    OneSignal 将自动检测您事件 CSV 文件中的列并建议映射。
  </Step>

  <Step title="映射必需的事件字段">
    映射自定义事件的必需字段：

    * **事件名称**（必需）：事件的名称/类型
    * **外部 ID**（必需）：外部用户 ID
    * **事件时间戳**（可选）：事件发生的时间。否则将假定为现在。
  </Step>

  <Step title="配置同步设置">
    设置您的事件处理频率和交付首选项。
  </Step>
</Steps>

***

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

***

## 限制

* **SQL 查询：** S3 源不支持 SQL 查询或对事件数据的高级转换
* **文件大小：** 单个 CSV 文件不应超过 1GB
* **更新频率：** 最小同步间隔为 15 分钟
* **文件类型：** 仅支持 CSV 文件（不支持 JSON、Parquet 等）

***

## FAQ

### 如果我的 CSV 文件有格式错误会发生什么？

OneSignal 将跳过格式错误的行并在集成仪表板中提供详细的错误日志。常见问题包括缺少必需列、无效时间戳格式和不一致的列数。

### OneSignal 多久检查一次新文件？

OneSignal 根据您配置的同步频率检查您的 S3 存储桶，最小间隔为 15 分钟。

***

## 需要帮助？

请联系我们的支持团队（`support@onesignal.com`）或使用应用内聊天获取 S3 集成设置的帮助。