接口调用说明 #
http请求方式: POST（请使用https协议）
https://xxxxxx.com.cn/api_url通过POST提交筛选条件
{
"format":"matrix",
"openStrategy":true,
"objective":"search",
"extendable":true,
"type":"原料",
"isTypeExclude":true,
"edge":["子品牌", "别称", "描述"],
"isEdgeExclude":false,
"direction":"forward",
"limit":5,
"init":true,
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
},
"existing":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
},
"token":"4tyhnjiutrcquawdbwsniuh23"
}| 参数 | 是否必须 | 说明 | 备注 |
|---|---|---|---|
| openStrategy | 否 | 是否接受方舟的缓存策略，开启时优先获取缓存 | |
| filters | 否 | 筛选条件 | |
| existing | 否 | existing中的节点互相之间不再适用与objective的运算 | |
| objective | 否 | 接口请求意图，有六个可能的值分别是search, findMutualFriends, findSimilar, findShortestPath, findMatch, buildRelationship,分别表示查询、寻找共同的Top关联节点，寻找相似节点、最短路径、寻找契合节点、建立关系，默认值search | new |
| extendable | 否 | 节点是否可外延，默认值是true，开启时获取目标节点以及其关联节点 | |
| type | 否 | 希望拓展的球的类型，仅extendable=true时生效 | |
| isTypeExclude | 否 | 与type参数结合使用，表示节点拓展类型传参是否取非逻辑(反选)，isTypeExclude=true时取非，默认取false | |
| edge | 否 | 希望拓展的关系类型，仅extendable=true时生效 | |
| isEdgeExclude | 否 | 与edge参数结合使用，表示关系拓展类型传参是否取非逻辑(反选)，isEdgeExclude=true时取非，默认取false | |
| direction | 否 | 拓展节点与已有节点的方向，其值可以是forward、backward、bilateral，默认值forward | new |
| limit | 否 | 希望拓展的球的数量，默认是5，仅extendable=true时生效 | |
| init | 否 | 是否是初始化请求(初次渲染，而非在原图上拓展) | |
| token | 按需 | 如果接口开启了安全校验，则必须传该值 |
返回说明 #
正确时返回的 Response Headers
X-Matrix-IsCache: true #当前返回的data是否是缓存
X-Matrix-TookTime: 0.036 #从接收到请求到返回结果用时，方舟统计
X-Matrix-Type: openapi #接口是使用什么方式发布的
X-Matrix-Version: 2 #接口版本，当前规范就是2
X-Matrix-Url: openapi/3RS3/leo/a_graph #接口在方舟上发布的地址
X-Matrix-Name: 原料品牌图谱 #接口在方舟上的名称正确时返回的 Response
{
"code":0,
"success" : true,
"message" : "success",
"data":{
"meta":{
"datasetType" : "graph",
"parameters" : [ {
"schemeField" : "type",
"apiParam" : "category"
}, {
"schemeField" : "label",
"apiParam" : "label"
} ],
"dimensions" : ["type","label","key1"],
"fieldsInfo" : [ {
"fieldName" : "type",
"fieldAlias" : "类型",
"fieldIsNested" : 0,
"fieldIsArray" : 0,
"fieldIsAnalyzed" : 0,
"fieldType" : "String"
}, {
"fieldName" : "label",
"fieldAlias" : "节点",
"fieldIsNested" : 0,
"fieldIsArray" : 0,
"fieldIsAnalyzed" : 0,
"fieldType" : "String"
} ]
},
"dataset": {
"init": true,
"type": {
"艺术家": [
"风格",
"流派"
],
"流派": [
"艺术",
"风格",
"艺术家",
"几何"
],
"几何": [],
"风格": [],
"艺术": []
},
"nodes": [
{
"id": "n1",
"label": "爱德华.蒙克",
"type": "艺术家",
"value": 200,
"description": "挪威表现主义画家，现代表现主义绘画的先驱，主要作品《呐喊》《生命之舞》",
"debut":1595387206000,
"attribute": {
"时代": "19-20世纪",
"感情基调": ["悲伤","压抑"],
"流派": "表现主义"
}
},
{
"id": "n2",
"label": "达.芬奇",
"type": "艺术家",
"value": 210,
"debut":1595387206000,
}
],
"edges": [
{
"id": "e1",
"source": "n1",
"target": "n2",
"value": 45990,
"description": "不同时期的艺术家",
"debut":1595387206000,
"attribute": {
"attr1": "123123123",
"attr2": "asdasdasd",
"volume": 345,
"vtype": "蓝v"
}
},
{
"id": "e2",
"source": "n2",
"target": "n1",
"value": 435002,
"description": "肯定没有见过面，但蒙克看过达芬奇作品",
"debut":1595387206000,
"attribute": {
"attr1": "123123123",
"attr2": "asdasdas123d",
"volume": 5432
}
}
]
}
}
}关键参数说明
| 参数 | 说明 | 备注 |
|---|---|---|
| data.dataset.init | 是不是用于初始化渲染 | |
| data.dataset.type | 这个图中所有可能的type，以及每种type可能关联的type | |
| data.dataset.nodes | 返回的所有的节点，以及每个节点的属性 | 属性名是自由的 |
| data.dataset.edges | 返回的所有的边，以及每个边的属性 | 属性名是自由的 |
节点和边的属性名是自由的，但是产生联动的时候，会按照
{
"属性名1":"值1",
"属性名2":"值2"
}这样的方式传值，尤其是在自身拓展新节点的时候，方舟没有暴露为变量更名的入口，所以开发者需要在requests和response中维护对应的属性名一致，这十分重要。
例如，如果你在data.dataset.nodes中，像下面这样用"关注对象"这个变量来作为节点的名称
{
"nodes": [
{
"id": "n1",
"关注对象": "微电流",
"type": "技术",
"value": 200,
"description": "微电流技术在许多领域都发挥着重要作用",
"attribute": {
"情感": "正面",
"volume": 200,
"vtype": "普通用户"
}
}]
}那么你需要在parameters中，声明你接收的变量包括“关注对象”，否则在拓展新词汇的时候会遇到障碍。
关系图常见使用方式 #
1.搜索一个(批)节点，以及多个节点时它们之间的关系
通过POST提交筛选条件，如下的提交方式会搜索到3个点，分别是品牌类型的奥利奥、原料类型的牛奶、种类类型的饼干.
{
"objective":"search",
"extendable":false,
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
}
}这里 "extendable":false 表示仅在3个点的范围内返回，不允许返回基于这三个点产生关联的其他点。 "objective":"search" 的取值是默认值，可省略。
2.搜索一个(批)节点，以及这其外延节点和关系
可指定外延节点的类型，以及外延关系的类型
通过POST提交筛选条件
{
"objective":"search",
"extendable":true,
"type":["原料","口味"],
"isTypeExclude":true,
"edge":["子品牌", "别称", "描述"],
"isEdgeExclude":false,
"direction":"forward",
"limit":5,
"init":true,
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
}
}"objective":"search" 的取值是默认值，可省略
3.搜索一批节点，以及这些节点的Top关联节点和关系
通过POST提交筛选条件
{
"objective":"findMutualFriends",
"extendable":true,
"type":["原料","口味"],
"isTypeExclude":true,
"edge":["子品牌", "别称", "描述"],
"isEdgeExclude":false,
"direction":"forward",
"limit":5,
"init":true,
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
}
}4.根据既定的两个节点，查询最短路径，以及最短路径上的全部点和边
通过POST提交筛选条件
{
"objective":"findShortestPath",
"filters":{
"label": ["奥利奥", "牛奶"],
"type":["品牌", "原料"],
}
}5.根据既定的n个节点，查询与他们相似的节点
通过POST提交筛选条件
{
"objective":"findSimilar",
"extendable":true,
"type":["原料","口味"],
"isTypeExclude":true,
"edge":["子品牌", "别称", "描述"],
"isEdgeExclude":false,
"direction":"forward",
"limit":5,
"init":true,
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
}
}6.根据一个节点以及一种关系，寻找最契合的一批节点
通过POST提交筛选条件
{
"objective":"findMatch",
"extendable":true,
"type":"明星",
"edge":"代言人",
"direction":"bilateral",
"limit":5,
"filters":{
"label": ["奥利奥"],
"type":["品牌"],
}
}7.在一批节点之间建立关系，但区分一部分相互之间不建立关系的节点(互相之间不建立关系，但与其他节点仍然建立关系)
通过POST提交筛选条件
{
"objective":"buildRelationship",
"filters":{
"label": ["奥利奥", "牛奶", "饼干"],
"type":["品牌", "原料", "种类"],
},
"existing":{
"label": ["奥利奥", "牛奶"],
"type":["品牌", "原料"],
}
}existing 表示它们之间不需要调用此接口，但它们可以与其他的节点调用此接口。