ObjectQL 微服务 - 华炎魔方

华炎魔方 2.4+ 版本启用微服务方式调用 ObjectQL，历史版本可以参考旧版ObjectQL文档。

broker.call

使用 broker.call 方法可以调用一个服务。服务管理者寻找具有指定动作的服务（和节点）并调用该动作，调用后返回 Promise。获取更多信息。

使用： const res = await broker.call(actionName, params, opts);
参数：
- actionName: String。一个点分隔的字符串，点之前是服务名称，点后面则是动作名称。若您传入’objectql.find’，则表明你要调用objectql服务的find动作。
- params: Object 传入您需要的参数。服务可以经由 ctx.params 访问它。若未定义，则为 {}。选填。
- opt: Object 设置/覆盖某些请求参数的对象，例如meta、timeout等。选填。更多参数请参考上方链接。

增删改查

ObjectQL微服务支持以下微服务动作，实现了对数据的增删改查，这些动作会触发相应的触发器。

find

查找多条记录。该动作会触发配置的触发器函数： beforeFind、afterFind。

使用： broker.call('objectql.find', params, opt?)
参数：
- actionName: String操作名称，此处执行查找多条记录操作，值为’objectql.find’。
- params:
  - objectName: String对象的name。
  - query: 查询数据相关参数[json]，选填。
    - fields: Array 返回字段选择，例如：[‘字段名1’, ‘字段名2’]。
    - filters: SteedosQueryFilters 查询条件数组。更多细节请参考过滤条件规范。
    - sort: string 排序规则，例如：‘name desc’。
    - top: number 返回记录数。
    - skip: number 跳过记录数，通常用于分页显示。
- opt: 选填。
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。
返回值：记录数组。未找到时返回空数组[]。

const res = await this.broker.call(
'objectql.find', 
{
  objectName: 'accounts',
  query: {
    fields: ['name', 'owner'],                      // 字段选择： name, owner 
    filters: ['owner', '=', ctx.meta.user.userId],  // 过滤条件： 所有者为当前用户
    sort: 'name desc'                               // 排序规则： name字段降序
  },
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

findOne

查找单条记录。该函数会触发配置的触发器函数： beforeFind、afterFindOne 。

使用： broker.call('objectql.findOne', params, opt?)
参数：
- actionName: String 操作名称，此处执行查找单条记录操作，值为’objectql.findOne’。
- params:
  - objectName: String 对象的name。
  - id: number | string 您希望查询数据的id。
  - query: 查询数据相关参数[json]
    - fields: Array 字段名数组，选填。例如：[‘字段名1’, ‘字段名2’]。
- opt:
  - meta:
    - user: SteedosUser 当前用户信息，此可以查询当前用户的权限。选填。
返回值：单条记录[json]。

const res = await this.broker.call(
'objectql.findOne', 
{
  objectName: 'accounts',
  id: 'CChCmkiHrNeTM9jgA',      // 查询字段的id，具有唯一性
  query: {
    fields: ['name', 'owner'],  // 字段选择： name, owner 
  }    
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

insert

添加单条记录。该函数会触发配置的触发器函数： beforeInsert 、afterInsert 。添加 “任务” 等特殊记录后会发送通知给指定人员。

使用： broker.call('objectql.insert', params, opt?)
参数：
- actionName: String操作名称，此处执行插入操作，故值为’objectql.insert’。
- params:
  - objectName: String对象的name。
  - doc: Dictionary<any> 您希望插入的数据，必须包含该对象的必填项。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值： 插入成功后的数据。


const res = await this.broker.call(
'objectql.insert', 
{
  objectName: 'accounts', 
  doc: {
    // account 对象下面 name 为必填项，不同对象的必填项可能有差异
    name: '这里是插入的数据的名称'
  }
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  需要在memetata中传入 user 属性。:{
    user: ctx.me ta.user
  }
}
);

accounts 的name字段为必填项，不同对象间存在差异。该对象的个别字段见下表（包含必填字段和系统字段）。

基础属性	属性含义	是否必填	说明
name	记录名称	✔	`accounts`添加记录为必填，不同对象必填项可能有差异
id	id	✖	若不传入id，则系统自动维护
space	工作区	✖	系统自动维护
owner	所有者	✖	系统自动维护
created_by	创建人员	✖	系统自动维护
modified_by	修改人员	✖	系统自动维护
created	创建时间	✖	系统自动维护
modified	修改时间	✖	系统自动维护

delete

删除单条记录。该函数会触发配置的触发器函数： beforeDelete、afterDelete 。

使用： broker.call('objectql.delete', params, opt?)
参数：
- actionName: String操作名称，此处执行删除操作，值为’objectql.delete’。
- params:
  - id: number | string 您希望变更数据的id。
  - objectName: String对象的name。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：成功：1，失败：抛出报错信息。

const res = await this.broker.call(
'objectql.delete', 
{
  objectName: 'accounts',
  id: "Xgf3NxXJWAXJff9FQ" // 删除字段的id，具有唯一性
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

update

更新单条记录。该函数会触发配置的触发器函数： beforeUpdate 、afterUpdate 。更新 “任务” 等特殊记录后会发送通知给指定人员。

使用： broker.call('objectql.update', params, opt?)
参数：
- actionName: String操作名称，此处执行更新操作，值为’objectql.update’。
- params:
  - id: number | string 您希望变更数据的id。
  - objectName: String对象的name。
  - doc: Dictionary<any> 您希望更新的数据。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：更新成功后的数据。

const res = await this.broker.call(
'objectql.update', 
{
  objectName: 'accounts',
  doc: {
    name: '更新的数据后的名称'
  },
  id: "CChCmkiHrNeTM9jgA"
},
// 如果查询需要带上当前用户的权限，需要在meta传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

aggregate

查找聚合记录。该动作会触发配置的触发器函数： beforeAggregate、afterAggregate 。

聚合：聚合操作处理数据记录并返回计算结果。聚合操作将来自多个文档的值组合在一起，并且可以对分组的数据执行各种操作以返回单个结果。

使用： broker.call('objectql.aggregate', params, opt?)
参数：
- actionName: String操作名称，此处执行聚合操作，值为’objectql.aggregate’。
- params:
  - objectName: String 对象的name。
  - query: 查询数据相关参数[json]。
    - filters: Array查询条件数组，选填。请参考过滤条件规范。
  - externalPipeline: ArrayMongodb ggregation Pipeline。mongodb聚合文档。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：聚合记录数组。

const res = await this.broker.call(
'objectql.aggregate', 
{
  objectName: 'accounts',
  query: {
    filters: ['owner', '=', ctx.meta.user.userId],  // 过滤条件： 所有者为当前用户
  },
  externalPipeline: [{ $count: 'users_count'}]      // 查询经过query后数据的数量，将数量赋值给users_count
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

direct

ObjectQL微服务支持以下带 direct 前缀的微服务动作，实现了对数据的增删改查，这些动作不会触发相应的触发器。

directFind

查找多条记录。此动作不会执行触发器。

使用： broker.call('objectql.directFind', params, opt?)
参数：
- actionName: String操作名称，此处执行直接查找操作，值为’objectql.directFind’。
- params:
  - objectName: String对象的name。
  - query: 查询数据相关参数[json]，选填。
    - fields: Array 返回字段选择，选填。例如：[‘字段名1’, ‘字段名2’]。
    - filters: SteedosQueryFilters 查询条件数组，选填。请参考过滤条件规范。
    - sort: string 排序规则，选填。例如：‘name desc’。
    - top: number 返回记录数，选填。
    - skip: number 跳过记录数，通常用于分页显示，选填。
- opt:
  - meta:
    - user: SteedosUser 当前用户信息，此可以查询当前用户的权限。选填。
返回值：记录数组。未找到时返回空数组[]。

const res = await this.broker.call(
'objectql.directFind', 
{
  objectName: 'accounts',
  query: {
    fields: ['name', 'owner'],                      // 字段选择： name, owner 
    filters: ['owner', '=', ctx.meta.user.userId],  // 过滤条件： 所有者为当前用户
    sort: 'name desc'                               // 排序规则： name字段降序
  }
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

directInsert

添加单条记录。此动作不会执行触发器。

使用： broker.call('objectql.directInsert', params, opt?)
参数：
- actionName: String操作名称，此处执行直接插入操作，值为’objectql.directInsert’。
- params:
  - objectName: String对象的name。
  - doc: Dictionary<any> 您希望插入的数据，必须包含该对象的必填项。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值： 插入成功后的数据。

const res = await this.broker.call(
'objectql.directInsert', 
{
  objectName: 'accounts',
  doc: {
    // account 对象下面 name 为必填项，不同对象的必填项可能有差异
    name: '插入的数据的名称（直接插入）'
  }
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

directDelete

更新单条记录。此动作不会执行触发器。

使用： broker.call('objectql.directDelete', params, opt?)
参数：
- actionName: String操作名称，此处执行直接删除操作，值为’objectql.directDelete’。
- params:
  - id: number | string 您希望变更数据的id。
  - objectName: String对象的name。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：成功：1，失败：抛出报错信息。

const res = await this.broker.call(
'objectql.directDelete', 
{
  objectName: 'accounts',
  id: "Xgf3NxXJWAXJff9FQ" // 删除字段的id，具有唯一性
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

directUpdate

更新单条记录。此动作不会执行触发器。

使用： broker.call('objectql.directUpdate', params, opt?)
参数：
- actionName: String操作名称，此处执行直接更新操作，值为’objectql.directUpdate’。
- params:
  - id: number | string 您希望变更数据的id。
  - objectName: String对象的name。
  - doc: Dictionary<any> 您希望更新的数据。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：更新成功后的数据。

const res = await this.broker.call(
'objectql.directUpdate', 
{
  objectName: 'accounts',
  doc: {
    name: '插入的数据的名称（directUpdate）'
  },
  id: "9RKrpkvm8Q9Bw7mYc"
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

directAggregate

查找聚合记录。此动作不会执行触发器。

聚合：聚合操作处理数据记录并返回计算结果。聚合操作将来自多个文档的值组合在一起，并且可以对分组的数据执行各种操作以返回单个结果。

使用： broker.call('objectql.directAggregate', params, opt?)
参数：
- actionName: String操作名称，此处执行聚合操作，值为’objectql.directAggregate’。
- params:
  - objectName: String 对象的name。
  - query: 查询数据相关参数[json]。
    - filters: Array查询条件数组，选填。请参考过滤条件规范。
  - externalPipeline: ArrayMongodb ggregation Pipeline。mongodb聚合文档。
- opt:
  - meta:
    - user: SteedosUser当前用户信息，此可以查询当前用户的权限。选填。
返回值：聚合记录数组。

const res = await this.broker.call(
'objectql.directAggregate', 
{
  objectName: 'accounts',
  query: {
    filters: ['owner', '=', ctx.meta.user.userId],  // 过滤条件： 所有者为当前用户
  },
  externalPipeline: [{ $count: 'users_count'}]
},
// 如果查询需要带上当前用户的权限，需要传入 user 属性。
{
  meta:{
    user: ctx.meta.user
  }
}
);

示例

以下示例在微服务中定义了一个名为 findAccounts 动作，在该动作中调用ObjectQL微服务，实现数据查询。

module.exports = {
  name: "example-service",      // 当前服务名称

  actions: {
    findAccounts: {
      // 使用微服务方式定义 API 接口。
      // 访问地址： GET /service/api/example-service/objectql/find
      rest: { method: 'GET', path: '/objectql/find' },
      async handler(ctx) {
        return await this.broker.call(
        'objectql.find',                                    // actionName
        {
          objectName: 'accounts',
          query: {
            fields: ['name', 'owner'],                      // 字段选择： name, owner 
            filters: ['owner', '=', ctx.meta.user.userId],  // 过滤条件： 所有者为当前用户
            sort: 'name desc'                               // 排序规则： name字段降序
          }
        },
        // 如果查询需要带上当前用户的权限，需要传入 user 属性。
        {
          meta:{
            user: ctx.meta.user
          }
        }
        );
      }
    }
  }
}

​broker.call

​增删改查

​find

​findOne

​insert

​delete

​update

​aggregate

​direct

​directFind

​directInsert

​directDelete

​directUpdate

​directAggregate

​示例

本页内容