上下文

Overview

Atlas Function 可以访问全局 context 对象，该对象包含传入请求的元数据，并提供对在 App Services App 中配置的组件和服务的访问权限。

context 对象公开以下接口：

获取应用元数据context.app ()

context.app 对象包含有关包含该函数的应用的元数据。

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

context.app.id

包含该函数的应用的唯一内部 ID。

例子

"60c8e59866b0c33d14ee634a"

context.app.clientAppId

包含该函数的应用程序的唯一客户端应用程序 ID。

例子

"myapp-abcde"

context.app.name

包含该函数的应用的名称。

例子

"myapp"

context.app.projectId

包含该应用的 Atlas 项目的 ID。

例子

"5e1ec444970199272441a214"

context.app.deployment

描述应用的部署模式和地区的对象。

例子

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

context.app.lastDeployed

上次部署 Atlas App 的日期和时间已格式化为 ISODate 字符串。

例子

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

context.app.hostingUri

如果启用了静态托管，则此值为托管资产的基本URL 。 （静态托管已弃用。 了解详情）

例子

"myapp-abcde.mongodbstitch.com"

调用函数context.functions ()

您可以通过 context.functions 接口调用应用程序中的任何函数。

context.functions.execute()

调用特定函数并返回结果。

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

Parameter	类型	说明
functionName	字符串	函数的名称。
args...	混合	要传递给函数的参数的可变列表。每个函数参数都映射到一个单独的、以逗号分隔的参数。

例子

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

检查应用环境context.environment ()

您可以通过 context.environment 接口访问有关应用的当前环境配置的信息并访问特定于环境的值。

context.environment.tag

以字符串表示的应用当前环境的名称。

Possible values:

• ""

• "development"

• "testing"

• "qa"

• "production"

例子

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
};

连接到MongoDB数据源或第三方服务 (context.services )

您可以通过 context.services 接口访问关联的 MongoDB Atlas 集群或联合数据源的客户端。您还可以访问第三方服务，但此功能已弃用。

context.services.get()

获取指定服务的服务客户端，如果不存在此类服务，则获取 undefined。

context.services.get(serviceName)

Parameter	类型	说明
serviceName	字符串	关联集群、联合数据库实例或服务的名称。 提示 MongoDB 服务名称 应用程序创建的链接数据源使用以下默认名称之一： 集群： mongodb-atlas 联合数据库实例： mongodb-datafederation

例子

在 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 },
  })
};

[已弃用] 调用第三方服务操作

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)
  }
};

获取请求元数据context.request ()

您可以通过 context.request 接口访问传入请求的相关信息。

context.request

一个对象，其中包含有关导致函数执行的 HTTP 请求的信息。

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

字段	类型	说明
remoteIPAddress	字符串	发出函数请求的客户端 IP 地址。
requestHeaders	对象	一个对象，其中每个字段都映射到一种 HTTP标头 包含在导致函数执行的请求中。每个字段的值都是一个字符串大量，其中每个string都映射到请求中包含的指定类型的标头。 例子 { "requestHeaders": { "Content-Type": ["application/json"], "Cookie": [ "someCookie=someValue", "anotherCookie=anotherValue" ] } }
webhookUrl	字符串	可选。HTTPS 端点函数中端点的路由。
httpMethod	字符串	可选。 在 HTTPS 端点 函数中， HTTP方法 调用端点的请求的 ID。
rawQueryString	字符串	查询string 附加到传入的HTTP 请求。所有查询参数的显示顺序均与指定顺序相同。 重要 App Services 会删除密码参数 出于安全原因，Atlas App Services 会自动删除键为 secret 的任何查询字符串键/值对。例如，如果传入请求具有查询字符串 ?secret=hello&someParam=42，则该请求的 rawQueryString 为 "someParam=42"。
httpReferrer	字符串	可选。从中发送请求的页面的 URL。 该值派生自HTTP 标头 。如果请求不包含Referer标头，则此值为undefined 。
httpUserAgent	字符串	可选。标识请求来源的特征信息，例如软件供应商、操作系统或应用程序类型。 该值派生自 HTTP User-Agent 标头 。如果请求不包含User-Agent标头，则此值为undefined 。

例子

以下 context.request 文档反映了在 macOS High Sierra 上使用 Chrome 73 浏览的用户从 https://myapp.example.com/ 发出的函数调用：

exports = function() {
  return context.request
}

隐藏输出

{
  "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"
    ]
  }
}

获取用户数据context.user ()

您可以访问有关使用 context.user 接口调用函数的应用程序或系统用户的信息。

context.user

调用函数的认证用户的用户对象。

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

字段	类型	说明
id	字符串	ObjectId 的字符串表示形式，用于唯一标识用户。
type	字符串	用户的类型。可以有以下几种类型： 类型 说明 “normal” 用户是通过 API 密钥提供程序以外的身份验证提供程序登录的应用程序用户。 “server” 用户是使用任何类型的 App Services API 密钥登录的服务器进程。 “system” 用户是绕过所有规则的系统用户。
data	文档	包含描述用户的元数据的文档。此字段合并与用户相关联的所有 identities 的数据，因此确切的字段名称和值取决于用户使用哪些身份验证提供程序进行身份验证。 注意 系统函数没有用户数据 在系统函数中， user.data对象为空。 使用context.runningAsSystem()测试函数是否以系统用户身份运行。
custom_data	文档	来自应用程序自定义用户数据集合的文档，用于指定用户 ID。您可以使用自定义用户数据集合来存储有关应用程序用户的任意数据。如果设置 name 字段，App Services 会使用返回值 name 填充 username 元数据字段。每当用户刷新其访问令牌（例如登录时），App Services 都会自动获取数据的新副本。底层数据是普通的 MongoDB 文档，因此您可以通过 MongoDB Atlas 服务使用标准 CRUD 操作来定义和修改用户的自定义数据。 注意 避免存储大型自定义用户数据 自定义用户数据限制为 16MB，即 MongoDB 文档的最大大小。为避免达到此限制，请考虑在每个自定义用户数据文档中存储小型且相对静态的用户数据，例如用户的首选语言或其头像图像的 URL。对于大型、无界限或频繁更新的数据，请考虑仅在自定义用户文档中存储对数据的引用，或存储带有对用户 ID 的引用的数据，而不是存储在自定义用户文档中。
identities	阵列	与用户关联的身份验证提供者身份列表。当用户首次使用特定提供商登录时，App Services 会将用户与身份对象关联起来，该身份对象包含唯一标识符以及来自提供商的有关用户的其他元数据。对于后续登录，App Services 会刷新现有身份数据，但不会创建新身份。身份对象具有以下形式： { "id": "<Unique ID>", "provider_type": "<Provider Name>", "data": { "<Metadata Field>": <Value>, ... } } 字段名称 说明 id 提供商生成的唯一标识此身份的字符串 provider_type 与此身份关联的身份验证提供者的类型。 data 身份验证提供程序中描述用户的附加元数据。确切的字段名称和值将根据用户登录所使用的身份验证提供程序而异。有关特定于提供程序的用户身份数据分类，请参阅用户元数据。

例子

以下 context.user 文档反映了与单个用户 API 密钥关联的电子邮件/密码用户。

exports = function() {
  return context.user
}

隐藏输出

{
  "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()

如果该函数以系统用户身份运行，则计算结果为布尔值true ，否则计算结果为false 。

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.
  }
}

引用值context.values ()

您可以使用 context.values 接口在函数中访问应用的静态值。

context.values.get(valueName)

获取与提供的值名称或 undefined 关联的数据（如果不存在此类值）。此数据可以是纯文本 JSON 值，也可以是通过值公开的密钥。

Parameter	类型	说明
valueName	字符串	值的名称。

例子

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"
};

发送HTTP请求context.http ()

您可以通过具有 context.http 接口的内置客户端发送 HTTPS 请求。

context.http.get()

发送 HTTP GET 请求到指定的 URL。请参阅http.get()以获取详细的参考信息，包括参数定义和返回类型。

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()

发送 HTTP POST 请求到指定的URL。请参阅http.post()以获取详细的参考信息，包括参数定义和返回类型。

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()

发送 HTTP PUT 请求到指定的URL。请参阅http.put()以获取详细的参考信息，包括参数定义和返回类型。

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()

发送 HTTP PATCH 请求到指定的URL。请参阅http.patch()以获取详细的参考信息，包括参数定义和返回类型。

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()

发送 HTTP DELETE 请求到指定的URL。请参阅http.delete()以获取详细的参考信息，包括参数定义和返回类型。

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

context.http.head()

发送 HTTP HEAD 请求到指定的URL。请参阅http.head()以获取详细的参考信息，包括参数定义和返回类型。

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());
};