> 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 Fetch Narrative Sections 和 Convai Fetch Narrative Triggers 查询角色的叙事区段和触发器。

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

这些节点是可选的。正常的剧情推进路径是 **调用叙事设计触发器** 在 `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. 右键单击 Event Graph 并搜索 `获取叙事区段`.
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** — 在 Unreal Editor 中检查角色的叙事图，而无需打开 Convai 仪表板。

{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.