GraphQL API

GraphQL 控制台

可以在浏览器端访问 GraphQL 控制台，查询和操作系统中的数据。访问网址为: ${服务器地址}/graphql

GraphQL接口内置权限控制，执行查询前必须先登录系统，当前查询的访问权限为当前登录的账户。

接口验证

调用接口前，首先需要先进行接口的身份验证，请参阅 接口验证。

查询数据

可以在使用GraphQL查询数据时设置要查询的对象、字段、翻页、排序及过滤条件等，所有查询都基于当前登录用户被授权查看的数据范围。

查询对象和字段

输入对象名称和字段名称，可以查询对象中的所有记录。例如以下查询可以查询分部信息。

{
  company{
    _id,
    name,
    admins
  } 
}

查询结果

{
  "data": {
    "company": [
      {
        "_id": "CqY8Dy4MCFgXCbMjT",
        "name": "华炎软件",
        "admins": [
          "60f6a630d5d0f30031bba318"
        ]
      },
      {
        "_id": "EX4Ro64TjLaMnves8",
        "name": "华炎网络",
        "admins": [
          "60f6a630d5d0f30031bba318"
        ]
      }
    ]
  }
}

查询参数：翻页

您可以定义一个skip要跳过多少条记录，以及一个查询要返回多少条记录top。

如下查询将仅返回第二条记录：

query{
  space_users(top:1, skip:1){
    name,
    mobile
  }
}

查询参数：排序

您可以定义如何用sort对结果进行排序。

关键字desc表示降序，关键字asc表示升序。

示例：按字段name降序排序

query{
  space_users(sort:"name asc"){
    name,
    mobile
  }
}

查询参数：过滤

您可以添加 filters 筛选特定记录。示例：查询分部名称包含 ‘华炎’ 的记录。过滤条件详情请见下方 ”查询过滤条件详解“。

query{
  company(filters: ["name","contains","华炎"]){
    _id,
    name,
  } 
}

扩展查询相关表

对于 lookup 和 master/detail 类型字段，使用 ${field_api_name}__expand 语法，可以扩展查询相关表中的数据。如果相关表字段是多选类型，返回的也是数组数据。

{
  company{
    _id,
    name,
    admins__expand{
      name
      mobile
    }
  } 
}

返回结果

{
  "data": {
    "company": [
      {
        "_id": "CqY8Dy4MCFgXCbMjT",
        "name": "华炎软件",
        "admins__expand": [
          {
            "_id": "60f6a630d5d0f30031bba318",
            "name": "管理员",
            "mobile": "18600000000"
          }
        ]
      }
    ]
  }
}

返回格式化数据

对于 boolean , select , date , datetime , lookup类型字段，使用 _display{ field_api_name } 语法，可以格式化查询到的数据。

其中 0 、null 、false 值格式化后为空字符串。

query{
  space_users(top:1, skip:1){
    name,
    # boolean null
    email_verified
    # boolean false
    mobile_verified
    # boolean true
    is_supplier
    # lookup  单选
    organization
    # lookup  多选
    organizations_parents
    # select
    locale
    # number
    sort_no
    # date
    last_logon
    # datetime
	created
    
    _display{
      email_verified
      mobile_verified
      is_supplier
      organization
      organizations_parents
      locale
      sort_no
      last_logon
      created
    },
    _ui{
      organization
      organizations_parents
    }
  }
}

返回结果

{
  "data": {
    "space_users": [
      {
        "name": "王小明",
        "email_verified": null,
        "mobile_verified": false,
        "is_supplier": null,
        "organization": "n7Yv6i5fg3acnmm5d",
        "organizations_parents": [
          "n7Yv6i5fg3acnmm5d",
          "XypyNbzGCJbHMNyWv"
        ],
        "locale": "zh-cn",
        "sort_no": null,
        "last_logon": null,
        "created": "2022-08-09T04:08:28.313Z",
        "_display": {
          "email_verified": "",
          "mobile_verified": "",
          "is_supplier": "",
          "organization": "上海分公司",
          "organizations_parents": "上海分公司,爱多邦",
          "locale": "简体中文",
          "sort_no": "",
          "last_logon": "",
          "created": "2022-08-09 12:08"
        },
        "_ui": {
          "organization": {
            "objectName": "organizations",
            "value": "n7Yv6i5fg3acnmm5d",
            "label": "上海分公司"
          },
          "organizations_parents": [
            {
              "objectName": "organizations",
              "value": "n7Yv6i5fg3acnmm5d",
              "label": "上海分公司"
            },
            {
              "objectName": "organizations",
              "value": "XypyNbzGCJbHMNyWv",
              "label": "爱多邦"
            }
          ]
        }
      }
    ]
  }
}

查询相关子表

当其他表与当前表关联时，可以同时查询相关的子表信息。

查询语法

_related_${object_api_name}_${field_api_name}

例如以下查询可以查询当前分部中的人员清单，也就是人员对象（space_users）中，company_ids 字段与 company 绑定的记录信息。

{
  company{
    _id,
    name,
    admins__expand{
      _id
      name
      mobile
    }
    space_users: _related_space_users_company_ids(filters: ["job_number","=","10"]) {
      name
      mobile
    }
  } 
}

注意：为了提升返回结果的可读性，这里给返回结果起了一个别名： space_users

返回结果

{
  "data": {
    "company": [
      {
        "_id": "CqY8Dy4MCFgXCbMjT",
        "name": "华炎软件",
        "admins__expand": [
          {
            "_id": "60f6a630d5d0f30031bba318",
            "name": "管理员",
            "mobile": "18600000000"
          }
        ],
        "space_users": [
          {
            "name": "小明",
            "mobile": "18600000000"
          }
        ]
      }
    ]
  }
}

操作数据

可以使用GraphQL对数据执行增、删、改操作，所有数据处理操作都基于当前登录用户被授权的数据范围。

新增数据

当调用 GraphQL API 新增数据时，系统会首先验证当前用户是否有对应的新增权限。

新增单条数据

使用 mutation.{object_api_name}__insert 语法，传入 doc 参数值。

mutation {
  tasks__insert(doc:{name:"Task One", assignees: []}) {
    name
    _id
  }
}

其中，tasks 代表要插入记录的对象名称，{name:"Task One", assignees: []} 代表要插入的JSON数据。

关键字 __insert 表示通过 GraphQL API 在系统中插入一条记录。

结果如下：

{
  "data": {
    "tasks__insert": {
      "name": "Task One",
      "_id": "5cb98489d09a343e14daae95"
    }
  }
}

修改数据

当调用 GraphQL API 修改数据时，系统会首先验证当前用户是否有对应的修改权限。

修改单条数据

使用 mutation.{object_api_name}__update 语法，传入 id 和 doc 参数值。

mutation {
  tasks__update(id:"5cb98489d09a343e14daae95", doc:{name:"Task Important"}) {
    name
    _id
  }
}

其中，tasks代表要修改记录的对象名称，id 的值 5cb98489d09a343e14daae95 代表要修改的记录的 _id，{name:"Task Important"} 代表要更新的JSON数据。

关键字__update表示通过 GraphQL API 在系统中修改一条记录。

结果如下：

{
  "data": {
    "tasks__update": {
      "name": "Task Important",
      "_id": "5cb98489d09a343e14daae95"
    }
  }
}

删除数据

当调用 GraphQL API 删除数据时，系统会首先验证当前用户是否有对应的删除权限。

删除单条数据

使用 mutation.{object_api_name}__delete 语法，传入 id 参数值。

mutation {
  tasks__delete(id:"5cb98489d09a343e14daae95")
}

其中，tasks 代表要删除记录的对象名，id 的值 5cb98489d09a343e14daae95 代表要删除的记录的_id

关键字__delete表示通过 GraphQL API 在系统中删除一条记录。

结果如下：

{
  "data": {
    "tasks__delete": 1
  }
}

参考：GraphQL