Menu Docs

Página inicial do DocsServiços Atlas App

Arquivos de configuração do conjunto de dados do MongoDB

Nesta página

  • Configuração do serviço
  • Clusters do MongoDB
  • Instâncias do banco de dados federado
  • reconhecimento de data center e collection
  • Esquema de collection
  • Relacionamentos
  • Regras padrão
  • Regras de collection
  • Configurações de regras
  • Funções
  • Filtros
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>
}
}
Campo
Descrição
name
string

Obrigatório. Padrão: mongodb-atlas

O nome do serviço usado para se referir ao cluster dentro deste Atlas App Services App. O nome pode ter no máximo 64 caracteres e deve conter apenas letras, números, sublinhados e hífens ASCII.

type
string
Obrigatório. Para clusters do MongoDB Atlas, esse valor é sempre "mongodb-atlas".
config.clusterName
string
Obrigatório. O nome do cluster no Atlas.
config.readPreference
string

O modo de preferência de leitura para query enviadas por meio do serviço.

Modo
Descrição
O App Services roteia todas as operações de leitura para o nó primário do conjunto de réplicas atual. Este é o modo de read preference padrão.
O App Services roteia todas as operações de leitura para o nó primário do conjunto de réplicas atual, se estiver disponível. Se o primário não estiver disponível, como durante um failover automático, as solicitações de leitura serão roteadas para um nó secundário .
O App Services roteia todas as operações de leitura para um dos nós secundários do conjunto de réplicas atual.
O App Services roteia todas as operações de leitura para um dos nós secundários disponíveis do conjunto de réplicas. Se nenhum secundário estiver disponível, as solicitações de leitura serão roteadas para o conjunto de réplicas primário .
O App Services encaminha as operações de leitura para o membro do conjunto de réplicas que tem a menor latência de rede em relação ao cliente.
config.wireProtocolEnabled
Boolean
/data_sources/<Service Name>/config.json
{
"name": "<Service Name>",
"type": "datalake",
"config": {
"dataLakeName": "<Federated database instance name>"
}
}
Campo
Descrição
name
string

Obrigatório. Padrão: mongodb-datafederation

O nome do serviço costumava se referir à instância do banco de dados federado nesse aplicativo do App Services. O nome pode ter no máximo 64 caracteres e deve conter apenas letras, números, sublinhados e hífens ASCII.

type
string
Obrigatório. Para uma instância do banco de dados federado, esse valor é sempre "datalake".
config.dataLakeName
string
Obrigatório. O nome da instância do Banco de Dados Federado no Atlas.

Se você deseja impor um esquema para uma collection, defina um arquivo de configuração schema.json que contém um JSON schema para os documento. O esquema de nível raiz deve ser um esquema de objeto, que possui o seguinte formato:

/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>
},
...
}
Campo
Descrição
ref
string

Uma string de JSON schema $ref que especifica a collection externa. A string tem o seguinte formato:

#/relationship/<Data Source Name>/<Database Name>/<Collection Name>
source_key
string
O nome do campo no esquema desta collection que especifica quais documento da collection estrangeira incluir no relacionamento. Um documento externo será incluído se source_key contiver o valor de seu campo foreign_key .
foreign_key
string
O nome do campo no esquema da collection externa que contém o valor referenciado por source_key.
is_list
Boolean

Se true, o relacionamento pode se referir a vários documentos estrangeiros (ou seja, um relacionamento "para muitos"). O campo source_key deve ser uma array com elementos do mesmo tipo que o campo foreign_key .

Se false , o relacionamento pode se referir a zero ou um documento estrangeiro (ou seja, um relacionamento "para-um"). O campo source_key deve ser do mesmo tipo que o campo foreign_key .

Exemplo

Um aplicativo de e-commerce define um relacionamento entre duas collections: cada documento em store.orders faz referência a um ou mais documentos na collection store.items ao incluir valores de item _id na array items do pedido. Ambas as coleções estão no mesmo cluster vinculado (mongodb-atlas) e banco de dados (store).

O relacionamento é definido para a coleção orders :

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

Você pode definir regras padrão que se aplicam a todas as collections em uma fonte de dados que não tenham regras mais específicas em nível de collection definidas.

Você define regras padrão no arquivo de configuração default_rule.json da fonte de dados em data_sources/<data-source-name>/default_rule.json.

/data_sources/<data source>/default_rule.json
{
"roles": [<Role>],
"filters": [<Filter>]
}
Campo
Descrição
roles
Array<Role>
Uma array de configurações de funções .
filters
Array<Filter>
Uma array de configurações de Filtro .

Se a fonte de dados não for uma fonte de dados federada, você poderá definir as regras em nível de collection no arquivo de configuração rules.json de uma collection.

/data_sources/<data source>/<database>/<collection>/rules.json
{
"database": "<Database Name>",
"collection": "<Collection Name>",
"roles": [<Role>],
"filters": [<Filter>]
}
Campo
Descrição
database
string
O nome do reconhecimento de data center que contém a collection.
collection
string
O nome da collection.
roles
Role[]
Uma array de configurações de funções .
filters
Filter[]
Uma array de configurações de Filtro .
{
"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 }
}
}
Campo
Descrição
name
string
O nome da role. Os nomes de roles identificam e distinguem entre roles na mesma collection. Limitado a 100 caracteres ou menos.
apply_when
object

Uma expressão avaliada como verdadeira quando essa role se aplica a um usuário.

Quando o Device Sync (modo flexível) não está ativado, o App Services atribui uma função por documento. Quando o Realm Mobile Sync (modo flexível) está habilitado, o App Services atribui funções por collection e por sessão, ou seja, para cada collection sincronizada quando um cliente abre uma conexão de sincronização.

Para atribuir uma função, o App Services avalia o apply_when de cada função potencial até que uma seja avaliada como verdadeira. Funções possíveis são quaisquer funções especificadas no arquivo de configuração rules.json para a collection fornecida ou, se nenhum arquivo rules.json for encontrado para a collection fornecida, a(s) função(ões) padrão. O App Services avalia as funções na ordem em que você as especifica em sua configuração. Se nenhuma função corresponder, o acesso será negado. Para obter mais informações, consulte Permissões baseadas em roles.

Se o Device Sync (modo flexível) estiver ativado, as funções atribuídas deverão ser compatíveis com a sincronização. Se a role não for compatível com a sincronização, mas seu apply_when for avaliado como verdadeiro, as outras roles não serão consideradas; o acesso é negado.

document_filters
Documento
Padrão: undefined

Um documento com expressões de leitura e gravação que determinam se as outras permissões da role podem ser avaliadas.

Se o Device Sync estiver habilitadoo, document_filters.read e document_filters.write deverão ser definidos para tornar a role Sync compatível. A sincronização de roles incompatíveis nega o acesso a todas as solicitações de sincronização.

Se o Realm Mobile Sync não estiver habilitado, document_filters, document_filters.read e document_filters.write serão opcionais; um document_filters.read ou document_filters.write indefinido tem como padrão verdadeiro, permitindo que as permissões subsequentes sejam avaliadas.

"document_filters": {
"read": { Expression },
"write": { Expression }
}
document_filters.read
object?
Padrão: undefined

Uma expressão que especifica se read, as permissões de leitura em fields e as permissões de leitura em additional_fields podem ser avaliadas. Se falso (e document_filters.write for indefinido ou falso), o acesso de leitura será negado para todo o documento.

Para manter a compatibilidade do Sync, a expressão deve ser definida e só pode fazer referência a campos de query .

document_filters.write
object?
Padrão: undefined

Uma expressão que especifica se write, as permissões de escrita em fields e as permissões de escrita em additional_fields podem ser avaliadas. Se falso, o acesso de escrita será negado para todo o documento.

Para manter a compatibilidade do Sync, a expressão deve ser definida e só pode fazer referência a campos de query .

read
object?
Padrão: undefined

Uma expressão que avalia para verdadeira se a função tiver permissão para ler todos os campos no documento.

Para manter a compatibilidade de sincronização, a expressão deve ser um literal booleano ( true ou false).

As permissões de leitura no nível do documento têm prioridade sobre quaisquer permissões no nível do campo. Se uma função tiver permissões read em nível de documento, ela se aplicará a todos os campos do documento. As permissões de leitura especificadas por fields ou additional_fields não substituem as permissões read no nível do documento.

Para definir um fallback padrão junto com as regras em nível de campo, deixe read indefinido e use additional_fields.

write
object?
Padrão: undefined

Uma expressão avaliada como verdadeira se a role tiver permissão para adicionar, modificar ou remover todos os campos no documento.

Para manter a compatibilidade de sincronização, a expressão deve ser um literal booleano ( true ou false).

As permissões de gravação no nível do documento têm prioridade sobre quaisquer permissões no nível do campo. Se uma função tiver permissões write em nível de documento, ela se aplicará a todos os campos do documento. As permissões de gravação especificadas por fields ou additional_fields não substituem as permissões write no nível do documento.

Para definir um fallback padrão junto com as regras em nível de campo, deixe write indefinido e use additional_fields.

Você pode utilizar expansões como %%root e %%prevRoot em write expressões JSON.

Importante

Permissão de leitura implícita

Sempre que uma função tem permissão write para um escopo específico, ela também tem permissão read , mesmo que isso não seja explicitamente definido.

insert
object?
Padrão: true

Uma expressão que avalia para true se o papel tem permissão para inserir um novo documento na collection.

O App Services só avalia essa expressão para operações de inserção e somente após determinar que a role tem permissão write para todos os campos no novo documento.

delete
object?
Padrão: true

Uma expressão que é avaliada como verdadeira se a role tiver permissão para excluir um documento da collection.

O App Services só avalia essa expressão para operações de exclusão e somente após determinar que a role tem permissão write para que todos os campos do documento sejam excluídos.

search
Boolean
Padrão: true

Uma expressão avaliada como verdadeira se o role tiver permissão para pesquisar a collection usando o Atlas Search.

Importante

O App Services $search executa as operações como um usuário do sistema e o impõe regras de nível de campo nos resultados de pesquisa retornados. Isso significa que um usuário pode pesquisar em um campo para o qual ele não tem acesso de leitura. Nesse caso, a pesquisa é baseada no campo especificado, mas nenhum documento retornado inclui o campo.

fields
Documento
Padrão: {}

Um documento em que cada chave corresponde a um nome de campo e cada valor define as permissões read e write em nível de campo da função para o campo correspondente em um documento consultado.

Para manter a compatibilidade de sincronização, as expressões read e write internas devem ser literais booleanos ( true ou false).

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

Observação

Prioridade de permissão

As permissões read ou write em nível de documento substituem todas as permissões em nível de campo do mesmo tipo. Se as permissões forem definidas para um campo que contém um documento incorporado, essas permissões substituirão quaisquer permissões definidas para os campos incorporados do documento.

fields.<Field Name>.read
object?
Padrão: false

Uma expressão avaliada como verdadeira se a role tiver permissão para ler o campo.

Para manter a compatibilidade de sincronização, a expressão deve ser um literal booleano ( true ou false).

fields.<Field Name>.write
object?
Padrão: false

Uma expressão avaliada como verdadeira se a role tiver permissão para adicionar, modificar ou remover o campo.

Para manter a compatibilidade de sincronização, a expressão deve ser um literal booleano ( true ou false).

fields.<Field Name>.fields
Documento
Padrão: {}

Um documento fields que define permissões read e write para campo incorporados a este campo em um documento query.

Consulte o padrão de função Permissões de nível de campo para documentos incorporados para obter mais informações.

additional_fields
Documento
Padrão: {}

Um documento que define as permissões read e write em nível de campo da função para quaisquer campos em um documento consultado que não têm permissões explicitamente definidas no documento fields .

Para manter a compatibilidade de sincronização, as expressões read e write internas devem ser literais booleanos ( true ou false).

"additional_fields": {
"read": { Expression },
"write": { Expression }
}
additional_fields.read
object?
Padrão: false

Uma expressão avaliada como verdadeira se a role tiver permissão para ler qualquer campo que não tenha uma definição de permissão de nível de campo em fields.

Para manter a compatibilidade de sincronização, a expressão deve ser booleana ( true ou false).

additional_fields.write
object?
Padrão: false

Uma expressão avaliada como verdadeira se a role tiver permissão para adicionar, modificar ou remover qualquer campo que não tenha uma definição de permissão de nível de campo em fields.

Para manter a compatibilidade de sincronização, a expressão deve ser booleana ( true ou false).

{
"name": "<Filter Name>",
"apply_when": { Expression },
"query": { MongoDB Query },
"projection": { MongoDB Projection }
}
Campo
Descrição
name
string
Obrigatório. O nome do filtro. Os nomes de filtros são úteis para identificar e distinguir entre filtros. Limitado a 100 caracteres ou menos.
apply_when
object

Uma expressão que determina quando esse filtro se aplica a uma operação MongoDB de entrada.

Importante

O Atlas App Services avalia e aplica filtros antes de ler qualquer tipo de documento, portanto, você não pode usar expansões de documentos do MongoDB em uma expressão Apply When de um filtro. No entanto, você pode usar outras expansões, como %%user, %%valuese %function.

query
object
Padrão: {}

Uma query do MongoDB que o App Services mescla à query existente de uma operação filtrada.

Exemplo

Um filtro retém documentos que tenham score abaixo 20 usando a seguinte query:

{ "score": { "$gte": 20 } }
projection
object
Padrão: {}

Uma projeção do MongoDB de que o App Services se funde na projeção existente de uma operação filtrada.

Importante

Conflitos de projeção

As projeção do MongoDB podem ser inclusivas ou exclusivas, ou seja, podem retornar apenas campo especificados ou reter campo que não são especificados. Se vários filtros se aplicarem a uma query, todos os filtros deverão especificar o mesmo tipo de projeção, ou a query falhará.

Exemplo

Um filtro retém o campo _internal de todos os documentos usando a seguinte projeção:

{ "_internal": 0 }
← Arquivos de configuração do provedor de autenticação e usuário