SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场fusion-help-api

fusion-help-api

编程与开发

查看项目

更新于 10-14 08:07

技能介绍

Fusion Help API 技能用于指导开发者或管理员直接与 Fusion Help REST API 交互，例如读取帮助内容、构建自定义工具或自动化内容管理。

用途

以下情况适合使用本技能：在 Fusion 应用中展示帮助文章、FAQ 或发布说明；构建自定义 CLI 或自动化以管理帮助内容；以编程方式创建、更新或删除帮助文档；从应用中搜索或建议帮助内容；理解 Help API 端点、身份验证或数据模型；为其他系统读取帮助内容。

以下情况不适用：使用 fhelp CLI 同步 markdown 文档（应使用 fusion-help-docs）；修改 Fusion.Services.Help 后端服务代码；与 Help 无关的一般 REST API 问题。

必需输入

  • 用例：必需，说明是读取内容、管理内容还是搜索。
  • App key：用于限定范围的查询，指定要读取或管理帮助的 Fusion 应用密钥。
  • 目标环境：必需，可取 ci、fqa、tr 或 fprd。
  • 身份验证上下文：必需，用户令牌（交互式）或服务主体（自动化）。

使用方式

  1. 发现 Help API 基地址：可动态解析或使用已知模式。环境与基地址对应关系为：ci 对应 https://help.ci.api.fusion-dev.net；fqa 对应 https://help.fqa.api.fusion-dev.net；fprd 对应 https://help.api.fusion.equinor.com。生产工具推荐动态发现：GET https://discovery.fusion.equinor.com/service-registry/environments/{env}/services，在响应中查找 key 为 "help" 的服务，使用其 uri 字段作为基地址。

  2. 身份验证：所有端点需要有效的 Azure AD bearer token。令牌受众的快速参考为：ci、fqa、tr 使用 5a842df8-3238-415d-b168-9f16a6a6031b/.default；fprd 使用 97978493-9777-4d48-b38a-67b0b9cd88d2/.default。前端、后端与 CLI 的代码示例见 references/authentication.md。

  3. 授权级别：任何经过身份验证的 Fusion 用户可以读取文章、FAQ、发布说明及搜索；应用管理员、受信任应用或 Fusion.Help.FullControl 可以创建/更新/删除文章、FAQ、发布说明；应用管理员、受信任应用或 Fusion.Help.FullControl 可以上传资产（图片）；仅 Fusion.Help.FullControl 可以查看全局变更日志；应用管理员或 Fusion.Help.FullControl 可以查看每个应用的变更日志。

  4. 调用 API：端点为版本化，需包含 ?api-version=1.0。资源包括 Articles、FAQs、Release Notes、Assets、Search/Suggest、Changelog。完整的 CRUD 细节、请求/响应体、OData 过滤器和验证规则见 references/api-endpoints.md；精简端点矩阵与 OData 速查表见 references/api-quick-reference.md；响应模型 schema 见 references/response-models.md。

  5. 集成模式：即用型代码示例（React 组件、发布说明横幅、FAQ 搜索、C# 后端自动化、Python 脚本）见 references/integration-patterns.md。

预期输出

可用的身份验证与调用 Help API 的代码；针对用例正确的端点 URL 和查询参数；对响应模型与 OData 查询选项的理解；管理用例下正确的创建/更新/删除请求体；集成模式下相关语言/框架的示例代码。

安全与限制

只读端点对任何经过身份验证的用户安全，无需管理员权限；写操作需要应用管理员、受信任应用或 Fusion.Help.FullControl；已删除的文章/FAQ/发布说明为软删除，slug 无法重用；sourceSystem 记录创建记录的工具，同一 slug 混合来源系统会导致 fhelp CLI 拒绝更新（除非使用 --no-validation）；始终先在 ci 上测试，再以 fprd 为目标；切勿硬编码 bearer token，应使用 DefaultAzureCredential 或等效方式；图片上传必须为 PNG，API 会将其处理为 WebP 供提供。