> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 将活动导入到 Maintain

> 学习如何使用用户界面（APM模式）、Cognite工具包或转换导入活动。

Maintain 支持三种导入活动的方法：

* **CSV上传**：使用用户界面（仅限APM模式）导入活动。
* **Cognite工具包**：使用[Cognite工具包](/cdf/deploy/cdf_toolkit/)数据建模（APM和IDM/CDM模式）导入活动。
* **转换**：使用[CDF转换](/cdf/integration/)从RAW表或其他来源转换数据（APM和IDM/CDM模式）。

## 通过CSV上传导入（APM模式）

<Info>
  **模式可用性**：仅限APM模式。IDM/CDM模式不支持在用户界面中进行CSV导入。
</Info>

通过 CSV 导入的活动可以像在 Maintain 中创建的活动一样进行可视化和修改。

<Steps>
  <Step title="下载CSV文件模板">
    导入的CSV文件需要符合您项目特定的模板。下载**maintain-import-template.csv**：

    1. 导航到**活动**并选择**添加活动**。
    2. 选择**导入活动**。
    3. 选择**下载模板**。
  </Step>

  <Step title="填写CSV文件模板">
    CSV模板将仅包含一行值，表示您可以为导入活动提供的可能值。这一行被称为标题行，在填充模板时不应被删除。

    <Tip>
      虽然标题 **行** 不能被删除，但您可以删除标题中的特定值或更改值的顺序。例如，如果某个字段在特定场景下不相关，您可以将其从标题和后续行中删除。这将导致所有导入的活动中该字段留空。
    </Tip>

    要导入单个活动，请在模板中添加新行，并输入用逗号分隔的适当值。新行中的每个值应包含您希望在模板中提供的相应标题行上填充的值。
    例如，如果您的模板包含以下标题行：`标题,状态,部门`，请创建一个包含额外行的CSV文件：

    ```
    标题,状态,部门
    搭建脚手架,完成,吊装
    ```

    导入时，您将创建一个标题为"搭建脚手架"，状态为"完成"，部门为"吊装"的活动。

    <a id="format-date-fields" />

    ### 格式化日期字段

    在 **Maintain** 中的一些活动字段表示日期，必须具有特定格式才能正确导入。日期字段可以通过 CSV 模板中的特殊标题值识别，形式为 `开始时间 (DD/MM/YYYY)`。在这个例子中，`开始时间` 是字段的名称，而 `DD/MM/YYYY` 是需要在 CSV 文件后续行中使用的日期格式。
    例如，导入以下文件将导致活动的 `开始时间` 设置为2023年12月10日。

    ```
    标题,开始时间 (DD/MM/YYYY)
    搭建脚手架,10/12/2023
    ```

    <a id="format-boolean-fields" />

    ### 格式化布尔字段

    在 **Maintain** 中的一些活动字段表示布尔值，例如 `真` 或 `假`。布尔字段可以通过 CSV 模板中的特殊标题值识别，形式为 `是否活动 (真/假)`。这些字段只有两个有效值，`真` 或 `假`。
    例如，导入以下文件将导致活动的 `是否活动` 设置为 `假`。

    ```
    标题,是否激活 (真/假)
    搭建脚手架,假
    ```

    <a id="format-values-containing-commas" />

    ### 格式化包含逗号的值

    由于 CSV 格式使用逗号分隔值，因此在活动字段也需要包含逗号时请小心。**Maintain** 根据 [RFC 4180 标准](https://www.rfc-editor.org/rfc/rfc4180) 处理 CSV 文件，该标准要求包含逗号的值必须用双引号括起来。
    例如，导入以下文件将导致活动被创建，`城市` 设置为 `波士顿, MA`。

    ```
    标题,城市
    搭建脚手架,"波士顿, MA"
    ```

    <a id="unset-values" />

    ### 未设置的值

    您可以在非必填的活动字段中留空，以表示特定活动的缺失或不相关值。
    例如，导入以下文件将导致活动被创建，`州` 设置为 `纽约`，但在`城市`字段中将没有值。

    ```
    标题,城市,州
    搭建脚手架,纽约
    ```

    <a id="connect-an-activity-to-an-asset" />

    ### 将活动连接到资产

    **Maintain** 支持将活动链接到 CDF 资产，用于在 3D 模型、文档、PSN 等中为活动提供上下文。为了让 **Maintain** 创建与 CDF 资产的适当链接，您必须在导入模板中提供 CDF 资产的外部 ID。
    如果您的项目中有资产上下文化，模板中将有一个特殊的`资产外部ID`字段，您需要用活动资产的外部ID填充该字段。
    例如，当导入以下文件并假设存在外部 ID 为 `NY_BUILDING_23` 的 CDF 资产时，活动在导入到 Maintain 时将与该资产相关联。

    ```
    标题,资产外部ID
    搭建脚手架,NY_BUILDING_23
    ```

    如果提供的外部ID未导出，用户在导入时将看到错误。

    <Tip>
      最终用户可能不知道与活动链接的资产的外部ID。如果需要向最终用户提供可能的资产及其外部ID的列表，我们建议使用CDF的[资产API](/api-reference/concepts/20230101/assets)或其他数据提取工具来检索此数据。
    </Tip>
  </Step>

  <Step title="导入已填写的CSV文件">
    一旦您有了填充的 CSV 模板，您可以将其导入到 **Maintain** 中：

    1. 导航到 **活动** > **添加活动**。
    2. 选择**导入活动**。
    3. 选择 **点击选择要导入的 CSV 文件** 字段。
    4. 从您的计算机中选择并上传填充好的 CSV 文件。
    5. 通过检查 **文件检查器** 部分来验证您是否已导入文件。应显示一条绿色消息，指示要导入的行数以及是否有任何警告或错误。
    6. 如果没有错误，请选择 **导入** 开始导入过程。
    7. 当导入成功时，您将看到一条绿色成功消息和 **显示活动** 按钮。
    8. 可选。选择 **显示活动** 导航到导入的活动，并检查它们是否与 CSV 文件中的内容一致。
  </Step>
</Steps>

## 通过 Cognite 工具包导入

<Info>
  **模式可用性**：APM 和 IDM/CDM 模式。这是程序化活动摄取的推荐方法。
</Info>

使用 [Cognite 工具包](/cdf/deploy/cdf_toolkit/) 通过 CDF 的数据建模能力摄取活动。此方法适用于两种部署模式，并提供版本控制和可重复的部署。

### 先决条件

在通过 Cognite 工具包导入活动之前，请确保您拥有：

* 在您的数据模型空间中配置的自定义活动视图（或使用来自 `cdf_idm` 的标准 `CogniteMaintenanceOrder` 视图）
* 在您的 Maintain 配置中映射的活动视图，位于 `viewMappings` 下
* 访问 [Cognite 工具包](/cdf/deploy/cdf_toolkit/)

### 配置活动视图映射

在您的 Maintain 配置中，验证 `viewMappings` 部分是否指向您的活动视图：

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"viewMappings": {
  "activity": {
    "type": "view",
    "space": "cdf_idm",
    "version": "v1",
    "externalId": "CogniteMaintenanceOrder"
  }
}
```

如果您创建了自定义活动视图（例如，`APM_Activity` 或 `ExtendedActivity`），请更新映射以指向您的自定义视图：

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"viewMappings": {
  "activity": {
    "type": "view",
    "space": "maintain_schema_extention",
    "version": "v1",
    "externalId": "APM\_Activity"
  }
}
```

了解更多关于 [扩展数据模型](/cdf/maintain/guides/config#extend-data-models) 和 [配置视图映射](/cdf/maintain/guides/config#view-mappings) 的信息。

### 使用 Cognite 工具包导入活动

在 IDM 模式下，使用 [Cognite 工具包](/cdf/deploy/cdf_toolkit/) 作为导入活动的推荐方法。

<Steps>
  <Step title="创建活动数据结构">
    如果您还没有，请为您的活动创建容器、视图和节点 YAML 文件。遵循标准数据建模结构：

    * `APM_Activity.Container.yaml` - 定义容器架构
    * `APM_Activity.View.yaml` - 定义视图属性和关系
    * `apmActivities.Node.yaml` - 包含您的活动实例
      请参阅 [Cognite 工具包文档](/cdf/deploy/cdf_toolkit/) 以获取详细示例和模板。
  </Step>

  <Step title="配置字段映射">
    确保您的活动节点包含 Maintain 所需的字段：

    | 字段                | 描述                       | 必需 |
    | ----------------- | ------------------------ | -- |
    | `externalId`      | 活动的唯一标识符                 | 是  |
    | `title`           | 活动标题                     | 是  |
    | `status`          | 活动状态（例如，“开放”、“进行中”、“完成”） | 推荐 |
    | `startTime`       | 开始日期/时间                  | 推荐 |
    | `endTime`         | 结束日期/时间                  | 推荐 |
    | `rootLocation`    | 根位置标识符                   | 推荐 |
    | `assetExternalId` | 关联资产的外部 ID               | 可选 |
    | `mainAsset`       | 与资产的直接关系                 | 可选 |

    <Tip>
      根据您在 Maintain 中的 [字段配置](/cdf/maintain/guides/config#field-configuration) 设置包含额外字段。
    </Tip>
  </Step>

  <Step title="部署活动">
    使用 Cognite 工具包部署您的活动数据：

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev
    ```

    如果您需要替换现有活动，请使用 `--drop-data` 标志：

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev --drop-data
    ```

    了解有关[Cognite Toolkit 部署标志](/cdf/maintain/guides/config#critical-deployment-flags)的更多信息。
  </Step>

  <Step title="在 Maintain 中验证">
    1. 登录到 [Maintain](https://maintain.cogniteapp.com)。
    2. 导航到 **活动**。
    3. 验证您导入的活动是否显示正确的数据。
  </Step>
</Steps>

### 使用转换导入活动

<Info>
  **模式可用性**：APM 和 IDM/CDM 模式。这是批量数据的推荐方法。
</Info>

或者，您可以使用[CDF 转换](/cdf/integration/)将来自原始表或其他来源的数据转换为活动节点。

### 故障排除

如果在导入后遇到活动问题，请查看表格以获取原因和解决方案。

| 问题     | 解决方案                      |
| ------ | ------------------------- |
| 活动不可见  | 验证`视图映射`配置是否指向正确的空间、视图和版本 |
| 缺少字段   | 检查您的字段配置是否包含所有正在导入的字段     |
| 资产链接断开 | 确保`资产外部ID`或`主资产`关系指向现有资产  |
| 错误的根位置 | 验证`根位置`是否与您的位置配置匹配        |