使用函數

函數是一種無狀態的程式碼片段，當 HTTP 請求呼叫它時，它就會執行任務。透過 IBM Code Engine 函式，您可以以可擴充和無伺服器的方式執行業務邏輯。 IBM Code Engine 功能提供最佳化的執行環境，以支援低延遲和快速擴充方案。您的函式代碼可以在包含特定 Node.js 或 Python 版本的受管運行時中寫入。

程式碼組合是代表函數碼的檔案集合。這個程式碼組合會注入執行時期儲存器中。您的程式碼組合由 Code Engine 建立，並儲存在儲存器登錄中或與函數一起列入。程式碼組合不是 Open Container Initiative (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 會負責從來源建置映像檔，並使用單一 CLI 指令來建立函數。在此實務範例中，Code Engine 會將您的程式碼上傳至 IBM Cloud® Container Registry。若要進一步瞭解，請參閱使用 CLI 從本端原始碼建立函數。
如果您是從原始碼開始，也可以在行內執行原始碼。在此實務範例中，您會在建立函數時貼上原始碼。如需相關資訊，請參閱使用行內程式碼建立函數。

建立並執行函數之後，您也可以使用上述任何方式來更新函數，而與您建立或先前更新函數的方式無關。

當我呼叫我的函數時，會發生什麼情況?

當呼叫 (啟動) 函數時，會使用已配置的執行時期儲存器和資源參數來起始設定對應的函數實例。第一次起始設定的處理程序稱為 冷啟動。

為了減少冷啟動延遲，Code Engine 會透過使用特定 CPU 和記憶體配置預先預熱特定執行時期來最佳化呼叫。函式的預溫組合包括 Node.js 和 Python 運行時間，以及函式的預設 CPU 和記憶體組合，即 0.25 vCPU x 1 GB 記憶體。此外，系統設計為改良已起始設定之「函數」實例的重複使用。因此，在呼叫完成之後，「函數」實例會保持作用中，以容許後續呼叫，方法是重複使用相同的實例，並在前次呼叫完成時重複使用實例的狀態。不保證重複使用「函數」實例。

我可以讓函數實例更長時間保持作用中嗎?

使用 Code Engine，您的函數會根據工作量自動擴增及縮減。當您使用預設 CPU 和記憶體組合來建立函數時，會將您的函數注入「預先預熱」的儲存器中，該儲存器已最佳化可供使用。當您建立具有非預設組合的 CPU 及記憶體組合的函數時，會將您的函數注入新的容器中。依預設，在功能完成之後，此儲存器只會短暫保持作用中。如需相關資訊，請參閱函數支援的 CPU 和記憶體組合。

您可以使用 CLI 中的 --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 狀態碼，甚至是之前列出的那些。因此，回應標頭指出狀態碼是由函數碼所產生。

Code Engine 函數會將下列回應標頭新增至函數呼叫回應。

狀態碼
代碼	說明
`x-faas-actionstatus`	由功能程式邏輯設定的 HTTP 狀態代碼。
`x-faas-activation-id`	用來識別函數呼叫的唯一 ID。
`x-faas-result`	執行時期儲存器傳回的 `success` 訊息或簡短錯誤訊息。
`x-faas-errormessage`	含有其他詳細資料的長錯誤訊息。
`x-faas-prewarmed`	指出呼叫是否冷或函數是否在現有 (預先暖儲存器) 中執行的訊息。可能的值為 `false` 或 `true`。

函數資料輸入/輸出性質

若要在 Code Engine中執行您的函數，您的程式碼必須實作具有下列性質的執行時期合約。

必須可從公共 Web 應用程式端點呼叫，因此可以將其嵌入網頁，然後從任何 Code Engine Eventing 來源、Web 瀏覽器或任何其他 HTTPS 功能的用戶端調用。
必須實作 main 程序作為進入點。 main 程序可以接收 JSON 格式化資料結構形式的輸入參數，也可以傳回 JSON 格式化資料結構形式的輸出參數。
可以接收選用的子路徑，以便函數可以根據指定的路徑實作不同的特性。函數的 main 程序會接收路徑作為 __ce_path 輸入參數。
可以接收選用查詢參數，可用來在執行時期配置函數。函數的 main 程序會接收參數作為 JSON 格式化輸入資料結構內的鍵值組。
可以接收要求標頭，以便用戶端程式碼可以指定接受的編碼。
可以接收選用內容類型要求標頭。
可以接收選用要求有效負載 (內文)，函數會在執行時期處理該要求有效負載。視選取的要求內容類型而定，資料有效負載會以 Base 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 專案。設定專用端點表示無法從公用網際網路存取您的函數，且只能透過在相同專案中執行的其他 IBM Cloud 服務使用「虛擬專用端點 (VPE)」或 Code Engine 元件進行網路存取。

您可以在建立及部署或更新函數時，從主控台或使用 CLI 來設定端點設定，以瞭解函數的可見性。

使用內部端點部署函數

您可以設定要使用內部 (專案) 端點部署之函數的端點可見性。當您設定內部 (專案) 端點時，無法從公用網際網路存取您的函數，且只能從相同 Code Engine 專案內執行的其他 Code Engine 元件進行網路存取。一律啟用此端點。功能仍可透過共用元件存取，因此需要保護。

例如，如果您的解決方案包含專案內的數個函數，則您可以設定解決方案，以便從網際網路只能看到其中一個函數，以便它處理送入的資料流量。此面向公用的函數可以將工作委派給解決方案中的其他函數，以便它們不需要從網際網路中可見。

使用 CLI，透過在 function create 或 function update 指令上使用 --visibility=project 選項，設定函數的端點可見性，讓它與專案端點一起部署。您可以使用 function get 指令取得函數的可用 URL，以反映您的端點定義。

在主控台中，當您建立函數時，請使用端點設定來設定函數的端點可見性。部署函數之後，您可以在「函數」頁面上的 網域對映 標籤上檢視及修改這些系統網域對映設定。

具有此設定的函數可以從相同 Code Engine 專案中的元件接收要求。但是，函數無法使用內部路由呼叫另一個作業或應用程式。

使用公用端點部署函數

當您部署函數時，依預設，函數可以接收來自公用網際網路或來自相同 Code Engine 專案內元件的要求。在此情況下，會使用公用端點來部署函數。

使用專用端點部署函數

您可以設定函數的端點可見性，以使用專用端點進行部署。當您為函數設定專用端點時，無法從公用網際網路存取它，且只能從虛擬專用端點 (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，以反映您的端點定義。

如需透過專用網路連接的相關資訊，請參閱 Using Virtual Private Endpoints with Code Engine。

用於建立函數的選項

瞭解您在建立函數時可以指定的選項。請注意，主控台與 CLI 之間的選項可能有所不同。

記憶體和 CPU

部署函數時，您可以指定函數可以耗用的記憶體及 CPU 數量。視您的功能是運算密集、記憶體密集或平衡而定，這些數量可能有所不同。

預設情況下，您的函數分配有 4 G 記憶體和1.0 vCPU。如需其他受支援記憶體及 CPU 組合的相關資訊，請參閱函數支援的記憶體及 CPU 組合。

使用環境變數建立及執行函數

您可以將環境變數定義及設定為鍵值組，以供函數在執行時期使用。

您可以在建立函數或使用 CLI 更新現有函數時定義環境變數。

如需定義環境變數的相關資訊，請參閱使用環境變數。

Code Engine 會自動將特定環境變數注入函數中。如需自動注入環境變數的相關資訊，請參閱自動注入環境變數。

使用密鑰及 configmap 時建立及執行函數

在 Code Engine中，您的函數可以使用環境變數來耗用密鑰及 configmap。

密鑰和 configmap 都是鍵值組。當對映至環境變數時，會設定 NAME=VALUE 關係，使環境變數的名稱對應於那些對映中每一個項目的「索引鍵」，且環境變數的值是該索引鍵的「值」。

您的函數可以使用環境變數來完整參照 configmap (或密碼)，或參照 configmap (或密碼) 中的個別索引鍵。

如需相關資訊，請參閱使用環境變數來參照密鑰及使用環境變數來參照配置對映。

函數配額的考量

當您使用應用程式、函數及批次工作時，這些資源會在 Code Engine 專案的環境定義內執行。資源配額是根據每個專案來定義，且限制適用於應用程式、功能及批次工作。

如需 Code Engine 限制的相關資訊，請參閱 Code Engine的限制和配額。

下一步

既然您已熟悉使用 Code Engine 函數的主要概念，您是否準備好建立並使用函數? 請參閱下列主題。

如需使用功能的相關資訊，請參閱下列主題。