Docs 菜单
Docs 主页
/ /
Atlas App Services

MongoDB 数据源配置文件

在此页面上

  • 服务配置
  • MongoDB 集群
  • 联合数据库实例
  • 数据库和collection
  • collection模式
  • 关系
  • 默认规则
  • collection规则
  • 规则配置
  • 角色
  • 筛选器

注意

本页介绍一种旧版配置文件格式。仅当使用已弃用的 realm-cli时才应使用此信息。

使用 App Services CLI 拉取或从用户界面导出的任何配置文件都使用最新配置版本。 有关当前配置文件格式的详细信息,请参阅应用程序配置。

app/
└── data_sources/
└── <service name>/
├── config.json
└── <database>/
└── <collection>/
├── schema.json
├── relationships.json
└── rules.json
config.json
{
"name": "<Service Name>",
"type": "mongodb-atlas",
"config": {
"clusterName": "<Atlas Cluster Name>",
"readPreference": "<Read Preference>",
"wireProtocolEnabled": <Boolean>
}
}
字段
说明
name
String

必需。默认: mongodb-atlas

用于引用此 Atlas App Services App 中的集群的服务名称。名称最长可以有 64 个字符,并且只能包含 ASCII 字母、数字、下划线和连字符。

type
String
必需。 对于 MongoDB Atlas 集群,此值始终为"mongodb-atlas"
config.clusterName
String
必需。 Atlas 中集群的名称。
config.readPreference
String

通过服务发送的查询的读取偏好(read preference)模式。

模式
说明
主节点
Atlas App Services将所有读取操作路由到当前副本集主节点。 这是默认的读取偏好模式。
Atlas App Services将所有读取操作路由到当前副本集主节点(如果可用)。 如果主 节点 不可用,例如在 自动故障转移 期间,读取请求将路由到从节点。
Atlas App Services将所有读取操作路由到当前副本集从节点之一。
Atlas App Services将所有读取操作路由到副本集的可用从节点之一。 如果没有可用的从节点,则读取请求将路由到副本集节点。
Atlas App Services将读取操作路由到相对于客户端具有最低网络延迟的副本集成员
config.wireProtocolEnabled
Boolean
如果true ,则客户端可以通过 MongoDB 传输协议连接到应用。
/data_sources/<Service Name>/config.json
{
"name": "<Service Name>",
"type": "datalake",
"config": {
"dataLakeName": "<Federated database instance name>"
}
}
字段
说明
name
String

必需。默认: mongodb-datafederation

用于引用此 App Services App 中的联合数据库实例的服务名称。名称最长可以有 64 个字符,并且只能包含 ASCII 字母、数字、下划线和连字符。

type
String
必需。 对于联合数据库实例,此值始终为"datalake"
config.dataLakeName
String
必需。 Atlas 中联合数据库实例的名称。

如果要为collection实施schema,请定义一个包含文档的 JSON schema 的schema.json文件。根级模式必须是对象模式,其形式如下:

/data_sources/<data source>/<database>/<collection>/schema.json
{
"title": "<Object Type Name>",
"bsonType": "object",
"properties": {
"<Property Name>": { <Schema> },
...
}
}
/data_sources/<data source>/<database>/<collection>/relationships.json
{
"<Source Field Name>": {
"ref": "#/relationship/<Data Source Name>/<Database Name>/<Collection Name>",
"source_key": "<Source Field Name>",
"foreign_key": "<Foreign Field Name>",
"is_list": <Boolean>
},
...
}
字段
说明
ref
String

JSON schema $ref字符串,用于指定外部collection。该字符串采用以下形式:

#/relationship/<Data Source Name>/<Database Name>/<Collection Name>
source_key
String
此集合模式中的字段名称,用于指定关系中包含的外部集合中的哪些文档。 如果source_key包含其foreign_key字段的值,则包含外部文档。
foreign_key
String
外部集合模式中包含source_key引用的值的字段的名称。
is_list
Boolean

如果为true ,则该关系可能会引用多个外部文档(即“对多”关系)。 source_key字段必须是一个数组,其元素类型与foreign_key字段相同。

如果为false ,则该关系可能引用零个或一个外部文档(即“对一”关系)。 source_key字段必须与foreign_key字段类型相同。

例子

电子商务应用程序定义两个collection之间的关系: store.orders中的每个文档通过在订单的items数组中包含商品_id值来引用store.itemscollection中的一个或多个文档。这两个collection位于同一关联集群 ( mongodb-atlas ) 和数据库 ( store )。

该关系是为orderscollection定义的:

/data_sources/mongodb-atlas/store/orders/relationships.json
{
"items": {
"ref": "#/relationship/mongodb-atlas/store/items",
"source_key": "items",
"foreign_key": "_id",
"is_list": true
}
}

您可以定义默认规则,应用于数据源中未定义更具体的collection级规则的所有collection。

您可以在数据源的default_rule.json配置文件(位于data_sources/<data-source-name>/default_rule.json中定义默认规则。

/data_sources/<data source>/default_rule.json
{
"roles": [<Role>],
"filters": [<Filter>]
}
字段
说明
roles
Array<Role>
角色配置的数组。
filters
Array<Filter>
筛选器配置的数组。

如果数据源不是“联合”数据源,则可以在collection的rules.json配置文件中定义collection级规则。

/data_sources/<data source>/<database>/<collection>/rules.json
{
"database": "<Database Name>",
"collection": "<Collection Name>",
"roles": [<Role>],
"filters": [<Filter>]
}
字段
说明
database
String
保存该collection的数据库的名称。
collection
String
集合的名称。
roles
Array<Role>
角色配置的数组。
filters
Array<Filter>
筛选器配置的数组。
{
"name": "<Role Name>",
"apply_when": { Expression },
"document_filters": {
"read": { Expression },
"write": { Expression }
},
"read": { Expression },
"write": { Expression },
"insert": { Expression },
"delete": { Expression },
"search": <Boolean>,
"fields": {
"<Field Name>": {
"read": { Expression },
"write": { Expression },
"fields": { Embedded Fields }
},
...
},
"additional_fields": {
"read": { Expression },
"write": { Expression }
}
}
字段
说明
name
string
角色的名称。角色名称用于识别和区分同一集合中的角色。限制在 100 个字符以内。
apply_when
object

一个表达式,当该角色应用于用户时,该表达式的计算结果为 true。

当未启用 Device Sync(灵活模式)时,App Services 根据每个文档分配角色。当启用 Device Sync(灵活模式)时,App Services 根据每个集合、每个会话分配角色 — 也就是说,当客户端打开同步连接时,它为每个同步集合分配角色。

为分配角色,App Services 会对每个潜在角色的apply_when求值,直到其中一个求值为 true。 潜在角色是在给定集合的rules.json配置文件中指定的任何角色,如果没有找到给定集合的rules.json文件,则为默认角色。 App Services 按照您在配置中指定角色的顺序对角色进行评估。 如果没有角色匹配,则拒绝访问。 有关更多信息,请参阅基于角色的权限。

如果启用 Device Sync(灵活模式),则分配的角色必须是Sync 兼容的。 如果该角色与同步不兼容,但其apply_when计算结果为 true,则不考虑其他角色;访问被拒绝。

document_filters
Document
Default: undefined

具有读取和写入表达式的文档,这些表达式决定是否可以评估角色的其他权限。

如果启用了 Device Sync,则必须同时定义document_filters.readdocument_filters.write以使Sync 角色兼容。 同步不兼容的角色会拒绝对同步请求的所有访问。

如果未启用 Device Sync,则document_filtersdocument_filters.readdocument_filters.write都是可选的;未定义的document_filters.readdocument_filters.write默认为 true,允许评估后续权限。

"document_filters": {
"read": { Expression },
"write": { Expression }
}
document_filters.read
object?
Default: undefined

一个表达式,用于指定是否可以评估readfields中的读取权限和additional_fields中的读取权限。 如果为 false(且document_filters.write为 undefined 或 false),则拒绝对整个文档的读取访问。

为了保持Sync 兼容性,必须定义表达式,并且表达式只能引用可查询字段。

document_filters.write
object?
Default: undefined

一个表达式,用于指定是否可以评估writefields中的写入权限和additional_fields中的写入权限。 如果为 false,则拒绝对整个文档的写入访问。

为了保持Sync 兼容性,必须定义表达式,并且表达式只能引用可查询字段。

read
object?
Default: undefined

如果角色有权读取文档中的所有字段,则该表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须是布尔值字面量( truefalse )。

Document-level read permissions take priority over any field-level permissions. 如果角色具有文档级read权限,则适用于文档中的所有字段。fieldsadditional_fields指定的读取权限不会覆盖文档级read权限。

要与字段级规则一起定义默认回退,请保留read未定义并使用additional_fields

write
object?
Default: undefined

如果角色有权添加、修改或删除文档中的所有字段,则该表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须是布尔值字面量( truefalse )。

文档级写入权限具有优先级超过任何字段级权限。如果角色具有文档级write权限,则适用于文档中的所有字段。 fieldsadditional_fields指定的写入权限不会覆盖文档级write权限。

要与字段级规则一起定义默认回退,请保留write未定义并使用additional_fields

您可以在write JSON 表达式中使用%%root%%prevRoot等扩展。

重要

隐式读取权限

每当角色拥有特定范围的write权限时,即使未明确定义,它也拥有read权限。

insert
object?
Default: true

如果角色有权将新文档插入到collection中,则表达式的计算结果为true

App Services 仅在插入操作中评估此表达式的值,并且仅在确定该角色对新文档中的所有字段都具有write权限后才计算。

delete
object?
Default: true

如果角色有权从collection中删除文档,则该表达式的计算结果为 true。

App Services 仅在删除操作中评估此表达式的值,并且仅在确定该角色对要删除的文档中的所有字段都具有write权限之后才计算。

search
Boolean
Default: true

如果角色有权使用Atlas Search Atlas SearchAtlas Search 集合,则 表达式 的计算结果为 true

重要

App Services 以系统用户身份执行 $search 操作,并对返回的搜索结果强制执行字段级规则。这意味着用户可以搜索他们没有读取权限的字段。在这种情况下,搜索基于指定字段,但返回的文档不包括该字段。

fields
Document
Default: {}

一种文档,其中每个键对应一个字段名称,每个值都定义角色对查询文档中相应字段的字段级readwrite权限。

为了保持Sync 兼容性,内部的readwrite表达式必须是布尔型字面量( truefalse )。

"fields": {
"<Field Name>": {
"read": { Expression },
"write": { Expression },
"fields": <Fields Document>
},
...
}

注意

权限优先级

文档级readwrite权限会覆盖同一类型的所有字段级权限。 如果为包含嵌入式文档的字段定义了权限,则这些权限将覆盖为文档的嵌入式字段定义的任何权限。

fields.<Field Name>.read
object?
Default: false

如果角色有权读取字段,则该表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须是布尔值字面量( truefalse )。

fields.<Field Name>.write
object?
Default: false

如果角色有权添加、修改或删除字段,则该表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须是布尔值字面量( truefalse )。

fields.<Field Name>.fields
Document
Default: {}

一个fields文档,为嵌入查询文档中此字段的字段定义readwrite权限。

有关更多信息,请参阅“嵌入式文档的字段级权限”角色模式。

additional_fields
Document
Default: {}

针对查询文档中在fields文档中没有显式定义权限的任何字段,定义角色的字段级readwrite权限的文档。

为了保持Sync 兼容性,内部的readwrite表达式必须是布尔型字面量( truefalse )。

"additional_fields": {
"read": { Expression },
"write": { Expression }
}
additional_fields.read
object?
Default: false

如果角色有权读取在fields中没有字段级权限定义的任何字段,则表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须为布尔值( truefalse )。

additional_fields.write
object?
Default: false

如果角色有权添加、修改或删除在fields中没有字段级权限定义的任何字段,则表达式的计算结果为 true。

为了保持Sync 兼容性,表达式必须为布尔值( truefalse )。

{
"name": "<Filter Name>",
"apply_when": { Expression },
"query": { MongoDB Query },
"projection": { MongoDB Projection }
}
字段
说明
name
string
必需。过滤器的名称。过滤器名称用于识别和区分过滤器。限制在 100 个字符以内。
apply_when
object

一个表达式,用于确定此筛选器何时应用于传入的 MongoDB 操作。

重要

Atlas App Services 将在读取任何文档之前评估并应用过滤器,因此您无法在过滤器的 “Apply When” 表达式中使用 MongoDB 文档扩展。但是,您也可以使用其他扩展,如 %%user%%values%function

query
object
Default: {}

一个MongoDB查询, Atlas App Services将其合并到已筛选操作的现有查询中。

例子

筛选器使用以下查询保留score低于20的文档:

{ "score": { "$gte": 20 } }
projection
object
Default: {}

一种MongoDB投影, Atlas App Services将其合并到已筛选操作的现有投影中。

重要

投影冲突

MongoDB 投影可以是包含式的或排除式的,即可以仅返回指定的字段,或者不返回未指定的字段。如果多个过滤器应用于查询,这些过滤器必须全部指定相同类型的投影,否则查询会失败。

例子

过滤器使用以下投影从所有文档中保留_internal字段:

{ "_internal": 0 }

来年

什么是 Atlas App Services?