WebHook-API
WebHook API的定义
WebHook API是由插件后端自己实现的Web API，它需要满足酷大师定义的API格式和返回值类型，并注册到酷大师后端。酷大师后端会在合适的时机，调用注册好的插件WebHook API
插件注册自己的WebHook API时，需要指定事件类型（eventName），这样，酷大师后端就知道该在什么时候调用哪个WebHook API
目前，酷大师支持以下三种事件类型的WebHook API注册
| 事件类型名称 | 功能 |
|---|---|
| get-ext-model | 获取模型数据 |
| copy-ext-model | 复制模型数据 |
| delete-ext-model | 删除模型数据 |
每一个消息类型的注册对应一类WebHook API，目前我们有三类WebHook API：
- 模型获取API
- 模型复制API
- 模型删除API
1. 模型获取API
API签名：
POST {external-application-api}?modelIndex={modelIndex}
其中 modelIndex 为插件自定义的参数名，{modelIndex} 为插入到酷大师的外部模型的索引值。酷大师利用此索引值作为外部模型在酷大师方案中的唯一标识符
举例1： POST /geom/api/modeling/plugin/model?brandGoodId={brandGoodId}
举例2： POST /geom/api/model/3dtext/model?modelIndex={modelIndex}
API需能处理以下请求头：
Headers
| Header Name | Value Type | Necessity | Default | Details |
|---|---|---|---|---|
| x-qh-model-usage | Integer | Required | 1 | LOD |
x-qh-model-usage = 0， 表示请求的模型用于出离线渲染效果图，期望第三方应用提供一个较精细的模型
x-qh-model-usage = 1，表示请求的模型用于在前端界面显示，期望第三方应用提供一个较粗糙的模型
将来酷大师还可能扩展x-qh-model-usage = 3，用于在移动端显示等等，那时第三方应用可以提供一个更加轻量级的模型
每一个x-qh-model-usage的取值，都有一系列支持的模型格式。目前支持的模型格式情况如下：
| x-qh-model-usage | obj | renderinfo | displayinfo | dmxDesignData |
|---|---|---|---|---|
| 0 | Y | Y | N | Y |
| 1 | Y | N | Y | Y |
API返回的消息体必须满足如下格式：
返回值中：
“c“ 为状态码
”m" 为错误信息
“d” 为业务逻辑返回内容，此处即为插件返回的3d模型表达。其中“t”为3d模型的格式，“r”为3d模型实际内容。
”t“ 可取值为 obj, displayinfo，renderInfo，dmxDesignData 等 (其中 obj 供三方开发者使用，displayInfo, renderInfo, dmxDesignData仅限群核内部二方开发团队使用）
displayInfo
displayInfo格式举例
{
"c": "0"， //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": "错误消息"，//错误提示信息，"c":"0"则无
"d": {
"t": "displayinfo",// 资源类型
"r": { // 资源内容
components: [
{
mtl: [...]
transform: '1.0, 0.0, .... ',
id: 'T2HWSZUHT...',
mesh: '//qhsmodel.kujiale.com/pop/T2HWSZU.../m.pop'
}
]
}
}
}
obj
obj 格式举例
{
"c": "0"， //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": "错误消息"，//错误提示信息，"c":"0"则无
"d":{
"t": "obj",// 资源类型
"r": { // 资源内容
"zipUrl":"https://qhgeom.oss-cn-hangzhou.aliyuncs.com/dev/2020/04/03/models_4951478_3813.zip",
"size":200 //单位为K
}
}
}
// zip 文件为标准的obj文件，包含 .obj .mtl 材质贴图文件，参考 https://www.cnblogs.com/daofaziran/p/11541522.html
renderInfo
renderInfo格式举例
renderInfo example
{
"c": "0",
"m": "错误消息",
"d": {
"t": "renderInfo",
"r": [
{
"transform": [0, 0, 0, 1 ....],
"meshInstance": {
"type": "MeshInstance",
"UUID": 1,
"mMesh": {
"type": "MeshWithFile",
"UUID": 2,
"attributes": {
},
"fileName": {
"0": "2017/12/22/SNPMUCGO7DSS2DEDLY888888.hrt"
},
"valid": true,
"boundingBox": {
"min": {
"x": -45.0,
"y": -44.808,
"z": -3.95
},
"max": {
"x": 45.0,
"y": 44.808,
"z": 3.95
}
},
"id": "SNPMUCGO7DSS2DEDLY888888"
},
"mComponents": [{ //用于指定每个component对应的mat
"UUID": 47,
"mIndex": 0,
"mComponentName": "obj2",
"mMaterial": {
"type": "VrayBasicMaterialName",
"UUID": 48,
"parameters": {
"color": {
"type": "Float3",
"UUID": 49,
"value": "5.0,5.0,5.0",
"variableName": "color"
},
"twoSided": {
"type": "Integer",
"UUID": 50,
"value": "0",
"variableName": "twoSided"
},
"version": {
"type": "Integer",
"UUID": 51,
"value": "1",
"variableName": "version"
}
},
"simplifyTag": 0,
"shaderName": "VRayLightMtl",
"id": "5a3d26bc52b61460220a9c39",
"imgs": "",
"lightMeshAddress": "",
"materialAddress": "",
"geomHairAddress": ""
}
}],
"mMeshInfoTypeId": 0,
"mId": "SNPMUCGO7DSS2DEDLY888888",
"mReplaceable": "0"
}
}
]
}
}
2. 模型复制API
API签名：
POST {external-application-api}?modelIndex={modelIndex}
其中modelIndex为插件自定义的参数名，{modelIndex} 为插入到酷大师的外部模型的索引值。酷大师利用此索引值作为外部模型在酷大师方案中的唯一标识符
举例1： POST /geom/api/modeling/plugin/model/copy?brandGoodId={brandGoodId}
举例2： POST /geom/api/model/3dtext/model/copy?modelIndex={modelIndex}
API返回的消息体必须满足如下格式：
返回值中：
“code“ 为状态码
”msg" 为错误信息
"success" 为调用是否成功
“resData” 为业务逻辑返回内容，此处即为插件返回的复制好了的 modelIndex
3. 模型删除API
API签名：
DELETE {external-application-api}?modelIndex={modelIndex}
其中modelIndex为插件自定义的参数名，{modelIndex} 为插入到酷大师的外部模型的索引值。酷大师利用此索引值作为外部模型在酷大师方案中的唯一标识符
举例1： DELETE /geom/api/modeling/plugin/model?brandGoodId={brandGoodId}
举例2： DELETE /geom/api/model/3dtext/model?modelIndex={modelIndex}
API返回的消息体必须满足如下格式：
返回值中：
“code“ 为状态码
”msg" 为错误信息
"success" 为调用是否成功
“resData” 为业务逻辑返回内容，此处即为插件返回删除好了的 modelIndex
WebHook API的注册、注销、更新和查询
除了使用酷家乐开放平台提供的WebHook注册页面，插件后端服务还可以使用以下酷大师后端API，对自己提供的WebHook进行动态注册、注销、更新和查询
Register webhook
API签名：
POST /geom/api/modeling/plugin/webhooks/v1
Body Structure
{
"baseUrl": "/external-application-api/{modelIndex}",
"eventName": "get-ext-model",
"appKey": "com.kujiale.custom.window-door-app",
"doamin": "https://www.kujiale.com"
}
Response
{
"c": "0", //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": null, //错误提示信息，"c":"0"则无
"d": null
}
上述示例中，请求数据代表的意义为：
注册一个消息类型为get-ext-model（获取模型）的webhook API，
他的完整链接为“https://www.kujiale.com/external-application-api/{modelIndex}”
（其中domain为“https://www.kujiale.com”， baseUrl为"/external-application-api/{modelIndex}"。
这个webhook属于appKey为"com.kujiale.custom.window-door-app"
Unregister webhook
API签名：
DELETE /geom/api/modeling/plugin/webhooks/v1
Query String Parameters
| Body Parameter Name | Value Type | Necessity | Details |
|---|---|---|---|
| webhookId | String | Required | webhookId |
Response
{
"c": "0", //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": null, //错误提示信息，"c":"0"则无
"d": null
}
Update webhook
API签名：
PUT /geom/api/modeling/plugin/webhooks/v1
Body Structure
{
"webhookId": 11
"baseUrl": "/external-application-api/{modelIndex}",
"eventName": "get-ext-model",
"appKey": "com.kujiale.custom.window-door-app",
"doamin": "https://www.kujiale.com"
}
Response
{
"c": "0", //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": null, //错误提示信息，"c":"0"则无
"d": null
}
Query webhook
API签名：
Get /geom/api/modeling/plugin/webhooks/v1/query
Body Structure
{
"eventName": "get-ext-model",
"appKey": "com.kujiale.custom.window-door-app"
}
Response
{
"c": "0", //状态码，成功为0，错误的情况下返回上述统一格式的错误码
"m": null, //错误提示信息，"c":"0"则无
"d": {
[
{
"webhookId": 11,
"baseUrl" : "external-application-api/{modelIndex}",
"eventName" : "get-ext-model"，
"appKey"："com.kujiale.custom.window-door-app",
"domain": "https://www.kujiale.com"
}
]
}
}