集成山海鲸编辑端

如果需要将山海鲸的编辑界面直接集成到系统中，首先需要先开启山海鲸软件的 SaaS 模式，然后通过 iFrame 方式将山海鲸的 SaaS 界面整合进来，通过 Saml2.0 的协议接入单点登录，同时通过 API 的方式实现自动的项目的创建，项目的删除等等功能。

1.打开 SaaS 服务

打开软件后，在软件左侧列表中找到 Saas 服务，点击按钮启动 SaaS 服务：

可以得到一个 SaaS 的地址，将这个地址嵌入到 iFrame 中既可完成最简单的系统整合。

（注意：网络公开版的 SaaS 服务需要联系客服申请开通）

2.单点登录

SaaS 服务虽然提供了子账号，不过我们在整合的时候，一般希望能用自己系统的账号来登录。山海鲸 SaaS 服务中提供了基于 Saml2.0 的单点登录功能，进需要填入证书和登录的 Entry Point 即可实现单点登录功能。

具体项目如下表所示：

配置项	说明
Issuer	非设置项，当前 SP 的发证名称，需要在 Idp 端填入。
登录地址	单点登录配置好后直接访问这个地址即可实现登录跳转
Cert	Idp 的证书 BASE64，不含证书头尾（纯 BASE64 字符串），不含回车
Entry	Idp 的登录地址
SP Meta	sp 的 metadata 文件地址，可以提供给 idp
Sign Assertions	是否对断言签名，默认开启，可以根据 idp 的设置进行调整。
Sign Response	是否对响应签名，默认开启，可以根据 idp 的设置进行调整，但建议开启。

注意单点登录设置好了之后，需要重启软件才能生效。

3.服务端 API

服务端 API 是在整合了页面后，通过后台接口直接操作山海鲸服务器进行的一系列操作：

3.1 授权登录接口

1	POST /api/v1/login

Post 参数

配置项	说明
username	子账号名称（注意是 SaaS 的子账号）
password	子账号密码

返回内容：

{
    "account": {
        "id": "vxuc3g6ac9btj7xu0mwb",
        "user": "test",
        "nickName": "test",
        "avatar": "",
        "createTime": 1695016819752,
        "updateTime": 1695016819752,
        "loginTime": 1702970396022,
        "disabled": false
    },
    "user": {
        "id": 1054647,
        "nickname": "",
        "loginName": "XXX@shanhaibi.com",
        "key": "123456AAA-MzUxZjk0YW",
        "keyAlias": null,
        "secret": "U1ODk5MGJkYjNkNz-123456AAA351f9",
        "money": null,
        "sessionId": "ShanhaiBI_1702954207876",
        "sessions": {
            "ShanhaiBI_1701844282735": {
                "clientIdentifier": "DESKTOP-38F8R7H-105481.70757788072",
                "lastVersion": "4.1.1-beta.5 win32",
                "loginTime": 1701844277
            },
        },
        "present": 0,
        "phone": "",
        "noPassword": false,
        "coin": 0,
        "onlineLimit": 11,
        "state": "none",
        "saas": true,
        "saasSeats": 5,
        "timeSaasEnd": 1734576606,
        "time_pay": 0,
        "coupons": [],
        "projectQuota": 500,
        "startTime": 0,
        "endTime": 0,
        "portrait": "",
        "author": 2
    },
    "accessToken": "此处返回的内容为token"
}

获取到 accessToken 后，后续将此 Token 拼合到后续所有请求的 Header 中既可实现 API 授权流程。

Header 中添加 authorization 项，内容写成 Bearer accessToken

注意 Bearer 后面有一个空格，具体在 postman 中的效果如下：

3.2 项目管理接口

1	GET /api/v1/project/list

返回格式如下：

[
    {
        "id": "ktujbphysm4h",//项目ID
        "name": "我的空白项目",//项目名称
        "createTime": 1702445569332,//创建时间戳
        "folder": "",//文件夹id
        "report": "",//报表系统id
        "new": true,//是否是新项目
        "snapshotted": true,//是否有封面截图
        "version": 3,//项目版本
        "boardsCount": 1,//看板数量
        "showPlayer": true,//是否显示控制条
        "cloudRendering": false,//是否启用云服务
        "widgetPlan": "",
        "visitorMode": true,
        "directAccess": true,
        "embedWeb": true,
        "embedIpWhiteList": [],
        "shareId": "",
        "cloudHosting": false,
        "allowZooming": true,
        "clientVersion": 4,
        "cachedExpireTime": 0
    },
]

1	POST /api/v1/project/add

配置项	说明
name	新项目名称
parentId	项目文件夹 id，可留空

1	POST /api/v1/project/copy

配置项	说明
id	被复制的项目 ID
parentId	复制到的项目文件夹 id，可留空

1	POST /api/v1/project/delete

配置项	说明
id	需要删除的项目 ID

1	POST /api/v1/project/destroy

配置项	说明
id	需要清理的项目 ID