{% endtab %}
{% tab title="脚本编写" %}
通过以下方式访问终端用户操作 `client.EndUsers` 在一个 `ConvaiRestClient` 实例上。
```csharp
using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
```
请参阅下面的每个方法以查看完整示例。
{% endtab %}
{% endtabs %}
***
### `EndUserDetails` 字段
每条终端用户记录都由以下内容表示 `EndUserDetails`:
| 属性 | 类型 | 说明 |
| ---------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `EndUserId` | `string` | SDK 在连接时发送的稳定标识符 |
| `LastActiveTs` | `string` | 上次会话的 ISO 8601 时间戳 |
| `LastLtmUsageTs` | `string` | 上次 LTM 交互的 ISO 8601 时间戳 |
| `Metadata` | `Dictionary` | 由 IEndUserMetadataProvider 发送的键值数据 `IEndUserMetadataProvider` |
| `DisplayName` | `string` | **计算属性** — 读取 `Metadata["name"]` 如果存在且非空；否则 `"User {EndUserId[..8]}"`，并可选择附加相对的最后活动时间（例如， `"User a1b2c3d4 (3d ago)"`) |
| `ShortId` | `string` | **计算属性** — 的截断形式 `EndUserId` 用于紧凑显示（例如， `"a1b2c3d4...ef01"`) |
`DisplayName` 和 `ShortId` 是 C# 计算属性，不是存储字段。它们不会出现在 JSON API 响应中。
***
### 脚本 API
#### 列出终端用户
使用基于游标的分页检索所有终端用户记录。默认限制为每页 50 条记录。
```csharp
using Convai.RestAPI;
using Convai.RestAPI.Internal;
using System.Collections.Generic;
using UnityEngine;
public class EndUserLister : MonoBehaviour
{
[ContextMenu("List All End Users")]
private async void ListAllEndUsers()
{
using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
string cursor = null;
bool hasMore = true;
var allUsers = new List();
while (hasMore)
{
var response = await client.EndUsers.ListAsync(limit: 50, cursor: cursor);
if (response.EndUsers != null)
allUsers.AddRange(response.EndUsers);
hasMore = response.HasMore;
cursor = response.NextCursor;
if (!hasMore || string.IsNullOrEmpty(cursor))
break;
}
Debug.Log($"终端用户总数：{allUsers.Count}");
foreach (var user in allUsers)
Debug.Log($" {user.EndUserId} — 最后活动：{user.LastActiveTs}");
}
}
```
**`EndUsersListResponse` 字段：**
| 属性 | 类型 | 说明 |
| ------------ | ---------------------- | -------------------------- |
| `EndUsers` | `List` | 此页上的记录 |
| `TotalCount` | `int` | 终端用户记录总数 |
| `NextCursor` | `string` | 下一页的游标令牌； `null` 当不存在更多页面时 |
| `HasMore` | `bool` | 是否存在更多页面 |
你也可以使用以下方式按活动日期筛选 `activeAfter` 和 `activeBefore` （ISO 8601 字符串）：
```csharp
var response = await client.EndUsers.ListAsync(
limit: 50,
activeAfter: "2025-01-01T00:00:00Z",
activeBefore: "2025-06-01T00:00:00Z");
```
***
#### 获取单个终端用户
通过其 `endUserId`.
```csharp
var user = await client.EndUsers.GetAsync("target-end-user-id");
Debug.Log($"最后活动：{user.LastActiveTs}");
Debug.Log($"显示名称：{user.DisplayName}");
```
***
#### 更新用户元数据
更新用户的一个或多个元数据键。补丁操作会保留你未包含的键——它不会替换整个元数据对象。
```csharp
var patch = new Dictionary
{
{ "name", "Jordan Kim" },
{ "department", "Facilities Management" }
};
var updated = await client.EndUsers.UpdateMetadataAsync("target-end-user-id", patch);
Debug.Log($"已更新 {updated.EndUserId} 的元数据。");
```
***
#### 删除终端用户
{% hint style="danger" %}
`DeleteAsync` 会移除终端用户记录 **以及该用户在所有角色中的所有记忆记录**。与 `MemoryService.DeleteAllAsync`不同，后者仅作用于一个角色，而此操作会全局移除该用户。此操作无法撤销。
{% endhint %}
```csharp
var result = await client.EndUsers.DeleteAsync("target-end-user-id");
if (result.Deleted)
Debug.Log($"终端用户 {result.EndUserId} 已删除。");
else
Debug.LogWarning("删除返回 false — 用户可能不存在。");
```
***
### `DeleteAllAsync` 与 `DeleteAsync`
| 操作 | 作用域 | 删除的内容 |
| ------------------------------------------------------ | ----------- | ---------------- |
| `client.Memory.DeleteAllAsync(characterId, endUserId)` | 一个用户 + 一个角色 | 该用户-角色配对的所有记忆记录 |
| `client.EndUsers.DeleteAsync(endUserId)` | 一个用户 + 所有角色 | 用户记录以及跨所有角色的所有记忆 |
使用 `DeleteAllAsync` 当你想重置某个用户在特定角色中的记忆，同时保留其在其他角色中的记录时。使用 `EndUsers.DeleteAsync` 当你需要将用户从系统中完全移除时。
***
### 后续步骤
{% content-ref url="/pages/0b7e1084a14c3bcf13fec179ad83b458f07ecff4" %}
[记忆管理 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/memory-management-api.md)
{% endcontent-ref %}
{% content-ref url="/pages/9c55a31cd790424665e521972bff5affc2dbe7f9" %}
[长期记忆脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/long-term-memory-scripting-reference.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-unity-sdk/features/long-term-memory/end-user-management.md?ask=&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.
