Docs 菜单
Docs 主页
/
MongoDB Atlas
/
Atlas App Services
/
定义数据访问权限

规则表达式

Overview

规则表达式是您编写的 JSON 对象，用于通过权限控制数据访问。 每个表达式都定义了用户可以执行某些操作的条件。 例如，您可以编写表达式来控制用户是否可以读取或写入 MongoDB 文档或同步 Realm 中的数据。

App Services 计算规则表达式（通常使用文档作为输入）以得到 true 或 false 结果。

您可以定义使用硬编码值的简单静态表达式：

“静态”表达式，仅当输入文档的“id”字段与给定的硬编码 ID“aaaabbbbccccddddeeeeffff”匹配时，其计算结果才为 true
{ "id": "aaaabbbbccccddddeeeeffff" }

您还可以写入支持任意逻辑的表达式，以表达动态需求和复杂或自定义的工作流程。动态表达式可以包含反映当前上下文的变量（称为 扩展 ），并且可以使用内置运算符来转换数据。如果输入文档的 owner字段等于用户的id ，并且请求的远程IP解决可以在存储为值的允许IP地址大量中找到，则以下示例的计算结果为 true：

根据请求用户及其 IP 位置而变化的“动态”表达式
{
  "owner": "%%user.id",
  "%%request.remoteIPAddress": {
    "$in": "%%values.allowedClientIPAddresses"
  }
}

限制

使用 Device Sync 时，表达式具有特殊限制。 请参阅同步兼容的表达式。

表达式事务语法

表达式可以是布尔值（即 true或false ）或 JSON 对象。

表达式对象字段名称可以是值、扩展名或操作符。 每个字段必须包含值、扩展或嵌套表达式之一。

表达式对象具有以下格式：

{
  <Value | Expansion | Operator>: <Value | Expression>,
  ...
}

嵌入式表达式

您可以将多个表达式文档嵌入另一个表达式文档的字段中，以处理复杂的求值逻辑。 App Services以深度优先、帖子的方式对表达式进行求值：换言之，它从表达式树的底部开始，在对每个嵌入式表达式求值之后，再对每个表达式进行求值，从而返回到根级别字段。

例子

仅当作为someNumber参数提供的数字处于特定范围内时，此表达式的计算结果才为true 。

{
  "%%args.someNumber": {
     "%and": [
        { "$gt": 0 },
        { "$lte": 42 }
     ]
  }
}

多字段表达式

当表达式中有多个字段时，当且仅当表达式中的每个字段的计算结果都为 true 时，该表达式的计算结果才为true 。 换句话说，App Services 将单个表达式中的多个字段视为“AND”运算。

例子

仅当提供了url参数且body.userId参数与调用操作的用户 ID 匹配时，此第三方服务规则表达式的计算结果才为true 。

{
  "%%args.url": { "$exists": true },
  "%%args.body.userId": "%%user.id"
}

表达式求值

App Services 在计算表达式时，首先将扩展替换为运行时值，然后将扩展表达式文档的每个字段计算为布尔表达式。 如果表达式中的所有字段的计算结果均为true ，则该表达式的计算结果也为true 。空表达式 ( {} ) 的计算结果为true 。

表达式字段根据以下规则进行计算：

  • 如果扩展字段名称与其值匹配，则计算结果为true 。

  • 如果字段的值是嵌入式表达式，则其计算结果与嵌入式表达式的值相同。 请参阅嵌入式表达式。

注意

如果规则未显式使用%%args或%%root扩展，表达式字段名称默认为检查同名的参数或文档字段。 示例，表达式{ "url": "https://www.example.com" }默认情况下会在服务规则中根据%%args.url以及MongoDB规则中的%%root.url来评估其值。

扩展

扩展是表示表达式中的动态值的变量。扩展由两个百分号后跟扩展名称表示。它们是：

  • %%root，表示 MongoDB 文档中的数据。

  • %%user，表示与您的应用程序交互的用户。

  • %%request，表示传入请求。

  • %%values，表示静态值。

  • %%environment，代表应用程序的环境。

  • %%args，表示传递给一个服务操作的参数。

当应用评估表达式时，它会将表达式中的每个扩展替换为由应用的配置和评估时的上下文确定的特定值。

例子

以下示例在“apply when”表达式中使用了%%user和%%root扩展：

"applyWhen": {
   "%%user.custom_data.status": "ACTIVE",
   "%%root.owners": "%%user.id"
}

注意

某些扩展（例如%%user ）在所有表达式中都可用。 其他则仅限于特定的上下文，例如%%root与同步不兼容，并且仅在对文档进行操作的表达式中可用。

使用 Device Sync 时，扩展具有特殊限制。 请参阅同步兼容的扩展。

逻辑扩展

%%true
Type: boolean
Usable In: Any Expression

计算结果为true 。 使用它可以断言嵌套表达式的计算结果必须为true 。

%%false
Type: boolean
Usable In: Any Expression

计算结果为false 。 使用它可以断言嵌套表达式的计算结果必须为false 。

值扩展

%%values
Type: object
Usable In: Any Expression

代表应用程序的values 。 对象的每个字段都将值名称映射到相应的 JSON 值或密钥。

例子

如果值admin_ids是包含用户ID的列表，则以下表达式的计算结果为true ：

{
  "%%user.id": { "$in": "%%values.admin_ids" }
}

环境扩展

%%environment
Type: object
Usable In: Any Expression

代表当前的应用程序环境。 您可以读取环境名称 ( tag ) 并访问环境值。

对象的每个属性都将一个环境值的名称映射到其在当前环境中的值。

{
  "tag": "<Environment Name>"
  "values": {
    "<ValueName>": <Value>
  }
}

例子

以下是一个规则表达式，如果当前环境为"production"且已定义"baseUrl"环境值，则该表达式的计算结果为true ：

{
  "%%environment.tag": "production",
  "%%environment.values.baseUrl": { "%exists": true }
}

请求扩展

%%request
Type: object
Usable In: Any Expression

表示传入请求。

{
  "httpMethod": "<HTTP Method>",
  "httpReferrer": "<HTTP Referer Header>",
  "httpUserAgent": "<HTTP User Agent>",
  "rawQueryString": "<URL Query String>",
  "remoteIPAddress": "<IP Address>",
  "requestHeaders": {
    "<Header Name>": ["<Header Value>", ...]
  },
  "service": "<Service Name>",
  "action": "<Endpoint Function or Service Action Name>",
  "webhookUrl": "<HTTPS Endpoint Route>"
}

用户扩展

%%user
Type: object
Usable In: Any Expression

代表发起请求的用户。 用户对象包含帐户信息、来自身份验证提供者的元数据以及来自应用程序的自定义数据。

{
  "id": "<User Account ID>",
  "type": "<normal | server>",
  "data": {
    "<Field Name>": <Value>,
    ...
  }
  "custom_data": {
    "<Field Name>": <Value>,
    ...
  }
  "identities": [
    {
      "providerType": "<Auth Provider Name>",
      "id": "<Provider User ID"
    }
    ...
  ]
}
%%user.id
Type: string
Usable In: Any Expression

已通过身份验证的用户 ID。

%%user.type
Type: "normal" | "server"
Usable In: Any Expression

发起请求的用户类型。 对于API 密钥用户，计算结果为"server" ；对于所有其他用户，计算结果为"normal" 。

%%user.custom_data
Type: object
Usable In: Any Expression

用户的自定义数据。 确切内容因自定义用户数据配置而异。

例子

"custom_data": {
  "primaryLanguage": "English",
}
%%user.data
Type: object
Usable In: Any Expression

用户的元数据。 确切的内容将根据与用户关联的身份验证提供程序身份而有所不同。

例子

"data": {
  "name": "Joe Mango",
  "email": "joe.mango@example.com"
}
%%user.identities
Type: object[]
Usable In: Any Expression

与用户关联的所有身份验证提供者身份的列表。身份由授权提供商为用户提供的唯一标识符以及提供商的类型组成：

例子

"identities": [
  {
    "id": "5bce299457c70db9bd73b8-aajddbkuvomsvcrjjfoxs",
    "providerType": "local-userpass"
  }
]

MongoDB 文档扩展

%%this
Type: any
Usable In: MongoDB Atlas Data Sources

数据库操作结束时特定字段的值。

%%prev
Type: any
Usable In: MongoDB Atlas Data Sources

特定字段在被写入操作更改之前的值。

%%root
Type: object
Usable In: MongoDB Atlas Data Sources

数据库操作结束时存在的完整文档。

%%prevRoot
Type: object
Usable In: MongoDB Atlas Data Sources

写入操作更改之前的完整文档。

例子

true以下是 MongoDB 模式验证表达式，如果文档以前存在（即操作不是插入）或文档的status字段的值为"new" ，则该表达式的计算结果为：

{
  "%or": [
    { "%%prevRoot": { "%exists": %%true } },
    { "%%root.status": "new" }
  ]
}

服务扩展

%%args
Type: object
Usable In: Third-Party Services

包含作为参数传递给服务操作的值的文档。 您可以通过参数名称访问每个参数。

例子

以下是一条Twilio 服务规则，如果发件人的电话号码（ from参数）与特定值匹配，则该规则的计算结果为true ：

{
  "%%args.from": "+15558675309"
}
%%partition
Type: string | number | BSON.ObjectId
Usable In: Partion-based Sync

（仅限基于分区的同步。） 当前正在评估的分区的分区键值。

操作符

表达式操作符表示表达式中的动作或操作。操作符接受一个或多个参数，并求得结果值。结果的类型和值取决于您使用的操作符以及传递给它的参数。

表达式操作符由以单个百分号 ( % ) 或美元符号 ( $ ) 开头的字符串表示。 您可以在任何表达式中使用它们。

转换 EJSON 值

以下操作符允许将值在 EJSON 和 JSON 表示形式之间转换：

%stringToOid

将 12 字节或 24 字节字符串转换为 EJSON objectId对象。

例子

{
  "_id": {
    "%stringToOid": "%%user.id"
  }
}
%oidToString

将 EJSON objectId对象转换为字符串。

例子

{
  "string_id": {
    "%oidToString": "%%root._id"
  }
}
%stringToUuid

将 36 字节字符串转换为 EJSON UUID对象。

例子

{
  "_id": {
    "%stringToUuid": "%%user.id"
  }
}
%uuidToString

将 EJSON UUID对象转换为字符串。

例子

{
  "string_id": {
    "%uuidToString": "%%root._id"
  }
}

重要

无内部操作

%stringToUuid 、 %uuidToString 、 %stringToOid和%oidToString不评估JSON操作符。 您必须提供string字面量/ EJSON对象或计算结果为 1 的扩展。

调用函数

以下操作符允许您调用 App Services 应用程序中的函数：

%function

使用指定名称和参数调用函数。 计算函数返回的值。

例子

{
  "%%true": {
    "%function": {
      "name": "isEven",
      "arguments": [42]
    }
  }
}

检查存在性

使用以下操作符可以确定对象或数组中是否存在某个值：

$exists

检查其分配到的字段是否有值。所得值为表示结果的布尔值。

例子

{
  "url": { "$exists": true }
}
$in

检查指定的值数组，以查看该数组是否包含此操作符分配到的字段的值。所得值为表示结果的布尔值。

例子

{
  "url": {
    "$in": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}
$nin

检查指定的值数组，以查看该数组是否不包含此操作符分配到的字段的值。所得值为表示结果的布尔值。

例子

{
  "url": {
    "$nin": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

Compare Values

以下操作符允许您比较值，包括扩展值：

$eq

检查其分配到的字段是否等于指定的值。所得值为表示结果的布尔值。

例子

{ "score": { "$eq": 42 } }
$ne

检查其分配到的字段是否不等于指定的值。所得值为表示结果的布尔值。

例子

{ "numPosts": { "$ne": 0 } }
$gt

检查其分配到的字段是否严格大于指定的值。计算结果为代表结果的布尔值。

例子

{ "score": { "$gt": 0 } }
$gte

检查其分配到的字段是否大于或等于指定的值。计算结果为代表结果的布尔值。

例子

{ "score": { "$gte": 0 } }
$lt

检查其分配到的字段是否严格小于指定的值。所得值为表示结果的布尔值。

例子

{ "score": { "$lt": 0 } }
$lte

检查其分配到的字段是否小于或等于指定的值。所得值为表示结果的布尔值。

例子

{ "score": { "$lte": 0 } }

后退

基于角色的权限

来年

筛选器传入查询

在此页面上