接口调用说明

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 表示它们之间不需要调用此接口，但它们可以与其他的节点调用此接口。