AcgClient（ACG 客户端开发包）

目录

• 1. 安装
• 2. 使用示例
• 3. 接口约定
• 4. 接口列表
  • 4.1. 用户（User）
    • 4.1.1. 登录
    • 4.1.2. 注销登录
  • 4.2. 文档（Document）
    • 4.2.1. 获取文档
    • 4.2.2. 查找文档（多个）
    • 4.2.3. 创建文档
    • 4.2.4. 删除文档
    • 4.2.5. 文档打补丁
    • 4.2.6. 批量创建文档
  • 4.3. 身份（Profile）
    • 4.3.1. 获取身份
  • 4.4. 文件（File）
    • 4.4.1. 上传文件
    • 4.4.2. 下载文件
  • 4.5. 扩展程序（Extension）
    • 4.5.1. 获取微信 JSAPI 参数

1. 安装

cnpm install acg-client --save

2. 使用示例

const AcgClient = require("acg-client");
(async function () {
  // 创建实例
  var client = new AcgClient({
    // 接入地址
    endpoint: "http://localhost:3000",
    // 身份令牌
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
  });
  // 获取指定域 指定集合 的指定文档
  var rst = await client.document.get(".root", ".users", "administrator");
  console.log(rst);
})();

3. 接口约定

所有接口结果均返回对象格式，必定包含 success、code 和 message 属性，分别表示“调用成功与否”、“结果编码”以及“结果消息”。不同接口会约定其他的属性请参考具体接口说明。以下是返回结果示例：

// 成功
{
    "success": true,
    "code": "200",
    "message": "成功",
    "document": {
        "id": "1000001",
        "title": "文档001"
    }
}
// 失败
{
    "success": false,
    "code": "404",
    "message": "失败"
}

4. 接口列表

4.1. 用户（User）

4.1.1. 登录

client.user.login( userId, password, options )

参数说明：

• userId： <string> 用户 ID
• password： <string> 密码
• options: <object> 附加选项

结果属性说明：

• token： <string> 令牌。

4.1.2. 注销登录

client.user.logout( options )

参数说明：

• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

4.2. 文档（Document）

4.2.1. 获取文档

client.document.get( domainId, collectionId, documentId, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• documentId： <string> 文档 ID
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

结果属性说明：

• document： <object> 文档内容，成功时返回。

4.2.2. 查找文档（多个）

client.document.find( domainId, collectionId, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• options: <object> 选项
  • options.token <string> 本次请求所使用的特定 Token
  • options.query <object> 基于 JSON 的完整查询DSL
  • options.size <number> 第一个搜索结果的偏移量。默认为“0”。
  • options.from <number> 返回搜索结果的文档数量。默认为“10”。
  • options.source <string|object> 指定搜索结果包含或排除的文档字段。
    • 当 source 字段是对象时，由 source.includes 和 source.excludes 共同产生作用。
      • source.includes：指定搜索结果包含的文档字段。每个元素是需要包含的字段名；允许使用通配符“”，例如“obj.”或“_.xxx”。
      • source.excludes：指定搜索结果排除的文档字段。每个元素是需要排除的字段名；允许使用通配符“”，例如“obj.”或“_.xxx”。
    • 当 source 字段是数组时，其作用同 source.includes。
  • options.sort <array|any> 排序设置。更多的排序方法请点击查阅。
    • options.sort[].{字段名} <object> 指定字段的排序设置。
      • options.sort[].{字段名}.order <string> 排序方式。asc:升序排列 desc:降序排序。

结果属性说明：

• total： <number> 文档总数，成功时返回。
• offset： <number> 文档偏移量，成功时返回。
• documents： <object> 搜索返回的文档清单，成功时返回。

4.2.3. 创建文档

client.document.create( domainId, collectionId, doc, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• doc： <object> 文档内容。不指定 ID 时则自动生成；必须指定模板 ID：_meta.tId
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

结果属性说明：

• document： <object> 文档内容，成功时返回。

4.2.4. 删除文档

client.document.delete( domainId, collectionId, documentId, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• documentId： <string> 文档 ID
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

4.2.5. 文档打补丁

client.document.patch( domainId, collectionId, documentId, patchs, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• documentId： <string> 文档 ID
• patchs: <array> 基于 JsonPatch 的补丁内容。
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

结果属性说明：

• document： <object> 文档内容，成功时返回。

4.2.6. 批量创建文档

client.document.bulkCreate( domainId, collectionId, items, options )

参数说明：

• domainId： <string> 域 ID
• collectionId： <string> 集合 ID
• items： <array> 文档清单，对象数组。
• items[].doc： <object> 文档内容。
• items[].doc.id： <string> 文档ID，不指定 ID 时则自动生成。
• items[].doc._meta.tId： <string> 必须指定模板 ID：_meta.tId。
• items[].doc.<fields>： <不限> 文档字段，按需传入。
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token
  • options.replace_if_exists <boolean> 此更新类型为完整替换更新，默认为false，传入true时，若文档已存在则传入的items[].doc以替换方式更新文档。

结果属性说明：

• errors： <boolean> 是否有执行失败的项目。
• items： <array> 执行结果清单，对象数组。
• items[].id： <string> 文档ID。
• items[].status： <number> 执行结果状态码，2开头表示成功。
• items[].result： <string> 执行结果，replaced:已替换，updated:已更新，created:已创建，成功时返回。
• items[].error： <object> 错误信息，失败时返回。
• items[].error.type： <string> 错误类型编码。
• items[].error.reason： <string> 错误原因描述。

4.3. 身份（Profile）

4.3.1. 获取身份

client.profile.get( domainId, profileId, options )

参数说明：

• domainId： <string> 域 ID
• profileId： <string> 身份 ID
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

结果属性说明：

• profile： <object> 身份内容，成功时返回。

4.4. 文件（File）

4.4.1. 上传文件

client.file.upload( domainId, file, options )

参数说明：

• domainId： <string> 域 ID
• file <string> 文件路径（后续会支持文件流等格式）
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token
  • options.doc <object|string> 文档内容，用于覆盖文件文档

结果属性说明：

• file： <object> 文件信息，成功时返回。

4.4.2. 下载文件

client.file.download( domainId, fileId, options )

参数说明：

• domainId： <string> 域 ID
• fileId <string> 文件 ID
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token
  • options.filepath <string> 指定的文件路径，文件下载后将保持到此路径（如 C:/xxx/xxx.txt）

结果属性说明：

• filepath： <object> 文件路径（如 C:/xxx/xxx.txt）

4.5. 扩展程序（Extension）

4.5.1. 获取微信 JSAPI 参数

client.extension.getWechatJsapiParams( domainId, extensionId, clientUrl, options )

参数说明：

• domainId： <string> 域 ID
• extensionId <string> 扩展程序 ID
• clientUrl <string> 客户端页面地址。不包含#及其后面部分。
• options: <object> 附加选项
  • options.token <string> 本次请求所使用的特定 Token

结果属性说明：

• params： <object> JSAPI 参数信息，成功时返回。