Contexto

Visão geral

As funções do Atlas têm acesso a um objeto global context que contém metadados para as solicitações de entrada e fornece acesso a componentes e serviços que você configurou em seu Atlas App Services.

O objeto context expõe as seguintes interfaces:

Obter metadados do app (context.app)

O objeto context.app contém metadados sobre o aplicativo que contém a função.

{
  "id": string,
  "clientAppId": string,
  "name": string,
  "projectId": string,
  "deployment": {
    "model": string,
    "providerRegion": string,
  },
  "lastDeployed": string,
  "hostingUri": string,
}

context.app.id

O ID interno exclusivo do aplicativo que contém a função.

Exemplo

"60c8e59866b0c33d14ee634a"

context.app.clientAppId

O ID exclusivo do aplicativo do cliente para o aplicativo que contém a função.

Exemplo

"myapp-abcde"

context.app.name

O nome da aplicação que contém a função.

Exemplo

"myapp"

context.app.projectId

O ID do Projeto Atlas que contém o aplicativo.

Exemplo

"5e1ec444970199272441a214"

context.app.deployment

Um objeto que descreve o modelo e região de implantação do aplicativo.

Exemplo

{
  "model": "LOCAL",
  "providerRegion": "aws-us-east-1"
}

context.app.lastDeployed

A data e hora em que a aplicação Atlas foi implantada pela última vez, formatada como uma string ISODate.

Exemplo

"2022-10-31T12:00:00.000Z"

context.app.hostingUri

Se o hospedagem estática estiver habilitado, esse valor será a URL base dos ativos hospedados. (A hospedagem estática está obsoleta. Saiba mais)

Exemplo

"myapp-abcde.mongodbstitch.com"

Chamar uma função (context.functions)

Você pode chamar qualquer função em seu aplicativo através da interface do context.functions.

context.functions.execute()

Chama uma função específica e retorna o resultado.

context.functions.execute(functionName, ...args)

Parâmetro	Tipo	Descrição
functionName	string	O nome da função.
args...	misto	Uma lista variada de argumentos para passar para a função. Cada parâmetro de função é mapeado para um argumento independente separado por vírgula.

Exemplo

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

Verifique o ambiente do aplicativo (context.environment)

Você pode acessar informações sobre a configuração atual do ambiente do seu aplicativo e acessar valores específicos do ambiente por meio da interface context.environment .

context.environment.tag

O nome do ambiente atual do aplicativo como uma string.

Possible values:

• ""

• "development"

• "testing"

• "qa"

• "production"

Exemplo

exports = async function() {
  switch(context.environment.tag) {
    case "": {
      return "There is no current environment"
    }
    case "development": {
      return "The current environment is development"
    }
    case "testing": {
      return "The current environment is testing"
    }
    case "qa": {
      return "The current environment is qa"
    }
    case "production": {
      return "The current environment is production"
    }
  }
};

exports = async function() {
  const baseUrl = context.environment.values.baseUrl
};

Conecte-se a uma fonte de dados MongoDB ou serviço de terceiroscontext.services()

Você pode acessar um cliente para um cluster MongoDB Atlas vinculado ou fonte de dados federada por meio da interface context.services. Você também pode acessar serviços de terceiros, embora essa funcionalidade seja obsoleta.

context.services.get()

Obtém um cliente de serviço para o serviço especificado ou undefined se não existir tal serviço.

context.services.get(serviceName)

Parâmetro	Tipo	Descrição
serviceName	string	O nome do cluster vinculado, instância do banco de dados federado ou serviço. Dica Nomes de serviço MongoDB As fontes de dados vinculadas criadas pelo seu aplicativo usam um dos seguintes nomes padrão: Cluster: mongodb-atlas Instância do banco de dados federado: mongodb-datafederation

Exemplo

Ler e gravar dados no MongoDB Atlas

exports = async function() {
  // Get the cluster's data source client
  const mdb = context.services.get("mongodb-atlas");
  // Reference a specific database/collection
  const db = mdb.db("myApp");
  const collection = db.collection("myCollection");
  // Run a MongoDB query
  return await collection.find({
    name: "Rupert",
    age: { $lt: 50 },
  })
};

Chamar ações de serviço de terceiros

exports = async function() {
  // Instantiate a service client for the HTTP Service named "myHttpService"
  const http = context.services.get("myHttpService");
  // Call the HTTP service's get() action
  try {
    const response = await http.get({ url: "https://www.mongodb.com" });
    return response.body.text()
  } catch(err) {
    // You might get an error if:
    // - you passed invalid arguments
    // - the service's rules prevent the action
    console.error(err)
  }
};

Obter metadados da solicitaçãocontext.request()

Você pode acessar informações sobre a solicitação recebida com a interface context.request.

context.request

Um objeto que contém informações sobre a requisição HTTP que causou a execução da função.

{
   "remoteIPAddress": <string>,
   "requestHeaders": <object>,
   "webhookUrl": <string>,
   "httpMethod": <string>,
   "rawQueryString": <string>,
   "httpReferrer": <string>,
   "httpUserAgent": <string>,
   "service": <string>,
   "action": <string>
}

Campo	Tipo	Descrição
remoteIPAddress	string	O endereço IP do cliente que emitiu a solicitação de função.
requestHeaders	objeto	Um objeto onde cada campo mapeia para um tipo de Cabeçalho HTTP que foi incluído na solicitação que fez com que a função fosse executada. O valor de cada campo é uma matriz de cadeias de caracteres em que cada cadeia de caracteres mapeia para um cabeçalho do tipo especificado que foi incluído na solicitação. Exemplo { "requestHeaders": { "Content-Type": ["application/json"], "Cookie": [ "someCookie=someValue", "anotherCookie=anotherValue" ] } }
webhookUrl	string	Opcional. Nas funções de ponto de conexão HTTPS, a rota do ponto de conexão.
httpMethod	string	Opcional. Em funções de ponto de conexão HTTPS, o método HTTP da solicitação que chamou o ponto de conexão.
rawQueryString	string	A string da query anexada à solicitação HTTP de entrada. Todos os parâmetros de query aparecem na mesma ordem em que foram especificados. Importante App Services remove o parâmetro secreto Por motivos de segurança, o Atlas App Services remove automaticamente qualquer string de query da chave/par de valor em que a chave for secret. Por exemplo, se uma solicitação recebida tiver a string de query ?secret=hello&someParam=42, o rawQueryString para essa solicitação será "someParam=42".
httpReferrer	string	Opcional. O URL da página da qual a solicitação foi enviada. Esse valor é derivado do Cabeçalho HTTP. Se a solicitação não incluiu um cabeçalho Referer, então é undefined.
httpUserAgent	string	Opcional. Informações características que identificam a origem da solicitação, como o fornecedor do software, o sistema operacional ou o tipo de aplicativo. Esse valor é derivado do header HTTP usuário-agente. Se a solicitação não incluiu um cabeçalho User-Agent, então é undefined.

Exemplo

O seguinte documento context.request reflete uma chamada de função emitida de https://myapp.example.com/ por um usuário navegando com o Chrome 73 no macOS High Sierra:

exports = function() {
  return context.request
}

OCULTAR SAÍDA

{
  "remoteIPAddress": "54.173.82.137",
  "httpReferrer": "https://myapp.example.com/",
  "httpUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36",
  "rawQueryString": "?someParam=foo&anotherParam=42",
  "requestHeaders": {
    "Content-Type": ["application/json"],
    "Cookie": [
      "someCookie=someValue",
      "anotherCookie=anotherValue"
    ]
  }
}

Obter dados do usuário (context.user)

Você pode acessar informações sobre o aplicativo ou usuário do sistema que chamou uma função com a interface context.user.

context.user

O objeto do usuário do usuário autenticado que chamou a função.

{
    "id": <string>,
    "type": <string>,
    "data": <document>,
    "identities": <array>
}

Campo	Tipo	Descrição
id	string	Uma representação de string do ObjectId que identifica exclusivamente o usuário.
type	string	O tipo do usuário. Os seguintes tipos são possíveis: Tipo Descrição "normal" O usuário é um usuário de aplicativo conectado por meio de um fornecedor de autenticação que não seja o fornecedor de chave de API. "servidor" O usuário é um processo de servidor conectado com qualquer tipo de chave API do App Services. "sistema" O usuário é o usuário do sistema que ignora todas as regras.
data	documento	Um documento que contém metadados que descrevem o usuário. Esse campo combina os dados de todos os identities associados ao usuário, portanto, os nomes e valores exatos dos campos dependem de quais fornecedores de autenticação o usuário autenticou. Observação As funções do sistema não têm dados de usuário Nas funções do sistema, o objeto user.data está vazio. Use context.runningAsSystem() para testar se a função está sendo executada como um usuário do sistema.
custom_data	documento	Um documento da collection de dados de usuário customizada do seu aplicativo que especifica o ID do usuário. Você pode usar a collection de dados de usuário customizada para armazenar dados arbitrários sobre os usuários do seu aplicativo. Se você definir o campo name, o App Services preencherá o campo de metadados username com o valor de retorno de name. O App Services busca automaticamente uma nova cópia dos dados sempre que um usuário atualiza seu token de acesso, como quando ele faz login. Os dados subjacentes são um documento normal do MongoDB, portanto, você pode usar operações CRUD padrão por meio do Serviço MongoDB Atlas para definir e modificar os dados personalizados do usuário. Observação Evite o armazenar grandes volumes de dados de usuários personalizados. O usuário de dados personalizado é limitado a 16MB, o tamanho máximo de um documento do MongoDB. Para evitar atingir esse limite, considere armazenando dados de usuário pequenos e relativamente estáticos em cada personalizado documento de dados do usuário, como o idioma preferido do usuário ou a URL da imagem do avatar. Para dados que são grandes, ilimitado ou atualizado com frequência, considere armazenar apenas um referência aos dados no documento do usuário personalizado ou no armazenamento os dados com uma referência ao ID do usuário em vez de no Documento de usuário personalizado.
identities	array	Uma lista de identidades do fornecedor de autenticação associadas ao usuário. Quando um usuário se conecta pela primeira vez com um provedor específico, o App Services associa o usuário a um objeto de identidade que contém um identificador exclusivo e metadados adicionais sobre o usuário do fornecedor. Para logins subsequentes, o App Services atualiza os dados de identidade existentes, mas não cria uma nova identidade. Os objetos de identidade têm o seguinte formulário: { "id": "<Unique ID>", "provider_type": "<Provider Name>", "data": { "<Metadata Field>": <Value>, ... } } Nome do campo Descrição id Uma string gerada pelo fornecedor que identifica exclusivamente esta identidade provider_type O tipo de fornecedor de autenticação associado a esta identidade. data Metadados adicionais do fornecedor de autenticação que descrevem o usuário. Os nomes e valores exatos dos campos variarão dependendo de quais fornecedores de autenticação o usuário usou para se conectar. Para obter uma análise específica do fornecedor dos dados de identidade do usuário, consulte Metadados do usuário.

Exemplo

O documento context.user a seguir reflete um usuário de email/senha associado a uma única chave de API de usuário.

exports = function() {
  return context.user
}

OCULTAR SAÍDA

{
  "id": "5cbf68583025b12840664682",
  "type": "normal",
  "data": {
    "email": "someone@example.com",
    "name": "myApiKeyName"
  },
  "identities": [
    {
      "id": "5cbf68583025b12880667681",
      "provider_type": "local-userpass"
    },
    {
      "id": "5cbf6c6a922616045a388c71",
      "provider_type": "api-key"
    }
  ]
}

context.runningAsSystem()

Avalia para um booleano que é true se a função estiver sendo executada como um usuário do sistema e false de outra forma.

exports = function() {
  const isSystemUser = context.runningAsSystem()
  if(isSystemUser) {
    // Do some work that bypasses rules
  } else {
    // Do some work in the context of the user that called the function.
  }
}

Referenciar um valor (context.values)

Você pode acessar os valores estáticos do seu aplicativo em uma função com a interface do context.values.

context.values.get(valueName)

Obtém os dados associados ao nome do valor fornecido ou undefined se não existir tal valor. Esses dados são um valor JSON de texto sem formatação ou um segredo exposto por meio de um valor.

Parâmetro	Tipo	Descrição
valueName	string	O nome do valor.

Exemplo

exports = function() {
  // Get a global value (or `undefined` if no value has the specified name)
  const theme = context.values.get("theme");
  console.log(theme.colors)     // Output: { red: "#ee1111", blue: "#1111ee" }
  console.log(theme.colors.red) // Output: "#ee1111"
};

Enviar uma solicitação HTTP (context.http)

Você pode enviar solicitações HTTPS por meio de um cliente integrado com a interface context.http.

context.http.get()

Envia uma solicitação HTTP GET para a URL especificada. Consulte http.get() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.get({ url: "https://www.example.com/users" })
  // The response body is a BSON.Binary object. Parse it and return.
  return EJSON.parse(response.body.text());
};

context.http.post()

Envia uma solicitação HTTP POST para a URL especificada. Consulte http.post() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.post({
    url: "https://www.example.com/messages",
    body: { msg: "This is in the body of a POST request!" },
    encodeBodyAsJSON: true
  })
  // The response body is a BSON.Binary object. Parse it and return.
  return EJSON.parse(response.body.text());
};

context.http.put()

Envia uma solicitação HTTP PUT para o URL especificado. Consulte http.put() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.put({
    url: "https://www.example.com/messages",
    body: { msg: "This is in the body of a PUT request!" },
    encodeBodyAsJSON: true
  })
  // The response body is a BSON.Binary object. Parse it and return.
  return EJSON.parse(response.body.text());
};

context.http.patch()

Envia uma solicitação HTTP PATCH para a URL especificada. Consulte http.patch() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.patch({
    url: "https://www.example.com/diff.txt",
    body: { msg: "This is in the body of a PATCH request!" },
    encodeBodyAsJSON: true
  })
  // The response body is a BSON.Binary object. Parse it and return.
  return EJSON.parse(response.body.text());
};

context.http.delete()

Envia uma solicitação HTTP DELETE para a URL especificada. Consulte http.delete() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.delete({ url: "https://www.example.com/user/8675309" })
};

context.http.head()

Envia uma solicitação HTTP HEAD para a URL especificada. Consulte http.head() para informações de referência detalhadas, incluindo definições de parâmetros e tipos de retorno.

exports = async function() {
  const response = await context.http.head({ url: "https://www.example.com/users" })
  // The response body is a BSON.Binary object. Parse it and return.
  EJSON.parse(response.body.text());
};