Filtrar queries de entrada
Visão geral
Um filtro modifica uma query de entrada do MongoDB para retornar somente um subconjunto dos resultados correspondentes à query. Adicionar um filtro a uma collection permite controlar a forma dos documentos consultados e pode melhorar o desempenho da consulta.
Os filtros adicionam parâmetros de query adicionais e omitem campos dos resultados de query antes que o Atlas App Services execute a consulta. Cada filtro tem três componentes:
Uma expressão "aplicar quando" que determina se o filtro se aplica a uma solicitação de entrada. Você pode utilizar variáveis como
%%usere%%requestna expressão "aplicar quando". No entanto, você não pode usar expansões que se refiram a um documento como%%rootporque o App Services avalia a expressão "aplicar quando" antes de ler qualquer documento.Uma expressão de query opcional, que se funde com a query existente de qualquer solicitação à qual o filtro se aplica.
Um documento de projeção opcional, que usa a sintaxe de projeção padrão do MongoDB e se mescla com a projeção existente de qualquer solicitação à qual o filtro se aplica.
Como o App Services aplica filtros
O App Services avalia e aplica filtros para todas as solicitações do MongoDB onde as regras se aplicam, exceto solicitações de Device Sync. Exemplos de solicitações do MongoDB que podem ser filtradas incluem:
Uma query sobre uma coleção.
Uma escrita para um documento.
Um filtro se aplica a uma dada solicitação se sua expressão "aplicar quando" for verdadeira dado o contexto dessa solicitação. Se um filtro se aplica a uma solicitação, o App Services mescla a query do filtro ou projeção na query e projeção existentes da operação solicitada.
Vários filtros podem ser aplicados a uma única solicitação.
O App Services aplica filtros à solicitação antes de enviar a solicitação ao MongoDB.
Exemplo
Uma collection contém vários milhões de documentos e tem uma role com a seguinte expressão "aplicar quando":
{ "owner_id": "%%user.id" }
Se nenhum filtro for aplicado, os Serviços de aplicativos avaliarão uma função para cada documento que a query corresponder. Sabemos que os App Services reterão qualquer documento que não tenha o ID do usuário como o valor do campo owner_id, portanto, economizamos tempo e recursos de computação aplicando um query adicional que exclui esses documentos antes que os App Services avaliem qualquer função:
Aplicar quando | Query | Projeção |
|---|---|---|
{ "%%true": true } | { "owner_id": "%%user.id" } | {} |
Definir filtros
Você pode usar filtros para otimizar queries, minimizar a sobrecarga de computação e proteger dados sensíveis. Os filtros são mais úteis para preocupações transversais que afetam algumas ou todas as suas queries.
Considere usar filtros se quiser que um sistema centralizado:
Restringir queries a um subconjunto de todos os documentos
Omitir dados confidenciais ou campos não utilizados
Exemplo
Em um aplicativo de votação onde alguns usuários concordaram em compartilhar anonimamente seu voto, você poderia usar o seguinte filtro para restringir todas as queries a um subconjunto anônimo dos dados existentes:
{ "name": "AnonymizeVotes", "apply_when": true, "query": { "shareVoteAnonymous": true }, "project": { "_id": 0, "age": 1, "vote": 1 } }
{ "_id": ObjectId(...), "name": "sarah", age: 42, "vote": "yes", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "andy", age: 22, "vote": "no", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "jennifer", age: 37, "vote": "yes", "shareVoteAnonymous": false } { "_id": ObjectId(...), "name": "rick", age: 43, "vote": "no", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "tom", age: 64, "vote": "yes", "shareVoteAnonymous": false } { "_id": ObjectId(...), "name": "bob", age: 67, "vote": "yes", "shareVoteAnonymous": true }
{ age: 42, "vote": "yes" } { age: 22, "vote": "no" } { age: 37, "vote": "yes" } { age: 43, "vote": "no" } { age: 64, "vote": "yes" } { age: 67, "vote": "yes" }
Procedimento
Você pode definir filtros para collections específicas em seu cluster vinculado a partir da UI do App Services ou implantando arquivos de configuração com a Realm CLI:
Observação
Este aba requer uma fonte de dadosvinculada ao MongoDB Atlas.
Especificar a expressão "aplicar quando"
Na caixa de entrada Apply When, insira uma expressão de regra que define quando o filtro se aplica a uma query. Se a expressão for avaliada como true para uma query recebida, o App Services adicionará os parâmetros Filter Query à query recebida.
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.
Especifique os predicados da query de filtro
Na caixa de entrada Query, especifique um documento que contenha predicados de query adicionais para mesclar na query recebida quando o filtro for aplicado. Por exemplo, um filtro que retém documentos que tenham score abaixo de 20 poderia usar a seguinte query de filtro:
{ "score": { "$gt": 20 } }
Especifique a projeção do filtro
Na caixa de entrada Projection , especifique um documento que contenha um documento deprojeção para mesclar na query recebida quando o filtro se aplicar.
Por exemplo, um filtro que retém os campos career_stats e personal dos documentos pode usar a seguinte projeção de filtro:
{ "career_stats": 0, "personal": 0 }
Obtenha a versão mais recente da sua aplicação
Para definir filtros para uma coleção com appservices, você precisa de uma cópia local dos arquivos de configuração do seu aplicativo.
Para extrair uma cópia local da versão mais recente do seu aplicativo, execute o seguinte:
appservices pull --remote="<Your App ID>"
Dica
Você também pode baixar uma cópia dos arquivos de configuração do seu aplicativo na tela Deploy > Export App na interface do usuário do App Services.
Adicionar um arquivo de configuração de regra
Para definir ou modificar roles para uma coleção, abra o arquivo de configuração do rules.json dentro do diretório de configuração da coleção.
Dica
Organize a coleção
Se você ainda não tiver definido regras ou um esquema para a coleção, precisará criar manualmente seu diretório de configuração e schema.json:
# Create the collection's configuration directory mkdir -p data_sources/<service>/<db>/<collection> # Create the collection's schema file echo '{}' >> data_sources/<service>/<db>/<collection>/rules.json
O arquivo de configuração deve ter o seguinte formato geral:
{ "database": "<Database Name>", "collection": "<Collection Name>", "roles": [], "filters": [] }
Observação
Este guia se concentra em criar filters para a collection. Confira os outros guias de configuração para saber como definir funções e permissões e aplicar esquemas.
Observação
As fontes de dados federadas não suportam regras ou esquemas. Você só pode acessar uma fonte de dados federada a partir de uma função do sistema.
Adicionar um ou mais filtros
Adicione um documento à array filters para cada filtro que você deseja configurar. Os documentos de filtro têm o seguinte formulário:
{ "name": "<Filter Name>", "apply_when": { Expression }, "query": { MongoDB Query }, "projection": { MongoDB Projection } }
Campo | Descrição | |
|---|---|---|
namestring | 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_whenobject | Uma expressão que determina quando esse filtro se aplica a uma operação MongoDB de entrada. ImportanteO 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 | |
queryobjectDefault: {} | Uma query doMongoDB que o Atlas App Services mescla à query existente de uma operação filtrada. ExemploUm filtro retém documentos que tenham | |
projectionobjectDefault: {} | Uma projeção doMongoDB que o Atlas App Services mescla na projeção existente de uma operação filtrada. ImportanteConflitos de projeçãoAs 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á. ExemploUm filtro retém o campo |
Observação
Considerações de segurança para filtros de App Services
Enquanto filtros e permissões baseadas em roles podem ocultar documentos e campos específicos dentro de uma collection, é possível que os dados possam ser expostos se o sistema permitir que queries arbitrárias acessem a collection.
Por exemplo, consultas ou roles que geram erros dependendo dos valores armazenados em uma collection (como erros de divisão por zero) podem revelar informações sobre documentos, mesmo que uma role ou filtro impeça o usuário que faz query de exibir documentos diretamente. Os usuários também podem fazer inferências sobre os dados subjacentes de outras maneiras (como medindo o tempo de execução da query, que pode ser afetado pela distribuição dos dados).
Esteja ciente de que isso é possível e audite seus padrões de acesso aos dados quando necessário.