> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Zendesk > 配置 Zendesk 帮助中心文章或支持工单索引，并明确范围、限流与访问边界。 ## 索引内容 每个 Zendesk 连接器只索引一种内容类型：**articles** 或 **tickets**。如果两种类型都需要，请创建两个连接器。管理表单不提供组织、品牌、类别、分区、工单视图或标签范围，因此会读取凭据在该账号内可见的所选内容类型。 | 内容 | 索引行为 | | -------- | -------------------------------------------------------------------------------------- | | Articles | 每篇有正文的已发布文章会成为一个文档，包含解析后的正文文本、来源链接、可用时的作者、标签与 content tag。草稿、无正文文章，以及带有部署级跳过标签的文章会被忽略。 | | Tickets | 每个未删除工单会成为一个文档，包含主题与 ticket-comments 端点返回的评论正文。状态、优先级、标签与工单类型会存为元数据。 | | 附件 | 不会下载或索引文章与工单评论中的附件文件。 | | 范围 | 没有项目或组织选择器。凭据可见性与所选内容类型共同定义摄取边界。 | ## 前置条件 * 从 `https://.zendesk.com` 确认 Zendesk 账号子域。 * 启用 token 访问，并为获准的 Zendesk 用户创建 API token。 * 允许连接器 worker 通过 HTTPS 访问该账号的 Zendesk API。 * 授予 Help Center 文章与 Guide content tag 的访问权限。当前连接器会验证文章端点，并在任一内容模式运行前加载 content tag。 * 对于 **tickets**，需保持 Zendesk Support 已启用，并授予 incremental ticket export 与工单评论访问权限。用户端点访问只是可选的作者元数据增强：没有该权限时，提交者与评论作者详情可能缺失，但工单和评论文本仍可索引。 ## 凭据 | 方式 | OpenCore 凭据值 | 说明 | | ----------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Zendesk API token | `zendesk_subdomain: `、`zendesk_email: `、`zendesk_token: ` | OpenCore 以 `/token` 和 API token 认证，并构建 `https://.zendesk.com/api/v2`。 | 在 **Zendesk 子域**中输入账号的租户名称，而不是通用 API Base URL。连接器可以接收以 `https://` 开头的值并移除 `.zendesk.com` 后缀，但使用裸子域可以避免路径或协议歧义。 Zendesk 用户端点访问是可选的作者元数据增强。如果作者查询返回 HTTP 错误，OpenCore 会省略对应提交者或评论作者元数据，并继续构建文章或工单文档。 ## 在 OpenCore 中配置 1. 在管理后台打开**连接器**，选择 **Zendesk**，并创建包含子域、邮箱与 token 的凭据。 2. 在**内容类型**中选择 **articles** 或 **tickets**。单个连接器不能同时索引两种模式。 3. 可以设置**每分钟 API 调用次数**。这是连接器本地上限，会应用于该连接器的文章、工单、评论、用户与 content-tag 请求。 4. 对受限支持内容选择**私有**并分配 OpenCore 群组。仅当每个 OpenCore 账号都可以搜索全部已索引文章或工单时才使用**公开**。 5. 设置刷新与清理选项，创建连接器并运行首次索引。 6. 如需同时索引文章与工单，请使用另一内容类型重复以上步骤，创建第二个连接器。 ## 权限 Zendesk 凭据控制连接器可以摄取哪些内容，但 Zendesk 的文章、工单、组织、品牌、角色与终端用户限制不会同步到 OpenCore。连接器的轻量文档路径只返回 ID 与创建日期，不包含源访问记录。 索引后，搜索访问由连接器的 OpenCore **私有**群组或**公开**模式决定。能够访问该连接器的任意用户都可以搜索每个成功索引的文档，即使该用户无法在 Zendesk 中打开对应文章或工单。应尽可能通过范围更窄的 Zendesk 凭据拆分敏感内容，并使用独立的 OpenCore 连接器与群组。 ## 验证 1. 验证凭据，并确认其可以调用 Help Center 文章端点。 2. 运行一次索引。对于 **articles**，搜索一篇已发布且非草稿文章的文本；对于 **tickets**，搜索一个工单主题与一条返回的评论正文。 3. 确认草稿文章或已删除工单不存在。 4. 确认只有附件中存在的文本无法搜索。 5. 使用已获 Zendesk 授权的浏览器会话打开结果链接，确认其指向预期租户及文章或 agent 工单。 6. 使用每个已分配的 OpenCore 群组测试搜索访问，因为查询时不会重新检查 Zendesk 权限。 ## 故障排除 | 症状 | 检查项 | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 请求指向错误租户或返回 404 | 只输入账号子域。移除路径、`http://` 前缀或其他 Zendesk 主机后缀。 | | 验证返回 401 | 替换过期或无效 token，并确认邮箱属于 token 用户。 | | 验证返回 403 | 为凭据授予 Help Center 文章与 content tag 访问权限；工单模式还需要工单与评论访问权限。用户端点访问仅用于作者元数据增强。 | | 工单索引提示 Support 未启用 | 为账号启用 Zendesk Support，或改用 **articles** 模式。 | | 文章缺失 | 检查文章是否为草稿、没有正文、带有部署级跳过标签，或对凭据不可见。 | | 工单或评论缺失 | 已删除工单会被跳过。检查凭据可见性，以及 incremental-ticket 或 ticket-comments 请求。用户查询返回 HTTP 错误时，只会省略提交者或评论作者元数据，工单与评论文本仍可生成。其他异常（例如 timeout 或 JSON parsing 错误）仍可能传播，并使该文档产生 ConnectorFailure。 | | 附件文本缺失 | 这是预期行为；不会下载或索引附件 payload。 | | 索引缓慢或反复收到 429 | 检查**每分钟 API 调用次数**与 Zendesk 账号限制。服务器 `Retry-After` 延迟最多会执行 60 秒，之后请求重试逻辑继续。 | | 用户能搜索但无法在 Zendesk 中打开内容 | 这是预期行为，因为源 ACL 不会同步。使用 OpenCore 群组限制连接器，或拆分数据源。 | ## 相关页面 * [连接器与索引](/opencore/knowledge/connectors) * [索引设置](/opencore/knowledge/index-settings)