Visão geral
Uma expressão de regra é um objeto JSON que você grava para controlar o acesso aos dados com permissões. Cada expressão define as condições sob as quais um usuário pode executar alguma ação. Por exemplo, você pode escrever uma expressão para controlar se um usuário pode ler ou gravar dados em um documento do MongoDB ou em um Realm sincronizado.
O App Services avalia uma expressão de regra, geralmente com um documento como entrada, para obter um resultado verdadeiro ou falso.
Você pode definir expressões simples e estáticas que usam valores codificados:
{ "id": "aaaabbbbccccddddeeeeffff" }
Você também pode escrever expressões que suportam lógica arbitrária para expressar requisitos dinâmicos e fluxos de trabalho complexos ou personalizados. Uma expressão dinâmica pode incluir variáveis que refletem o contexto atual, chamadas de expansões, e podem usar operadores integrados para transformar dados. O exemplo a seguir é avaliado como verdadeiro se o campo do documento de entrada owner
for igual ao do usuário id
e o endereço IP remoto da solicitação puder ser encontrado em uma array de endereços IP permitidos que é armazenado como um valor:
{ "owner": "%%user.id", "%%request.remoteIPAddress": { "$in": "%%values.allowedClientIPAddresses" } }
Restrições
Ao usar o Realm Mobile Sync, a expressão têm restrições especiais. Consulte expressão Compatíveis com Sincronização.
Sintaxe de Expressão
Uma expressão é um valor booleano (ou seja, true
ou false
) ou um objeto JSON.
Os nomes de campo do objeto de expressão podem ser um valor, uma expansão ou um operador. Cada campo deve conter um valor, uma expansão ou uma expressão aninhada.
Objetos de expressão têm o seguinte formato:
{ <Value | Expansion | Operator>: <Value | Expression>, ... }
expressões incorporadas
Você pode incorporar vários documentos de expressão nos campos de outro documento de expressão para lidar com a lógica de avaliação complexa. O App Services avalia as expressões em profundidade, pós-ordem: ou seja, ele começa na parte inferior da árvore de expressões e trabalha de volta aos campos de nível raiz, avaliando cada expressão após todas as suas expressões incorporadas.
Exemplo
Esta expressão é avaliada como true
somente se o número fornecido como o argumento someNumber
estiver em um intervalo específico.
{ "%%args.someNumber": { "%and": [ { "$gt": 0 }, { "$lte": 42 } ] } }
expressão de vários campo
Quando você tem mais de um campo em uma expressão, essa expressão é avaliada como true
se e somente se cada campo na expressão for avaliado como verdadeiro. Em outras palavras, o App Services trata vários campos em uma única expressão como uma operação "E".
Exemplo
Essa expressão de regra de serviço de terceiros é avaliada como true
somente se o argumento url
foi fornecido e o argumento body.userId
corresponder ao ID do usuário que chamou a ação.
{ "%%args.url": { "$exists": true }, "%%args.body.userId": "%%user.id" }
Avaliação de expressão
O App Services avalia expressões substituindo primeiro as expansões por seus valores de tempo de execução e, em seguida, avaliando cada campo do documento de expressão expandida para uma expressão booleana. Se todos os campos em uma expressão avaliarem para true
, a expressão também avaliará para true
. Uma expressão vazia ({}
) é avaliada como true
.
Os campos de expressão avaliam com base nas seguintes regras:
Se um nome de campo expandido corresponder ao seu valor, ele será avaliado como
true
.Se o valor de um campo for uma expressões incorporadas, ele será avaliado como o mesmo valor que a expressões incorporadas. Consulte expressões incorporadas.
Observação
Se uma regra não usar explicitamente a expansão %%args
ou %%root
, os nomes dos campo de expressão serão padronizados para verificar argumentos ou campos de documento com o mesmo nome. Por exemplo, a expressão { "url": "https://www.example.com" }
tem como padrão avaliar o valor em relação a %%args.url
em uma regra de serviço e %%root.url
em uma regra do MongoDB .
Expansões
Uma expansão é uma variável que representa um valor dinâmico em uma expressão. As expansões são indicadas por dois sinais de porcentagem seguidos do nome da expansão. São eles:
%%root
, que representa os dados em um documento MongoDB.%%user
, que representa um usuário interagindo com seu aplicativo.%%request
, que representa uma solicitação recebida.%%values
, que representa um valor estático.%%environment
, que representa o ambiente do seu aplicativo.%%args
, que representa os argumentos que foram passados para uma ação de serviço.
Quando seu aplicativo avalia uma expressão, ele substitui cada expansão na expressão por um valor específico determinado pela configuração do seu aplicativo e o contexto no momento da avaliação.
Exemplo
O exemplo seguinte utiliza as expansões %%user
e %%root
em uma expressão "aplicar quando":
"applyWhen": { "%%user.custom_data.status": "ACTIVE", "%%root.owners": "%%user.id" }
Observação
Algumas expansões, como %%user
, estão disponíveis em todas as expressões. Outros são limitados a contextos específicos, como %%root
, que não é compatível com sincronização e está disponível apenas em expressões que operam em um documento.
Ao usar o Device Sync, as expansões têm restrições especiais. Consulte Expansões compatíveis com sincronização.
Expansões lógicas
Expansões de valor
%%values
- Type:
object
Usable In: Any ExpressionRepresenta os valores do seu aplicativo. Cada campo do objeto mapeia um nome de valor para seu valor JSON ou segredo correspondente.
Exemplo
A seguinte expressão é avaliada como
true
se o valoradmin_ids
for uma lista que contém o ID da conta do usuário:{ "%%user.id": { "$in": "%%values.admin_ids" } }
Expansões de ambiente
%%environment
- Type:
object
Usable In: Any ExpressionRepresenta o ambiente atual da aplicação. Você pode ler o nome do ambiente (
tag
) e acessar os valores do ambiente.Cada propriedade do objeto mapeia o nome de um valor de ambiente para seu valor no ambiente atual.
{ "tag": "<Environment Name>" "values": { "<ValueName>": <Value> } } Exemplo
A seguir está uma expressão de regra que avalia para
true
se o ambiente atual for"production"
e o valor de ambiente"baseUrl"
estiver definido:{ "%%environment.tag": "production", "%%environment.values.baseUrl": { "%exists": true } }
Solicitar expansões
%%request
- Type:
object
Usable In: Any ExpressionRepresenta a solicitação recebida.
{ "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>" }
Expansões de usuário
%%user
- Type:
object
Usable In: Any ExpressionRepresenta o usuário que iniciou a solicitação. O objeto contém informações da conta, metadados do provedor de autenticação e dados personalizados da sua aplicação.
{ "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.type
- Type:
"normal" | "server"
Usable In: Any ExpressionO tipo de usuário que iniciou a solicitação. Avalia como
"server"
para usuários de chaves de API e"normal"
para todos os outros usuários.
%%user.custom_data
- Type:
object
Usable In: Any ExpressionOs dados personalizados do usuário. O conteúdo exato varia dependendo da sua configuração de dados de usuário personalizada .
Exemplo
"custom_data": { "primaryLanguage": "English", }
%%user.data
- Type:
object
Usable In: Any ExpressionOs metadados do usuário. O conteúdo exato variará dependendo das identidades do provedor de autenticação associadas ao usuário.
Exemplo
"data": { "name": "Joe Mango", "email": "joe.mango@example.com" }
%%user.identities
- Type:
object[]
Usable In: Any ExpressionUma lista de todas as identidades do provedor de autenticação associadas ao usuário. Uma identidade consiste em um identificador exclusivo fornecido a um usuário por um provedor de autorização junto com o tipo do provedor:
Exemplo
"identities": [ { "id": "5bce299457c70db9bd73b8-aajddbkuvomsvcrjjfoxs", "providerType": "local-userpass" } ]
Expansões de documentos do MongoDB
%%this
- Type:
any
Usable In: MongoDB Atlas Data SourcesO valor de um campo específico conforme existe no final de uma operação de reconhecimento de data center.
%%prev
- Type:
any
Usable In: MongoDB Atlas Data SourcesO valor de um campo específico antes de ser alterado por uma operação de gravação.
%%root
- Type:
object
Usable In: MongoDB Atlas Data SourcesO documento conforme existe no final de uma operação do reconhecimento de data center.
%%prevRoot
- Type:
object
Usable In: MongoDB Atlas Data SourcesO documento completo antes de ser alterado por uma operação de gravação.
Exemplo
A seguir está uma expressão de validação de esquema do MongoDB que é avaliada como true
se o documento existiu anteriormente (ou seja, a ação não é uma inserção) ou se o campo status
do documento tem um valor de "new"
:
{ "%or": [ { "%%prevRoot": { "%exists": %%true } }, { "%%root.status": "new" } ] }
Expansões de serviço
%%args
- Type:
object
Usable In: Third-Party ServicesUm documento contendo os valores passados como argumentos para uma ação de serviço. Você pode acessar cada argumento pelo nome do parâmetro.
Exemplo
A seguir está uma regra de serviço do Twilio que avalia como
true
se o número de telefone do remetente (o argumentofrom
) corresponder a um valor específico:{ "%%args.from": "+15558675309" }
%%partition
- Type:
string | number | BSON.ObjectId
Usable In: Partion-based Sync(Somente sincronização baseada em partição .) O valor da chave da partição da partição atual que está sendo avaliada.
Operadores
Um operador de expressão representa uma ação ou operação dentro de uma expressão. Os operadores recebem um ou mais argumentos e avaliam para um valor de resultado. O tipo e o valor do resultado dependem do operador que você utiliza e dos argumentos que você passa para ele.
Os operadores de expressão são indicados por strings que começam com um único sinal de porcentagem (%
) ou um cifrão ($
). Você pode usá-las em qualquer expressão.
Converter valores EJSON
Os seguintes operadores permitem a você converter valores entre representações EJSON e JSON:
%stringToOid
Converte uma string de 12 bytes ou 24 bytes em um objeto EJSON
objectId
.Exemplo
{ "_id": { "%stringToOid": "%%user.id" } }
%oidToString
Converte um objeto EJSON
objectId
em uma string.Exemplo
{ "string_id": { "%oidToString": "%%root._id" } }
%stringToUuid
Converte uma string de 36 bytes em um objeto EJSON
UUID
.Exemplo
{ "_id": { "%stringToUuid": "%%user.id" } }
%uuidToString
Converte um objeto EJSON
UUID
em uma string.Exemplo
{ "string_id": { "%uuidToString": "%%root._id" } }
Importante
Sem operações internas
%stringToUuid
, %uuidToString
, %stringToOid
e %oidToString
não avaliam operadores JSON. Você deve fornecer uma string literal/ objeto EJSON ou uma expansão que seja avaliada como um.
Chamar uma função
Os seguintes operadores permitem que você chame funções em seu aplicativo App Services:
%function
Chama uma função com o nome e argumentos especificados. Avalia o valor que a função retorna.
Exemplo
{ "%%true": { "%function": { "name": "isEven", "arguments": [42] } } }
Verificar existência
Os seguintes operadores permitem a você determinar se um valor existe em um objeto ou array:
$exists
Verifica se o campo ao qual é atribuído tem algum valor. Avalia como um booleano que representa o resultado.
Exemplo
{ "url": { "$exists": true } }
Compare Values
Os seguintes operadores permitem comparar valores, incluindo valores expandidos :
$eq
Verifica se o campo ao qual é atribuído é igual ao valor especificado. Avalia como um booleano que representa o resultado.
Exemplo
{ "score": { "$eq": 42 } }
$ne
Verifica se o campo ao qual é atribuído não é igual ao valor especificado. Avalia como um booleano que representa o resultado.
Exemplo
{ "numPosts": { "$ne": 0 } }
$gt
Verifica se o campo ao qual é atribuído é estritamente maior que o valor especificado. Avalia como um booleano que representa o resultado.
Exemplo
{ "score": { "$gt": 0 } }
$gte
Verifica se o campo ao qual é atribuído é maior ou igual ao valor especificado. Avalia como um booleano que representa o resultado.
Exemplo
{ "score": { "$gte": 0 } }