fusion-help-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion Help API

Use this skill when a developer or admin needs to interact directly with the Fusion Help REST API — whether to read help content in their own app, build custom tooling, or automate content management.

当开发者或管理员需要直接与Fusion Help REST API交互时，可使用本skill——无论是在自己的应用中读取帮助内容、构建自定义工具，还是自动化内容管理。

When to use

适用场景

App developer wants to display help articles, FAQs, or release notes inside their Fusion app
Developer building a custom CLI or automation script to manage help content
Admin wants to programmatically create, update, or delete help documentation
Developer needs to search or suggest help content from their application
Someone wants to understand the Help API endpoints, authentication, or data models
Building an integration that reads help content for another system

应用开发者希望在其Fusion应用内展示帮助文章、常见问题（FAQ）或发布说明
开发者构建自定义CLI或自动化脚本以管理帮助内容
管理员希望以编程方式创建、更新或删除帮助文档
开发者需要从其应用中搜索或推荐帮助内容
想要了解Help API的端点、认证方式或数据模型的用户
构建集成以向其他系统读取帮助内容的场景

When not to use

不适用场景

Using the
```
fhelp
```
CLI tool to sync markdown docs (use the
```
fusion-help-docs
```
skill instead)
Modifying the Fusion.Services.Help backend service code
General REST API questions unrelated to Help

使用
```
fhelp
```
CLI工具同步Markdown文档（请改用
```
fusion-help-docs
```
skill）
修改Fusion.Services.Help后端服务代码
与Help无关的通用REST API问题

Required inputs

必填输入项

Input	Required	Description
Use case	Yes	Reading content, managing content, or searching
App key	For scoped queries	The Fusion app key to read/manage help for
Target environment	Yes	`ci` , `fqa` , `tr` , or `fprd`
Auth context	Yes	User token (interactive) or service principal (automation)

输入项	是否必填	描述
使用场景	是	读取内容、管理内容或搜索
应用密钥	范围查询时需要	用于读取/管理对应Fusion应用的帮助内容的密钥
目标环境	是	`ci` 、 `fqa` 、 `tr` 或 `fprd`
认证上下文	是	用户令牌（交互式）或服务主体（自动化）

Instructions

操作步骤

1. Discover the Help API base URL

1. 查找Help API的基础URL

The Help API is registered in the Fusion service discovery. Resolve the URL dynamically or use the known patterns:

Environment	Base URL
`ci`	`https://help.ci.api.fusion-dev.net`
`fqa`	`https://help.fqa.api.fusion-dev.net`
`fprd`	`https://help.api.fusion.equinor.com`

Dynamic discovery (recommended for production tooling):

GET https://discovery.fusion.equinor.com/service-registry/environments/{env}/services

Look for the service with

key: "help"

in the response. Use the

uri

field as the base URL.

Help API已在Fusion服务发现中注册。可动态解析URL，或使用已知的固定格式：

环境	基础URL
`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

字段作为基础URL。

2. Authentication

2. 认证

All endpoints require a valid Azure AD bearer token. Token audiences and code samples for frontend, backend, and CLI are in references/authentication.md.

Quick reference — token audiences:

Environment	Resource ID (audience)
`ci` , `fqa` , `tr`	`5a842df8-3238-415d-b168-9f16a6a6031b/.default`
`fprd`	`97978493-9777-4d48-b38a-67b0b9cd88d2/.default`

所有端点都需要有效的Azure AD承载令牌。前端、后端和CLI的令牌受众及代码示例请查看references/authentication.md。

快速参考——令牌受众：

环境	资源ID（受众）
`ci` 、 `fqa` 、 `tr`	`5a842df8-3238-415d-b168-9f16a6a6031b/.default`
`fprd`	`97978493-9777-4d48-b38a-67b0b9cd88d2/.default`

3. Authorization levels

3. 授权级别

Action	Who can do it
Read articles, FAQs, release notes, search	Any authenticated Fusion user
Create / Update / Delete articles, FAQs, release notes	App admin, trusted app, or `Fusion.Help.FullControl`
Upload assets (images)	App admin, trusted app, or `Fusion.Help.FullControl`
View changelog (global)	`Fusion.Help.FullControl` only
View changelog (per app)	App admin or `Fusion.Help.FullControl`

操作	允许执行者
读取文章、FAQ、发布说明、搜索	任何已认证的Fusion用户
创建/更新/删除文章、FAQ、发布说明	应用管理员、受信任应用或拥有 `Fusion.Help.FullControl` 权限的用户
上传资源（图片）	应用管理员、受信任应用或拥有 `Fusion.Help.FullControl` 权限的用户
查看变更日志（全局）	仅拥有 `Fusion.Help.FullControl` 权限的用户
查看变更日志（按应用）	应用管理员或拥有 `Fusion.Help.FullControl` 权限的用户

4. Call the API

4. 调用API

Endpoints are versioned — include

?api-version=1.0

in requests. Resources: Articles, FAQs, Release Notes, Assets, Search/Suggest, Changelog.

For full CRUD details, request/response bodies, OData filters, and validation rules see references/api-endpoints.md.

For a compact endpoint matrix and OData cheat sheet see references/api-quick-reference.md.

For detailed response model schemas see references/response-models.md.

端点采用版本化管理——请求中需包含

?api-version=1.0

。资源包括：Articles、FAQs、Release Notes、Assets、Search/Suggest、Changelog。

完整的CRUD详情、请求/响应体、OData筛选器和验证规则请查看references/api-endpoints.md。

如需紧凑的端点矩阵和OData速查表，请查看references/api-quick-reference.md。

如需详细的响应模型架构，请查看references/response-models.md。

5. Integration patterns

5. 集成模式

Ready-to-use code samples for common scenarios (React component, release notes banner, FAQ search, C# backend automation, Python scripting) are in references/integration-patterns.md.

常见场景的即用型代码示例（React组件、发布说明横幅、FAQ搜索、C#后端自动化、Python脚本）请查看references/integration-patterns.md。

Expected output

预期输出

When this skill completes, the user should have:

Working code to authenticate and call the Help API
Correct endpoint URLs and query parameters for their use case
Understanding of the response models and OData query options
For admin use cases: correct request bodies for create/update/delete operations
For integration patterns: sample code in the relevant language/framework

当本skill完成后，用户应获得：

用于认证并调用Help API的可运行代码
符合其使用场景的正确端点URL和查询参数
对响应模型和OData查询选项的理解
针对管理员场景：用于创建/更新/删除操作的正确请求体
针对集成模式：对应语言/框架的示例代码

Safety & constraints

安全与限制

Read-only endpoints are safe for any authenticated user — no admin permissions needed
Write operations require app admin, trusted application, or
```
Fusion.Help.FullControl
```
Deleted articles/FAQs/release notes are soft-deleted — their slugs cannot be reused
The
```
sourceSystem
```
field tracks which tool created a record — mixing source systems for the same slug will cause the
```
fhelp
```
CLI to refuse updates (unless
```
--no-validation
```
is used)
Always test against
```
ci
```
environment before targeting
```
fprd
```
(production)
Do not hardcode bearer tokens — always use
```
DefaultAzureCredential
```
or equivalent token providers
Image uploads must be PNG format; the API processes them into WebP for serving

只读端点对任何已认证用户安全可用——无需管理员权限
写入操作需要应用管理员、受信任应用或
```
Fusion.Help.FullControl
```
权限
删除的文章/FAQ/发布说明为软删除——其slug无法重复使用
```
sourceSystem
```
字段记录创建记录的工具——同一slug混合使用不同源系统会导致
```
fhelp
```
CLI拒绝更新（除非使用
```
--no-validation
```
参数）
针对
```
fprd
```
（生产环境）操作前，务必先在
```
ci
```
环境测试
请勿硬编码承载令牌——请始终使用
```
DefaultAzureCredential
```
或等效的令牌提供程序
图片上传必须为PNG格式；API会将其处理为WebP格式后提供