Funções do Atlas

Nesta página

Quando usar as funções

Como escrever uma função
Definir uma função
Chamar uma função
Restrições

Uma função do Atlas é um código JavaScript do lado do servidor que você grava para definir o comportamento de seu aplicativo. Você pode chamar as funções do seu aplicativo diretamente de um aplicativo de cliente ou definir serviços que integram e chamam funções automaticamente.

As funções podem chamar outras funções e incluir um cliente integrado para trabalhar com dados em clusters MongoDB Atlas. Elas também incluem utilitários globais úteis, suportam módulos integrados comuns do Node.js e podem importar e usar pacotes externos do registro npm.

Uma função básica que retorna uma saudação

exports = function(name) {
  return `Hello, ${name ?? "stranger"}!`
}

As funções são sem servidor

Quando uma função é chamada, seu aplicativo encaminha a solicitação para um servidor de aplicativos gerenciado que avalia seu código e retorna o resultado. Esse modelo torna as funções sem servidor, o que significa que você não precisa implantar e gerenciar um servidor para executar o código. Em vez disso, você escreve o código-fonte da função e seu aplicativo lida com o ambiente de execução.

Funções têm contexto

Uma função é executada em um contexto que reflete seu ambiente de execução. O contexto inclui o usuário que chamou a função, como ele a chamou e o estado de seu aplicativo quando a chamou. Pode utilizar contexto para executar código específico do usuário e trabalhar com outras partes de seu aplicativo.

Para saber mais sobre como trabalhar com o contexto da Função, consulte Contexto .

Quando usar as funções

As funções podem executar código JavaScript arbitrário definido por você, o que significa que você pode usá-las para quase tudo. Os casos de uso comuns incluem tarefas de baixa latência e execução curta, como movimentação de dados, transformações e validação. Você também pode usá-los para se conectar a serviços externos e abstrair os detalhes de implementação dos aplicativos clientes.

Aciona automaticamente funções de chamada para lidar com eventos específicos. Por exemplo, sempre que um gatilho de banco de dados (trigger) observa um evento de alteração, ele chama sua função associada com o evento de alteração como argumento. Na função de trigger , é possível acessar as informações do evento de modificação e responder adequadamente.

Observação

Banco de dados e gatilhos agendados sempre são executados no contexto de um usuário do sistema.

Como escrever uma função

O código de uma função é essencialmente um arquivo de código fonte JavaScript nomeado, o que significa que você pode definir várias funções JavaScript em um único arquivo de função. O arquivo deve exportar uma única função JavaScript para servir como ponto de entrada das chamadas recebidas. Quando você chama uma função por nome, você está realmente chamando a função JavaScript atribuída a exports no arquivo de origem da função.

Por exemplo, aqui está uma função simples que aceita um argumento name, adiciona uma mensagem de registro e retorna uma saudação para o nome fornecido:

exports = function Hello(name) {
   console.log(`Said hello to ${name}`);
   return `Hello, ${name}!`;
};

Você pode usar a sintaxe JavaScript moderna e importar pacotes para definir funções mais complexas:

// You can use ES6 arrow functions
const uppercase = (str) => {
   return str.toUpperCase();
};
// You can use async functions and await Promises
exports = async function GetWeather() {
// You can get information about the user called the function
const city = context.user.custom_data.city;
// You can import Node.js built-ins and npm packages
const { URL } = require("url");
const weatherUrl = new URL("https://example.com");
weatherUrl.pathname = "/weather";
weatherUrl.search = `?location="${city}"`;
// You can send HTTPS requests to external services
const weatherResponse = await context.http.get({
   url: url.toString(),
   headers: {
      Accept: ["application/json"],
   },
});
const { current, forecasts } = JSON.parse(weatherResponse.body.text());
return [
   `Right now ${uppercase(city)} is ${current.temperature}°F and ${current.weather}.`,
   `Here's the forecast for the next 7 days:`,
   forecasts
      .map((f) => `${f.day}: ${f.temperature}°F and ${f.weather}`)
      .join("\n  "),
].join("\n");
};

Right now NEW YORK CITY is 72°F and sunny.
Here's the forecast for the next 7 days:
  Tuesday: 71°F and sunny
  Wednesday: 72°F and sunny
  Thursday: 73°F and partly cloudy
  Friday: 71°F and rainy
  Saturday: 77°F and sunny
  Sunday: 76°F and sunny
  Monday: 74°F and sunny

As funções serializam automaticamente os valores retornados para JSON estendido. Isto é útil para preservar informações de tipo, mas pode não ser o que seu aplicação espera.

Por exemplo, os valores no objeto retornado da seguinte função são convertidos em valores EJSON estruturados:

exports = function() {
  return {
    pi: 3.14159,
    today: new Date(),
  }
}

{
  "pi": {
    "$numberDouble": "3.14159"
  },
  "today": {
    "$date": {
      "$numberLong": "1652297239913"
    }
  }
}

Para retornar um valor como JSON padrão, chame JSON.stringify() no valor e, em seguida, retorne o resultado em string:

exports = function() {
  return JSON.stringify({
    pi: 3.14159,
    today: new Date(),
  })
}

"{\"pi\":3.14159,\"today\":\"2022-05-11T19:27:32.207Z\"}"

Definir uma função

Você pode criar e gerenciar funções em seu aplicação a partir da UI do Atlas ou importando a configuração da função e o código-fonte usando o App Services CLI ou o sistema do Github .

Você pode definir uma nova função do lado do servidor a partir da UI do Atlas :

Navegue até a Functions Página

Navegue até a página Triggers :
1. Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
2. Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
3. Na barra lateral, clique em Triggers sob o título Services.
  A página Acionadores é exibida.
Clique no link Linked App Service: Triggers.
Na barra lateral, clique em Functions sob o título Build.
Clique Create a Function. A aba Settings é exibida por padrão.

Nomear a nova função

Insira um nome para a função no campo Name . Esse nome deve ser exclusivo de todas as outras funções do aplicação.

Dica

Você pode definir funções dentro de pastas agrupadas. Os nomes de função são caminhos separados por barra, então, uma função denominada utils/add mapeia para functions/utils/add.js nos arquivos de configuração da aplicação.

Configurar autenticação de usuário

As funções no Atlas sempre são executadas no contexto de um usuário específico do aplicação ou como um usuário do sistema que ignora as regras. Para configurar o usuário de execução da Função, especifique o tipo de autenticação que o Atlas deve usar.

Observação

As funções para banco de dados e scheduled triggers sempre são executadas no contexto de um usuário do sistema.

Tipo de autenticação	Descrição
Autenticação de aplicativo (obsoleto)	Obsoleto. Esse tipo de autenticação configura uma função para ser executada no contexto do usuário do aplicativo existente que estava logado quando o aplicativo cliente chamou a função. Se a função foi chamada de outra função, ela herda o usuário de execução dessa função.
Sistema	Esse tipo de autenticação configura uma função para ser executada como um usuário do sistema que tem acesso total às APIs de Agregação e CRUD do MongoDB e não é afetada por nenhuma regra, função ou permissão.
ID de usuário (obsoleto)	Obsoleto. Este tipo de autenticação configura uma função para sempre executar como um usuário de aplicativo específico.
Roteiro	Esse tipo de autenticação configura uma função para ser executada como um usuário de aplicação específico determinado com base no resultado de uma função personalizada que você define. A função deve retornar uma string `id` de um usuário específico ou pode especificar um usuário do sistema retornando `{ "runAsSystem": true }`.

Configurar registros de funções

Por padrão, o Atlas inclui os argumentos que uma Função recebeu na entrada de registro para cada execução da Função.

Para evitar que o Atlas registre os argumentos, desative Log Function Arguments.

Especificar uma expressão de autorização

Você pode autorizar solicitações dinamicamente com base no conteúdo de cada solicitação definindo uma expressão Can Evaluate . O Atlas avalia a expressão sempre que a função é chamada. Se você não especificar uma expressão, o Atlas autorizará automaticamente todas as solicitações de entrada autenticadas.

A expressão pode expandir variáveis de expressão padrão , incluindo as expansões %%request e %%user .

A função Pode avaliar a entrada de expressão JSON na UI

clique para ampliar

Configurar o nível de privacidade da função

Por padrão, você pode chamar uma função de aplicativos de clientes, bem como outras funções no mesmo aplicativo. Você pode impedir que aplicativos de clientes vejam ou chamem uma função definindo Private como true.

Você ainda pode chamar uma função privada de expressão e outras funções, incluindo webhooks e gatilhos recebidos.

clique para ampliar

Escrever o código da função

Depois de criar e configurar a nova função, você pode escrever o código JavaScript que será executado quando você chamar a função.

Você pode escrever o código diretamente na UI do Atlas usando o editor de funções.

Na página Create Function , clique na aba Function Editor .
Adicione o código javascript à função. No mínimo, o código deve atribuir uma função a exports, como no seguinte exemplo:
```
exports = function() {
   return "Hello, world!";
};
```
Observação
Você pode usar os recursos JavaScript mais modernos (ES6+) em funções, incluindo async/await, desestruturação e literais de modelo.

Salvar a função

Clique em Save. Depois de salvar a função, você pode começar a usá-la imediatamente.

Autenticar um usuário do MongoDB Atlas

Use sua chave de API de administração do MongoDB Atlas para fazer login na App Services CLI:

appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"

Extraia os arquivos de configuração mais recentes do seu aplicativo

Execute o seguinte comando para obter uma cópia local dos seus arquivos de configuração:

appservices pull --remote=<App ID>

Por padrão, o comando extrai arquivos para o diretório de trabalho atual. Você pode especificar um caminho de diretório com a bandeira --local opcional.

Escreva o código fonte da função

As Atlas Functions executam funções ES6+ JavaScript padrão que você exporta de arquivos individuais.

Crie um arquivo .js no diretório functions ou em um subdiretório.
O nome do arquivo deve corresponder ao nome da função. Use barras no nome do arquivo para indicar um caminho de subdiretório.

touch functions/<FunctionName>.js

Dica

Você pode definir funções dentro de pastas aninhadas no diretório functions . Use barras no nome de uma função para indicar seu caminho de diretório. Por exemplo, uma função denominada utils/add mapeia para functions/utils/add.js.

Escreva o código-fonte da função no arquivo criado.

Por exemplo, a seguinte função hello.js retorna uma saudação para o nome fornecido:

functions/hello.js

exports = async function hello(...args) {
  // Write your function logic here! You can...
  // Import dependencies
  const assert = require("assert")
  assert(typeof args[0] === "string")
  // Use ES6+ syntax
  const sayHello = (name = "world") => {
    console.log(`Hello, ${name}.`)
  }
  // Return values back to clients or other functions
  return sayHello(args[0])
}

Observação

Você pode usar os recursos JavaScript mais modernos (ES6+) em funções, incluindo async/await, desestruturação e literais de modelo.

Configurar a função

No diretório functions do seu aplicação local, abra o arquivo config.json e adicione um objeto de configuração para sua nova função à array.

O objeto deve ter o seguinte formato:

{
  "name": "<Function Name>",
  "private": <Boolean>,
  "can_evaluate": { <JSON Expression> },
  "disable_arg_logs": <Boolean>,
  "run_as_system": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

Configure a autenticação do usuário:
As funções no Atlas sempre são executadas no contexto de um usuário específico do aplicação ou como um usuário do sistema que ignora as regras. Para configurar o usuário de execução da Função, especifique o tipo de autenticação que o Atlas deve usar.
Observação
As funções para banco de dados e scheduled triggers sempre são executadas no contexto de um usuário do sistema.
- Usuário do sistema: para executar a função como usuário do sistema, use a seguinte configuração:
  Configuração do usuário do sistema
  { "run_as_system": true, "run_as_user_id": "", "run_as_user_id_script_source": "" }
- Roteiro: para executar a função como um usuário retornado de outra função, use a seguinte configuração:
  Configuração do script
  { "run_as_system": false, "run_as_user_id": "", "run_as_user_id_script_source": "<Function Source Code>" }
- Usuário (obsoleto): para executar uma função como um usuário específico, use a seguinte configuração:
  Configuração da ID do usuário (obsoleto)
  { "run_as_system": false, "run_as_user_id": "<App Services User Id>", "run_as_user_id_script_source": "" }
Configure os registros de função:
Para incluir os argumentos que a função recebeu na entrada de registro para cada execução da função, defina disable_arg_logs como false.
Especifique uma expressão de autorização:
Você pode autorizar solicitações dinamicamente com base no conteúdo de cada solicitação definindo uma expressão Can Evaluate . O Atlas avalia a expressão sempre que a função é chamada. Se você não especificar uma expressão, o Atlas autorizará automaticamente todas as solicitações de entrada autenticadas.
A expressão pode expandir variáveis de expressão padrão , incluindo as expansões %%request e %%user .
Por exemplo, a expressão a seguir só autoriza solicitações recebidas se o endereço IP do remetente não estiver incluído na lista de endereços especificada:
Expressão de autorização de exemplo
```
{
   "%%request.remoteIPAddress": {
      "$nin": [
         "248.88.57.58",
         "19.241.23.116",
         "147.64.232.1"
      ]
   }
}
```
Configure o nível de privacidade:
Para evitar que aplicativos de cliente vejam ou chamem a função, defina private como true.

Distribua suas alterações:

Envie a configuração da função e o código-fonte para implementá-la em seu aplicativo. Você pode começar a usar a função imediatamente.

Execute o seguinte comando para implementar suas alterações:

appservices push

Chamar uma função

Você pode chamar uma função de outra função ou usando a App Services CLI.

Os exemplos nesta seção demonstram a chamada de uma função simples denominada sum que recebe dois argumentos, os adiciona e retorna o resultado:

functions/sum.js

// sum: adds two numbers
exports = function sum(a, b) {
  return a + b;
};

Chamar de uma função

Você pode chamar uma função a partir de outra função por meio da interface context.functions , que está disponível como uma variável global em qualquer função. A função chamada é executada no mesmo contexto da função que a chamou.

// difference: subtracts b from a using the sum function
exports = function difference(a, b) {
  return context.functions.execute("sum", a, -1 * b);
};

Chamada da App Services CLI

Você pode chamar uma função por meio da App Services CLI com o comando execução de função . O comando retorna o resultado da função como EJSON, bem como quaisquer mensagens de registro ou de erro.

appservices function run \
  --name=sum \
  --args=1 --args=2

Por padrão, as funções são executadas no contexto do sistema . Para chamar uma função no contexto de um usuário específico, inclua seu ID de usuário no argumento --user.

appservices function run \
  --name=sum \
  --args=1 --args=2 \
  --user=61a50d82532cbd0de95c7c89

Restrições

As funções são limitadas a 300 segundos de tempo de execução por solicitação, após os quais uma função atingirá o tempo limite e falhará.
As funções podem usar até 350 MB de memória a qualquer momento.
As funções estão limitadas a 1000 operações assíncronas.
As funções suportam as funcionalidades ES6+ mais comumente usadas e módulos integrados do Node.js. No entanto, algumas funcionalidades incomuns ou inadequadas para cargas de trabalho sem servidor não são suportadas. Para obter mais informações, consulte Suporte a JavaScript.
Uma função pode abrir um máximo de 25 soquetes usando o módulo interno dede rede.
As solicitações recebidas são limitadas a um tamanho máximo de 18 MB. Este limite se aplica ao tamanho total de todos os argumentos passados para a função.

Voltar

Enviar eventos de gatilho para o AWS EventBridge

Contexto

Quando usar as funções

Observação

Como escrever uma função

Definir uma função

Navegue até a .css-h15tq0{font-style:normal;font-weight:700;}Functions Página

Nomear a nova função

Dica

Configurar autenticação de usuário

Observação

Configurar registros de funções

Especificar uma expressão de autorização

Configurar o nível de privacidade da função

Escrever o código da função

Observação

Salvar a função

Autenticar um usuário do MongoDB Atlas

Extraia os arquivos de configuração mais recentes do seu aplicativo

Escreva o código fonte da função

Dica

Observação

Configurar a função

Observação

Distribua suas alterações:

Chamar uma função

Chamar de uma função

Chamada da App Services CLI

Restrições

Navegue até a Functions Página