> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md).

# 获取叙事数据

Convai Unreal Engine 插件在……下提供两个异步 Blueprint 节点 **Convai|REST API** 用于从 Convai 获取角色的叙事章节和触发器。使用这些节点可以在调用触发器之前验证触发器名称、填充动态 UI，或在加载界面期间预缓存叙事数据。

这些节点是可选的。正常的剧情推进路径是 **调用叙事设计触发器** on `UConvaiChatbotComponent`，而不是先获取再调用。

### 先决条件

* Convai Unreal Engine 插件已安装，并且 API 密钥已配置。参见 [配置您的 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* 一个有效的 `CharacterId` ，与……匹配的 `CharacterID` 在目标上 `UConvaiChatbotComponent`.
* 在获取节点执行时需要网络访问。获取节点会向 Convai 发起 HTTPS POST 请求。

### 获取叙事章节

**Convai 获取叙事章节** 是由……实现的异步潜伏式 Blueprint 节点 `UFetchNarrativeSectionsProxy`。它会 POST 到 `character/narrative/list-sections` 并返回在控制台中为该角色配置的章节。

| 引脚            | 方向     | 类型                          | 说明                                                              |
| ------------- | ------ | --------------------------- | --------------------------------------------------------------- |
| `CharacterId` | 输入     | `FString`                   | 要查询的角色 ID。必须与……匹配 `CharacterID` 在目标上 `UConvaiChatbotComponent`. |
| `成功时`         | 输出（执行） | —                           | 当 HTTP 请求成功且响应被解析为……时触发 `FNarrativeSection` 条目的数组。              |
| `失败时`         | 输出（执行） | —                           | 当激活验证失败、响应指针无效，或 HTTP 响应超出 `2xx` 范围时触发。                         |
| `叙事章节`        | 输出     | `TArray<FNarrativeSection>` | 成功时返回的章节。失败时为空。                                                 |

**要在 Blueprint 中添加该节点：**

1. 右键单击事件图并搜索 `获取叙事章节`.
2. 选择 **Convai 获取叙事章节** 位于 **Convai|REST API**.
3. 将 `CharacterId` 输入设置为与……使用的值相同 `UConvaiChatbotComponent` 你正在使用的那个。
4. 将节点连接到两个 **成功时** 是位于 **失败时** 执行引脚。

### 获取叙事触发器

**Convai 获取叙事触发器** 是由……实现的异步潜伏式 Blueprint 节点 `UFetchNarrativeTriggersProxy`。它会 POST 到 `character/narrative/list-triggers` 并返回该角色叙事图中配置的触发器。

| 引脚            | 方向     | 类型                          | 说明                                                 |
| ------------- | ------ | --------------------------- | -------------------------------------------------- |
| `CharacterId` | 输入     | `FString`                   | 要查询的角色 ID。                                         |
| `成功时`         | 输出（执行） | —                           | 当 HTTP 请求成功且响应被解析为……时触发 `FNarrativeTrigger` 条目的数组。 |
| `失败时`         | 输出（执行） | —                           | 当激活验证失败、响应指针无效，或 HTTP 响应超出 `2xx` 范围时触发。            |
| `叙事触发器`       | 输出     | `TArray<FNarrativeTrigger>` | 成功时返回的触发器。失败时为空。                                   |

每个 `FNarrativeTrigger` 结果中的……会暴露 `trigger_name`, `trigger_id`, `trigger_message`，以及 `destination_section` 作为 `BlueprintReadOnly` 字段。 `trigger_name` 字段是你传递给……的内容 **调用叙事设计触发器**.

### 何时调用获取节点

在加载时调用获取节点，不要在游戏过程中重复调用：

* **开始游戏** — 在任何触发器被调用之前先获取，这样游戏开始时数据就已就绪。
* **加载界面** — 在玩家无法与角色交互时，与其他加载工作并行获取。
* **编辑器实用 Blueprint** — 无需打开 Convai 控制台即可在 Unreal Editor 中检查角色的叙事图。

{% hint style="warning" %}
每次执行时，获取节点都会向 Convai 发起一次 HTTPS 请求。不要在 Tick 中或响应重复的游戏事件时调用它们。将结果缓存到 Blueprint 变量中并重复使用。
{% endhint %}

### 处理结果

在 **成功时** 的引脚 **Convai 获取叙事触发器**，遍历 `叙事触发器` 数组并提取每个 `trigger_name` 到一个 `TSet<FString>` 或 Map 变量中。在调用 **调用叙事设计触发器**之前，检查目标名称是否在集合中。

在 **成功时** 的引脚 **Convai 获取叙事章节**，遍历 `叙事章节` 并使用每个 `section_id` 是位于 `section_name` 来填充下拉菜单或调试覆盖层。

有关完整的触发器验证步骤，请参阅 [叙事设计使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-usage-examples.md#fetch-triggers-to-validate-names-before-invoking).

### 验证获取结果

在 Play In Editor 中运行获取节点后：

1. 确认 **成功时** 执行引脚已触发（而不是 **失败时**).
2. 检查 `叙事章节` 或 `叙事触发器` — 数组应包含你查询的角色对应的条目。
3. 如果 **失败时** 触发时，检查 **输出日志** 用于 `ConvaiNarrativeHTTP` 消息。请参阅 [排查叙事设计问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md).

{% hint style="info" %}
如果 HTTP 请求成功，但响应数组无法解析为叙事结构体，获取代理可能会在不触发 **成功时** 或 **失败时**。如果潜伏节点似乎卡住了，请检查 **输出日志** 用于 `ConvaiNarrativeHTTP` 并在确认该角色在控制台中已有叙事数据后重试。
{% endhint %}

### 下一步

{% content-ref url="/pages/ff19704aac20f7d6e4bf5c3214636ccbe4248151" %}
[叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/579f95b35d1b473357f37588e6fc915a03231497" %}
[叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/609986e3902c22d2027f232e5ffaaa507011c8a0" %}
[排查叙事设计问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.