API 实战流程

本文档介绍如何通过 API 完成角色权限配置和用户创建的完整流程，适用于需要自动化批量创建用户和配置权限的场景。

场景描述

假设当前的空间 ID 为 default，有一张销售表，sid 为 dwd_sales_detail_default。另外有一张门店表，sid 为 dim_shops_default，ID 字段的字段名为「店铺ID」。

现在需要添加一个「店长」角色，让每位店长只能查看自己店铺的数据。

API 通用配置

获取 API Key

管理员账号 → 右上角⚙️按钮 → API密钥，生成一个密钥。

必需的请求头

所有 API 请求都需要包含以下请求头：

Authorization: Bearer <YOUR_TOKEN>
X-SPACES: default
Content-Type: application/json

环境变量

以下命令假设服务部署在 http://localhost:13000，实际使用时请替换为您的域名：

export BASE_URL="http://localhost:13000"

创建或更新角色并配置权限

使用 yiask_roles:updateOrCreateWithPermissions API，一次调用即可完成角色创建、权限配置和用户绑定：

curl '$BASE_URL/api/yiask_roles:updateOrCreateWithPermissions' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'X-SPACES: default' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "name": "storeOwner",
    "title": "店长",
    "permissions": {
      "dim_shops_default": {
        "rowPermissions": {
          "$and": [
            {
              "店铺ID": {
                "$eq": "{{$user.yiask_dim_shops_default}}"
              }
            }
          ]
        },
        "columnPermissions": {
          "view": ["店铺ID", "店铺名称"]
        }
      },
      "dwd_sales_detail_default": {
        "rowPermissions": {
          "$and": [
            {
              "店铺ID": {
                "$eq": "{{$user.yiask_dim_shops_default}}"
              }
            }
          ]
        },
        "columnPermissions": {
          "view": null
        }
      }
    },
    "users": [
      {
        "username": "zhangsan",
        "nickname": "张三",
        "email": "zhangsan@example.com",
        "phone": "13800138001",
        "password": "Password123!",
        "yiask_dim_shops_default": "1"
      },
      {
        "username": "lisi",
        "nickname": "李四",
        "email": "lisi@example.com",
        "phone": "13800138002",
        "password": "Password123!",
        "yiask_dim_shops_default": "2"
      }
    ]
  }'

参数说明

必填参数

参数	类型	说明
`name`	`string`	角色名称（唯一标识）
`permissions`	`object`	权限配置对象

可选参数

参数	类型	默认值	说明
`title`	`string`	同 `name`	角色显示名称
`users`	`array`	`[]`	用户列表（同时创建/更新用户）

permissions 格式

{
  permissions: {
    "[schemaSid]": {
      // 行权限：数据过滤条件
      rowPermissions: {
        "$and": [
          {
            "字段名": { "操作符": "值" }
          }
        ]
      },
      // 列权限：每个 action 可访问的字段列表
      columnPermissions: {
        "[actionName]": ["字段1", "字段2"],  // 只能访问指定字段
        "[actionName]": null                   // null 表示允许访问所有字段
      }
    }
  }
}

users 格式

{
  users: [
    {
      username: "string",      // 必填，用户名（唯一标识）
      nickname: "string",      // 可选，显示名称
      email: "string",         // 可选，邮箱
      phone: "string",         // 可选，手机号
      password: "string",      // 可选，密码（不传则留空，支持 OAuth2 等其他登录方式）
      "yiask_[sid]": "值"      // 可选，用户在实体上的权限值
    }
  ]
}

字段名自动转换

建议使用属性的名称（如 店铺ID），同时也支持属性的 ID（如 ID、name），输入属性的 ID 会自动转换为属性名称。

{
  "permissions": {
    "dim_shops_default": {
      "rowPermissions": {
        "$and": [
          {
            "ID": { "$eq": "..." }  // 属性 ID → 自动转换为 "店铺ID"
          }
        ]
      },
      "columnPermissions": {
        "view": ["ID", "name"]  // → ["店铺ID", "店铺名称"]
      }
    }
  }
}

说明：以上示例中，假设「店铺ID」的属性 ID 为 ID，「店铺名称」的属性 ID 为 name。

转换规则：

如果字段是某个 property 的 name（如 店铺ID），直接保留
如果字段是某个 property 的 id（如 ID），自动转换为 name
如果字段既不是 name 也不是 id（如 $and、$eq 等操作符），保留原样

数据范围语法说明

数据范围（rowPermissions）使用类似 MongoDB 的查询语法来定义数据过滤条件。

逻辑操作符

操作符	说明	示例
`$and`	逻辑与，所有条件都必须满足	见下方示例
`$or`	逻辑或，满足任一条件即可	见下方示例

$and 示例（同时满足多个条件）：

{
  "rowPermissions": {
    "$and": [
      { "status": { "$eq": "active" } },
      { "age": { "$gte": 18 } }
    ]
  }
}

$or 示例（满足任一条件即可）：

{
  "rowPermissions": {
    "$or": [
      { "status": { "$eq": "active" } },
      { "role": { "$eq": "admin" } }
    ]
  }
}

比较操作符

操作符	说明	示例
`$eq`	等于	`{ "status": { "$eq": "active" } }`
`$ne`	不等于	`{ "status": { "$ne": "deleted" } }`
`$gt`	大于	`{ "age": { "$gt": 18 } }`
`$gte`	大于等于	`{ "age": { "$gte": 18 } }`
`$lt`	小于	`{ "age": { "$lt": 65 } }`
`$lte`	小于等于	`{ "age": { "$lte": 65 } }`
`$in`	包含在数组中	`{ "status": { "$in": ["active", "pending"] } }`
`$nin`	不包含在数组中	`{ "status": { "$nin": ["deleted", "banned"] } }`

字符串操作符

操作符	说明	示例
`$includes`	包含指定字符串（模糊匹配）	`{ "name": { "$includes": "张三" } }`
`$notIncludes`	不包含指定字符串	`{ "name": { "$notIncludes": "测试" } }`
`$startsWith`	以指定字符串开头	`{ "username": { "$startsWith": "user_" } }`
`$notStartsWith`	不以指定字符串开头	`{ "username": { "$notStartsWith": "admin_" } }`
`$endWith`	以指定字符串结尾	`{ "email": { "$endWith": "@example.com" } }`
`$notEndWith`	不以指定字符串结尾	`{ "email": { "$notEndWith": "@spam.com" } }`

数组操作符

操作符	说明	示例
`$anyOf`	数组包含任一指定元素	`{ "tags": { "$anyOf": ["urgent", "important"] } }`
`$noneOf`	数组不包含任何指定元素	`{ "tags": { "$noneOf": ["spam", "test"] } }`
`$match`	数组完全匹配	`{ "permissions": { "$match": ["read", "write"] } }`
`$notMatch`	数组不完全匹配	`{ "permissions": { "$notMatch": ["admin"] } }`
`$arrayEmpty`	数组为空	`{ "tags": { "$arrayEmpty": true } }`
`$arrayNotEmpty`	数组不为空	`{ "tags": { "$arrayNotEmpty": true } }`

日期操作符

操作符	说明	示例
`$dateOn`	日期等于某天	`{ "createdAt": { "$dateOn": "2024-01-01" } }`
`$dateNotOn`	日期不等于某天	`{ "createdAt": { "$dateNotOn": "2024-01-01" } }`
`$dateBefore`	日期在指定日期之前	`{ "createdAt": { "$dateBefore": "2024-01-01" } }`
`$dateNotBefore`	日期不在指定日期之前（≥）	`{ "createdAt": { "$dateNotBefore": "2024-01-01" } }`
`$dateAfter`	日期在指定日期之后	`{ "createdAt": { "$dateAfter": "2024-01-01" } }`
`$dateNotAfter`	日期不在指定日期之后（≤）	`{ "createdAt": { "$dateNotAfter": "2024-01-01" } }`
`$dateBetween`	日期在两个日期之间	`{ "createdAt": { "$dateBetween": ["2024-01-01", "2024-12-31"] } }`

空值/布尔操作符

操作符	说明	示例
`$empty`	为空（null、undefined、空字符串或空数组）	`{ "phone": { "$empty": true } }`
`$notEmpty`	不为空	`{ "phone": { "$notEmpty": true } }`
`$isFalsy`	为假值	`{ "deleted": { "$isFalsy": true } }`
`$isTruly`	为真值	`{ "verified": { "$isTruly": true } }`

用户变量引用

在数据范围中可以引用用户的实体权限字段：

{
  "rowPermissions": {
    "$and": [
      {
        "店铺ID": {
          "$eq": "{{$user.yiask_dim_shops_default}}"
        }
      }
    ]
  }
}

说明：{{$user.yiask_dim_shops_default}} 表示用户在门店表中的关联值。

其他 API

获取角色权限

curl '$BASE_URL/api/yiask_roles:getPermissions' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'X-SPACES: default' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "roleName": "storeOwner"
  }'

返回结果：

{
  "roleName": "storeOwner",
  "permissions": {
    "dim_shops_default": {
      "rowPermissions": {
        "$and": [
          {
            "店铺ID": {
              "$eq": "{{$user.yiask_dim_shops_default}}"
            }
          }
        ]
      },
      "columnPermissions": {
        "view": ["店铺ID", "店铺名称"]
      }
    }
  }
}

完整示例

创建「店长」角色，配置两个表的权限，同时创建两位店长用户：

curl '$BASE_URL/api/yiask_roles:updateOrCreateWithPermissions' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'X-SPACES: default' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "name": "storeOwner",
    "title": "店长",
    "permissions": {
      "dim_shops_default": {
        "rowPermissions": {
          "$and": [
            {
              "店铺ID": {
                "$eq": "{{$user.yiask_dim_shops_default}}"
              }
            }
          ]
        },
        "columnPermissions": {
          "view": ["店铺ID", "店铺名称"]
        }
      },
      "dwd_sales_detail_default": {
        "rowPermissions": {
          "$and": [
            {
              "店铺ID": {
                "$eq": "{{$user.yiask_dim_shops_default}}"
              }
            }
          ]
        },
        "columnPermissions": {
          "view": null
        }
      }
    },
    "users": [
      {
        "username": "zhangsan",
        "nickname": "张三",
        "email": "zhangsan@example.com",
        "phone": "13800138001",
        "password": "Password123!",
        "yiask_dim_shops_default": "1"
      },
      {
        "username": "lisi",
        "nickname": "李四",
        "email": "lisi@example.com",
        "phone": "13800138002",
        "password": "Password123!",
        "yiask_dim_shops_default": "2"
      }
    ]
  }'

返回结果：

{
  "name": "storeOwner",
  "title": "店长",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "id": 123456789,
  "permissions": {
    "dim_shops_default": {
      "rowPermissions": {
        "$and": [
          {
            "店铺ID": {
              "$eq": "{{$user.yiask_dim_shops_default}}"
            }
          }
        ]
      },
      "columnPermissions": {
        "view": ["店铺ID", "店铺名称"]
      }
    },
    "dwd_sales_detail_default": {
      "rowPermissions": {
        "$and": [
          {
            "店铺ID": {
              "$eq": "{{$user.yiask_dim_shops_default}}"
            }
          }
        ]
      },
      "columnPermissions": {
        "view": null
      }
    }
  }
}

执行结果

调用成功后：

创建了「店长」角色
自动创建了数据范围
自动配置了表的权限范围
创建了张三、李两位用户，并绑定到「店长」角色
设置了用户在门店表中的权限值（yiask_dim_shops_default）

#API 实战流程

#场景描述

#API 通用配置

#获取 API Key

#必需的请求头

#环境变量

#创建或更新角色并配置权限

#参数说明

#必填参数

#可选参数

#permissions 格式

#users 格式

#字段名自动转换

#数据范围语法说明

#逻辑操作符

#比较操作符

#字符串操作符

#数组操作符

#日期操作符

#空值/布尔操作符

#用户变量引用

#其他 API

#获取角色权限

#完整示例

#执行结果