使用函数

函数是无状态代码片段，用于执行由 HTTP 请求调用的任务。通过 IBM Code Engine 功能，您可以采用可扩展且无服务器的方式运行业务逻辑。 IBM Code Engine 功能提供优化的运行时环境，以支持低延迟和快速向外扩展方案。可以在包含特定 Node.js 或 Python 版本的受管运行时中编写函数代码。

代码束是表示函数代码的文件的集合。此代码束将注入到运行时容器中。代码束由 Code Engine 创建，并存储在容器注册表中或与函数直接插入。代码束不是开放式容器计划 (OCI) 标准容器映像。

准备工作

如果要使用 Code Engine 控制台，请转至 Code Engine 概述。
如果要使用 CLI，请设置 Code Engine CLI 环境。
规划并选择使代码作为 Code Engine 函数组件运行的方法。

不确定要创建哪种类型的 Code Engine 工作负载? 请参阅规划 Code Engine。

函数限制

不支持预订事件生产者。
不支持 Terraform。

如何使代码作为 Code Engine 函数组件运行?

无论您的代码是作为本地文件或 Git 存储库中的源存在，还是您的代码是位于公共或专用注册表中的现有代码束，Code Engine 都为您提供了作为函数运行代码的简化方法。

如果是从位于 Git 存储库中的源代码开始，那么可以选择指向源的位置，并且 Code Engine 负责从源构建代码束并使用单个操作创建函数。在此场景中，Code Engine 将代码上载到 IBM Cloud® Container Registry。要了解更多信息，请参阅根据存储库源代码创建函数。
如果是从本地工作站上的源代码开始，那么可以选择指向源的位置，并且 Code Engine 负责从源构建映像并使用 single CLI 命令创建函数。在此场景中，Code Engine 将代码上载到 IBM Cloud® Container Registry。要了解更多信息，请参阅使用 CLI 从本地源代码创建函数。
如果是从源代码开始，那么还可以以内联方式运行源代码。在此场景中，您将在创建函数时粘贴源代码。有关更多信息，请参阅使用内联代码创建函数。

创建并运行函数后，还可以使用上述方法中的任何来更新函数，而与您创建或先前更新函数的方式无关。

调用函数时会发生什么?

调用 (启动) 函数时，将使用配置的运行时容器和资源参数来初始化相应的函数实例。第一次初始化的过程称为 冷启动。

为了减少冷启动等待时间，Code Engine 通过使用特定 CPU 和内存配置预热特定运行时来优化调用。函数的预热组合包括 Node.js 18 和 Python 3.11 版本以及 Functions 的缺省 CPU 和内存组合，即 0.25 vCPU x 1 GB 内存。此外，该系统旨在改进已初始化的 Function 实例的复用。因此，函数实例在调用完成后保持活动状态，以允许后续调用，方法是复用同一实例并在上次调用完成时复用实例的状态。不保证复用函数实例。

能否使我的函数实例保持活动时间更长?

通过 Code Engine，您的函数会根据工作负载自动向上和向下扩展。使用缺省 CPU 和内存组合创建函数时，会将函数注入到“预热”容器中，该容器已优化使用。创建具有除缺省组合以外的 CPU 和内存组合的函数时，会将该函数注入到新容器中。缺省情况下，在函数完成后，此容器仅在短时间内保持活动状态。有关更多信息，请参阅函数的受支持 CPU 和内存组合。

您可以使用 CLI 中的 --scale-down-delay 选项或控制台中的 Scale-down delay 选项来更改容器保持活动的时间量。请注意，在使容器保持活动的同时，将减少任何后续运行函数的冷启动时间，还会针对定制函数容器存在的时间量对您进行计费。

请求和响应

使用 HTTP 协议调用函数。调用函数时，可以指定定制请求参数，定制请求主体和头以及 HTTP 方法。将请求参数作为输入参数提供给函数代码。函数代码可以设置从函数端点返回给调用者的响应主体，响应头和响应代码。

示例 1: 从函数生成 HTML 响应

以下示例说明如何从函数生成 HTML 响应。

  function main(params) {
      var msg = 'You did not tell me who you are.';
      if (params.name) {
          msg = `Hello, ${params.name}!`
       } else {
          msg = `Hello, FaaS on CodeEngine!`
      }
      return {
          headers: { 'Content-Type': 'text/html; charset=utf-8' },
          body: `<html><body><h3>${msg}</h3></body></html>`
       }
  }

  module.exports.main = main;

示例 2: 设置响应代码和响应头

您的函数可以设置特定的响应代码和头标志。以下示例说明如何设置响应代码和响应头以将重定向添加到其他 URL。

function main(params) {
    return {
        headers: { location: 'https://cloud.ibm.com/docs/codeengine' },
        statusCode: 302
    }
}

示例 3: 从函数生成纯文本响应

以下示例说明如何从函数生成纯文本响应。

function main(params) {
    var msg = 'You did not tell me who you are.';
    if (params.name !== "") {
        msg = `Hello, ${params.name}!`
    }
    return {
        headers: { 'Content-Type': 'text/plain;charset=utf-8' },
        body: `${msg}`
    }
}

错误处理和调试

函数调用可能会返回系统或应用程序错误。例如，系统错误指示函数代码未成功执行，而应用程序错误指示函数代码本身存在问题。

发生系统错误时，将返回类似于以下代码的 HTTP 响应代码。

HTTP 响应代码
代码	描述
409	未满足该功能所需的资源。
413	请求有效内容超过定义的最大值。
414	调用 URI 太长。
416	该函数生成的响应超过了定义的最大值。
422	功能代码无效，无法处理。详情请查看平台日志。
424	功能代码无法执行。请稍后重试。
429	您超出了资源配额，无法调度该功能。
431	请求头超过定义的最大值。
500	内部服务器错误。
502	网关错误。
503	功能当前不可用，请稍后再试。
507	存储空间不足，无法装入该功能。

如果 Code Engine 可以执行函数代码，那么它会使用下列其中一个状态码来响应调用。

状态码
代码	描述
200	已接受函数调用，将延迟执行该函数。
202	已接受函数调用，将异步执行该函数。
299	该函数超过了指定的或最大的运行时限制，并且已异常中止。

作为函数的开发者，您可以生成任何任意 HTTP 状态码，甚至可以生成先前列出的 HTTP 状态码。因此，响应头指示状态码是由函数代码生成的。

Code Engine 函数将以下响应头添加到函数调用响应。

状态码
代码	描述
`x-faas-actionstatus`	由函数程序逻辑设置的 HTTP 状态码。
`x-faas-activation-id`	用于标识函数调用的唯一标识。
`x-faas-result`	由运行时容器返回的 `success` 消息或短错误消息。
`x-faas-errormessage`	包含其他详细信息的长错误消息。
`x-faas-prewarmed`	一条消息，指示调用是冷调用还是函数在现有 (预热容器) 中运行。可能的值为 `false` 或 `true`。

函数数据输入/输出特征

要在 Code Engine中运行函数，代码必须实现具有以下特征的运行时合同。

必须可以从公共 Web 应用程序端点调用，以便可以将其嵌入网页，然后从任何Code Engine事件源、Web 浏览器或任何其他支持 HTTPS 的客户端。
必须实现 main 过程作为入口点。 main 过程可以接收 JSON 格式的数据结构形式的输入参数，并且可以返回输出参数，也可以返回 JSON 格式的数据结构形式的输出参数。
可以接收可选的子路径，以便该函数可以根据指定的路径实现不同的类型模板。函数的 main 过程接收路径作为 __ce_path 输入参数。
可以接收可选查询参数，这些参数可用于在运行时配置函数。函数的 main 过程在 JSON 格式的输入数据结构中以键/值对形式接收参数。
可以接收请求头，以便客户机代码可以指定可接受的编码。
可以接收可选的 content-type 请求头。
可以接收函数在运行时处理的可选请求有效内容 (主体)。根据所选请求内容类型，数据有效内容将以基本 64 位编码形式或作为 JSON 输入数据结构的一部分“展开”传递到函数的主入口点。 application/x-www-form-urlencoded 输入的键值对中的特殊字符是 percent-encoded 值。
可以定义随后返回到调用客户机的任意 HTTP 状态码 (可选)。
可以设置任意响应头，例如重定向位置，响应编码或 cookie 值。
可以返回具有所选二进制或非二进制编码的任意响应主体; 例如，application/octet-stream，application/json，text/*，image/* 或 audio/*。如果未设置 content-type 响应头，那么缺省为 text/plain。
支持以下请求内容类型: application/x-www-form-urlencoded (缺省值)，text/plain，application/json，application/octet-stream，image/* 和 audio/*
不支持 multipart/form-data 请求头。

Code Engine 函数的可视性选项

通过 Code Engine，您可以通过定义可用于接收请求的端点或系统域映射来确定函数的正确可视性级别。

每个函数都有一个内部系统域映射，同一Code Engine项目内的所有组件都能看到该映射，但项目外的组件则看不到。除了内部系统域映射外，您还选择使该函数对公用因特网或 IBM Cloud 专用网络可视。

对于公共或私人可见性，该功能在 HTTPS 端点上公开。有关使用的 TLS 证书的详细信息，请参阅 Code Engine项目的 TLS 证书。

您可以部署具有以下可视性级别的函数:

功能可见性
设置	描述
内部(项目)	具有此设置的函数可以从同一 Code Engine 项目中的组件接收请求。设置内部（项目）端点意味着无法从公共互联网访问您的功能，只能从运行在同一Code Engine项目中的其他Code Engine组件进行网络访问。此端点始终处于启用状态。重要的：函数不能使用内部路由调用另一个作业或应用程序。
public	具有此设置的函数将向因特网和 Code Engine 项目公开。设置公共端点意味着您的函数可以从公共因特网或从 Code Engine 项目中的组件接收请求。此设置为缺省设置。
private	具有此设置的函数将向 IBM Cloud 专用网络和 Code Engine 项目公开。设置专用端点意味着无法从公用因特网访问您的功能，只能通过使用在同一项目中运行的虚拟专用端点 (VPE) 或 Code Engine 组件从其他 IBM Cloud 服务进行网络访问。

您可以在创建和部署功能或更新功能时，通过控制台或 CLI 设置功能可视性的端点设置。

使用内部端点部署函数

您可以设置要使用内部 (项目) 端点进行部署的函数的端点可视性。设置内部 (项目) 端点时，无法从公用因特网访问您的函数，只能从在同一 Code Engine 项目中运行的其他 Code Engine 组件进行网络访问。此端点始终处于启用状态。功能仍可通过共享组件进行访问，因此需要进行保护。

例如，如果解决方案由项目中的多个功能组成，那么可以设置解决方案，以便只有其中一个功能可从因特网看到，以便它处理入局流量。此面向公共的函数可以将工作委派给解决方案中的其他函数，以便这些函数不需要从因特网可见。

通过 CLI，设置函数的端点可视性，以便使用 function create 或 function update 命令上的 --visibility=project 选项随项目端点一起部署该函数。您可以使用 function get 命令获取反映端点定义的函数的可用 URL。

在控制台中，通过在创建函数时使用端点设置来设置函数的端点可视性。部署函数后，可以在“函数”页面上的 域映射 选项卡上查看和修改这些系统域映射设置。

具有此设置的函数可以从同一 Code Engine 项目中的组件接收请求。但是，函数不能使用内部路由调用另一个作业或应用程序。

使用公共端点部署函数

在部署函数时，缺省情况下，该函数可以从公用因特网或同一 Code Engine 项目中的组件接收请求。在这种情况下，将使用公共端点来部署函数。

使用专用端点部署函数

您可以设置要使用专用端点进行部署的函数的端点可视性。为功能设置专用端点时，无法从公用因特网访问该端点，只能从在同一项目 (cluster-local) 中运行的虚拟专用端点 (VPE) 或 Code Engine 组件中的其他 IBM Cloud 服务进行网络访问。

例如，如果解决方案由在您自己的虚拟专用端点中的 IBM Cloud Kubernetes Service Kubernetes 集群上运行的组件组成，并且您想要从 IBM Cloud 专用网络访问 Code Engine 函数，那么可以将该函数的可视性设置为 private。当该功能的可视性设置为 private 时，无法通过公共因特网访问该功能。该功能仍可从项目中的其他功能访问。

您可以使用专用端点创建函数，以便仅通过 IBM Cloud 专用网络公开该函数，而不向外部因特网公开该函数。该功能仍可通过内部网络中的共享组件访问，需要保护功能端点。

通过 CLI，设置函数的端点可视性，以便使用 function create 或 function update 命令上的 --visibility=private 选项随专用端点一起部署该函数。您可以使用 function get 命令获取反映端点定义的函数的可用 URL。

有关通过专用网络进行连接的更多信息，请参阅将虚拟专用端点用于 Code Engine。

用于创建函数的选项

了解创建函数时可以指定的选项。请注意，选项可能因控制台和 CLI 而异。

内存和 CPU

部署函数时，可以指定函数可以使用的内存量和 CPU。根据您的功能是计算密集型，内存密集型还是平衡型，这些数量可能有所不同。

默认情况下，为您的函数分配 4 G 内存和 1.0 vCPU。有关其他受支持的内存和 CPU 组合的更多信息，请参阅函数的受支持内存和 CPU 组合。

使用环境变量创建和运行函数

您可以将环境变量定义为可在运行时由函数使用的“键/值”对，并将其设置为“键/值”对。

您可以在创建函数时定义环境变量，也可以在使用 CLI 更新现有函数时定义环境变量。

有关定义环境变量的更多信息，请参阅使用环境变量。

Code Engine 会自动将某些环境变量注入到函数中。有关自动注入的环境变量的更多信息，请参阅自动注入的环境变量。

使用私钥和 ConfigMap 时创建和运行函数

在 Code Engine中，可以使用环境变量来使用私钥和配置映射。

私钥和配置映射都是键/值对。当映射到环境变量时，将设置 NAME=VALUE 关系，以使环境变量的名称对应于这些映射中每个条目的“键”，并且环境变量的值是该键的“值”。

您的函数可以使用环境变量来完全引用 configmap (或私钥) 或引用 configmap (或私钥) 中的各个密钥。

有关更多信息，请参阅使用环境变量引用私钥和使用环境变量引用配置映射。

函数配额的注意事项

使用应用程序，函数和批处理作业时，这些资源将在 Code Engine 项目的上下文中运行。资源配额是根据每个项目定义的，限制适用于应用程序，功能和批处理作业。

有关 Code Engine 限制的更多信息，请参阅 Code Engine。

后续步骤

既然您熟悉使用 Code Engine 函数的关键概念，是否准备好创建和使用函数? 请参阅以下主题。

有关使用函数的更多信息，请参阅以下主题。