本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Lambda 環境變數 您可以使用環境變數來調整函數的行為，而無需更新程式碼。環境變數是存放在函數特定版本組態中的一對字串。Lambda 執行時間可讓程式碼使用環境變數，並設定其他環境變數，這些變數包含函數和調用請求的相關資訊。 **注意** 為了提高安全性，我們建議您使用 AWS Secrets Manager 而非環境變數來存放資料庫登入資料和其他敏感資訊，例如 API 金鑰或授權字符。如需詳細資訊，請參閱[在 Lambda 函式中使用 Secrets Manager 秘密](with-secrets-manager.md)。 在函數調用之前，不會評估環境變數。您定義的任何值都會視為文字字串，而且不會展開。在函數程式碼中執行變數評估。 ## 建立 Lambda 環境變數 您可以使用 Lambda 主控台、 AWS Command Line Interface (AWS CLI)、 AWS Serverless Application Model (AWS SAM) 或使用 AWS SDK 在 Lambda 中設定環境變數。 ------ #### [ Console ] 您可以在函數的未發佈版本上定義環境變數。發布版本時，該版本的環境變數與其他[版本特定組態設定](configuration-versions.md)會被鎖定。 您可以透過定義索引鍵和值，為函數建立環境變數。函數使用索引鍵的名稱來擷取環境變數的值。 **在 Lambda 主控台中設定環境變數** 1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。 1. 選擇一個函數。 1. 選擇**組態**索引標籤，然後選擇**環境變數**。 1. 在 **Environment variables** (環境變數) 下，選擇 **Edit** (編輯)。 1. 選擇 **Add environment variable** (新增環境變數)。 1. 輸入索引鍵和值。 **請求** + 索引鍵需以英文字母為開頭，且至少有兩個字元。 + 索引鍵僅包含字母、數字和底線字元 (`_`)。 + 索引鍵不是[由 Lambda 預留](#configuration-envvars-runtime)。 + 所有環境變數的大小總計不超過 4 KB。 1. 選擇**儲存**。 **在主控台程式碼編輯器中產生環境變數清單** 可在 Lambda 程式碼編輯器中產生環境變數清單。這是在編碼時參考環境變數的快速方法。 1. 選擇 **程式碼** 標籤。 1. 向下捲動至程式碼編輯器的 **ENVIRONMENT VARIABLES** 區段。下面列出了現有環境變數： ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/env-var.png) 1. 若要建立新的環境變數，請選擇加號 (![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/add-plus.png))： ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/create-env-var.png) 在主控台程式碼編輯器中列出環境變數時，會保持加密狀態。如果在傳輸過程中啟用加密輔助工具進行加密，則這些設定會維持不變。如需詳細資訊，請參閱[保護 Lambda 環境變數](configuration-envvars-encryption.md)。 環境變數清單為唯讀狀態，且只能在 Lambda 主控台中使用。下載函數的 .zip 封存檔時，不會包含此檔案，且您無法透過上傳此檔案來新增環境變數。 ------ #### [ AWS CLI ] 下列範例會在名為 `my-function` 的函數上設定兩個環境變數。 ``` aws lambda update-function-configuration \ --function-name my-function \ --environment "Variables={BUCKET=amzn-s3-demo-bucket,KEY=file.txt}" ``` 當您使用 `update-function-configuration` 命令套用環境變數時，會取代 `Variables` 結構的整個內容。若要在新增環境變數時保留現有的環境變數，請在請求中包含所有現有值。 若要取得目前的組態，請使用 `get-function-configuration` 命令。 ``` aws lambda get-function-configuration \ --function-name my-function ``` 您應該會看到下列輸出： ``` { "FunctionName": "my-function", "FunctionArn": "arn:aws:lambda:us-east-2:111122223333:function:my-function", "Runtime": "nodejs24.x", "Role": "arn:aws:iam::111122223333:role/lambda-role", "Environment": { "Variables": { "BUCKET": "amzn-s3-demo-bucket", "KEY": "file.txt" } }, "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15", ... } ``` 可以從 `get-function-configuration` 的輸出中將修訂 ID 作為參數傳遞給 `update-function-configuration`。這樣可確保在讀取組態和更新組態期間，值不會變更。 若要設定函數的加密金鑰，請設定 `KMSKeyARN` 選項。 ``` aws lambda update-function-configuration \ --function-name my-function \ --kms-key-arn arn:aws:kms:us-east-2:111122223333:key/055efbb4-xmpl-4336-ba9c-538c7d31f599 ``` ------ #### [ AWS SAM ] 可以使用 [AWS Serverless Application Model](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/serverless-getting-started.html ) 來設定函數的環境變數。更新 `template.yaml` 檔案中的[環境](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-environment)和[變數](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html#cfn-lambda-function-environment-variables)屬性，然後執行 [sam 部署](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html)。 **Example template.yaml** ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: An AWS Serverless Application Model template describing your function. Resources: my-function: Type: AWS::Serverless::Function Properties: CodeUri: . Description: '' MemorySize: 128 Timeout: 120 Handler: index.handler Runtime: nodejs24.x Architectures: - x86_64 EphemeralStorage: Size: 10240 Environment: Variables: BUCKET: amzn-s3-demo-bucket KEY: file.txt # Other function properties... ``` ------ #### [ AWS SDKs ] 若要使用 AWS SDK 管理環境變數，請使用下列 API 操作。 + [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) + [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html) + [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) 若要進一步了解，請參閱您偏好的程式設計語言的 [AWS SDK 文件](https://aws.amazon.com/developer/tools/)。 ------ ## 環境變數的範例案例 您可以使用環境變數，自訂測試環境和生產環境中的函數行為。例如，您可以建立兩個具備相同程式碼，但不同組態的函數。一個函數連接到測試資料庫，另一個函數連接到生產資料庫。在此情況下，可以使用環境變數將資料庫的主機名稱和其他連線詳細資訊傳遞給函數。 以下範例顯示如何將資料庫主機和資料庫名稱定義為環境變數。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/console-env.png) 如果您希望測試環境產生比實際執行環境更多的偵錯資訊，您可以設定環境變數，以將測試環境設定為使用更詳細的記錄或更詳細的追蹤。 例如，在測試環境中，您可以使用 `LOG_LEVEL` 索引鍵與表示偵錯或追蹤日誌層級的值來設定環境變數。在 Lambda 函式的程式碼中，您可以使用此環境變數來設定日誌層級。 下列 Python 與 Node.js 語言程式碼範例示範可如何完成此操作。這些範例假設環境變數在 Python 中的值為 `DEBUG`，在 Node.js 中的值為 `debug`。 ------ #### [ Python ] **Example 設定日誌層級的 Python 程式碼** ``` import os import logging # Initialize the logger logger = logging.getLogger() # Get the log level from the environment variable and default to INFO if not set log_level = os.environ.get('LOG_LEVEL', 'INFO') # Set the log level logger.setLevel(log_level) def lambda_handler(event, context): # Produce some example log outputs logger.debug('This is a log with detailed debug information - shown only in test environment') logger.info('This is a log with standard information - shown in production and test environments') ``` ------ #### [ Node.js (ES module format) ] **Example 設定日誌層級的 Node.js 程式碼** 此範例使用 `winston` 記錄程式庫。使用 npm 將此程式庫新增至函式的部署套件。如需詳細資訊，請參閱[建立含相依項的 .zip 部署套件](nodejs-package.md#nodejs-package-create-dependencies)。 ``` import winston from 'winston'; // Initialize the logger using the log level from environment variables, defaulting to INFO if not set const logger = winston.createLogger({ level: process.env.LOG_LEVEL || 'info', format: winston.format.json(), transports: [new winston.transports.Console()] }); export const handler = async (event) => { // Produce some example log outputs logger.debug('This is a log with detailed debug information - shown only in test environment'); logger.info('This is a log with standard information - shown in production and test environment'); }; ``` ------ ## 擷取 Lambda 環境變數 若要在函數程式碼中擷取環境變數，請使用程式設計語言的標準方法。 ------ #### [ Node.js ] ``` let region = process.env.AWS_REGION ``` ------ #### [ Python ] ``` import os region = os.environ['AWS_REGION'] ``` **注意** 在某些情況下，您可能需要使用下列格式： ``` region = os.environ.get('AWS_REGION') ``` ------ #### [ Ruby ] ``` region = ENV["AWS_REGION"] ``` ------ #### [ Java ] ``` String region = System.getenv("AWS_REGION"); ``` ------ #### [ Go ] ``` var region = os.Getenv("AWS_REGION") ``` ------ #### [ C\$1 ] ``` string region = Environment.GetEnvironmentVariable("AWS_REGION"); ``` ------ #### [ PowerShell ] ``` $region = $env:AWS_REGION ``` ------ Lambda 透過靜態加密環境變數來安全地存放它們。您可以[設定 Lambda 使用不同的加密金鑰](configuration-envvars-encryption.md)、在用戶端加密環境變數值，或在具有 的 CloudFormation 範本中設定環境變數 AWS Secrets Manager。 ## 定義執行時間環境變數 Lambda [執行時間](lambda-runtimes.md)會在初始化期間設定數個環境變數。大多數的環境變數都會提供函數或執行時間的資訊。這些環境變數的索引鍵都已進行*預留*，無法在您的函數組態中設定。 **預留環境變數** + `_HANDLER` - 在函數中設定的處理常式位置。 + `_X_AMZN_TRACE_ID` - [X-Ray 追蹤標頭](services-xray.md)。此環境變數會隨著每次調用而變更。 + 未針對僅限作業系統的執行期 (`provided` 執行期系列) 定義此環境變數。您可以使用 [下次調用](runtimes-api.md#runtimes-api-next) 中的 `Lambda-Runtime-Trace-Id` 回應標頭為自訂執行階段設定 `_X_AMZN_TRACE_ID`。 + 對於 Java 執行期版本 17 及更高版本，不使用此環境變數。相反地，Lambda 會將追蹤資訊儲存在 `com.amazonaws.xray.traceHeader` 系統屬性中。 + `AWS_DEFAULT_REGION` – 執行 Lambda 函數的預設 AWS 區域 位置。 + `AWS_REGION` – 執行 Lambda 函數 AWS 區域 的 。若已完成定義，此值便會覆寫 `AWS_DEFAULT_REGION`。 + 如需搭配 AWS SDKs 使用 AWS 區域 環境變數的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[AWS 區域](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html#feature-region-sdk-compat)。 + `AWS_EXECUTION_ENV` – [執行時間識別符](lambda-runtimes.md)，字首為 `AWS_Lambda_` (例如，`AWS_Lambda_java8`)。未針對僅限作業系統的執行期 (`provided` 執行期系列) 定義此環境變數。 + `AWS_LAMBDA_FUNCTION_NAME` - 函數的名稱。 + `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` - 可供函數使用的記憶體量 (MB)。 + `AWS_LAMBDA_FUNCTION_VERSION` - 正在執行的函數版本。 + `AWS_LAMBDA_INITIALIZATION_TYPE` – 函數的初始化類型，即 `on-demand`、`snap-start`、 `provisioned-concurrency`或 `lambda-managed-instances`。如需詳細資訊，請參閱[設定佈建並行](provisioned-concurrency.md)[使用 Lambda SnapStart 改善啟動效能](snapstart.md)、 或 [Lambda 受管執行個體](lambda-managed-instances.md)。 + `AWS_LAMBDA_LOG_GROUP_NAME`、`AWS_LAMBDA_LOG_STREAM_NAME` - Amazon CloudWatch Logs 群組和函數串流的名稱。`AWS_LAMBDA_LOG_GROUP_NAME` 和 `AWS_LAMBDA_LOG_STREAM_NAME` [環境變數](#configuration-envvars-runtime)無法在 Lambda SnapStart 函數中使用。 + `AWS_ACCESS_KEY`、`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN` - 從函數的[執行角色](lambda-intro-execution-role.md)中取得的存取金鑰。 + `AWS_LAMBDA_RUNTIME_API` - ([自訂執行時間](runtimes-custom.md)) [執行時間 API](runtimes-api.md) 的主機和連接埠。 + `LAMBDA_TASK_ROOT` - 指向您 Lambda 函數程式碼的路徑。 + `LAMBDA_RUNTIME_DIR` - 指向執行時間程式庫的路徑。 + `AWS_LAMBDA_MAX_CONCURRENCY` – （僅限 Lambda 受管執行個體） Lambda 將傳送至一個執行環境的並行調用數目上限。 + `AWS_LAMBDA_METADATA_API` – 格式的[中繼資料端點](configuration-metadata-endpoint.md)伺服器地址 `{ipv4_address}:{port}`（例如 `169.254.100.1:9001`)。 + `AWS_LAMBDA_METADATA_TOKEN` – 目前執行環境的唯一身分驗證字符，用於對[中繼資料端點](configuration-metadata-endpoint.md)的請求進行身分驗證。Lambda 會在初始化時自動產生此權杖。 下列其他環境變數並未進行預留，可以在您的函數組態中進行擴充。 **未預留的環境變數** + `LANG` – 執行時間的地區設定 (`en_US.UTF-8`)。 + `PATH` – 執行路徑 (`/usr/local/bin:/usr/bin/:/bin:/opt/bin`)。 + `LD_LIBRARY_PATH` – 系統程式庫路徑 (`/var/lang/lib:/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib`)。 + `NODE_PATH` - ([Node.js](lambda-nodejs.md)) Node.js 程式庫路徑 (`/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules`)。 + `NODE_OPTIONS` – ([Node.js](lambda-nodejs.md)) 對於 Node.js 執行時期，您可以使用 `NODE_OPTIONS` 來重新啟用 Lambda 預設停用的實驗性功能。 + `PYTHONPATH` – ([Python](lambda-python.md)) Python 程式庫路徑 (`$LAMBDA_RUNTIME_DIR`)。 + `GEM_PATH` - ([Ruby](lambda-ruby.md)) Ruby 程式庫路徑 (`$LAMBDA_TASK_ROOT/vendor/bundle/ruby/3.3.0:/opt/ruby/gems/3.3.0`)。 + `AWS_XRAY_CONTEXT_MISSING` - 對於 X-Ray 追蹤，Lambda 將它設定為 `LOG_ERROR`，以避免從 X-Ray 開發套件中擲回執行時間錯誤。 + `AWS_XRAY_DAEMON_ADDRESS` - 對於 X-Ray 追蹤，為 X-Ray 常駐程式的 IP 地址和連接埠。 + `AWS_LAMBDA_DOTNET_PREJIT` – ([.NET](lambda-csharp.md)) 設定此變數，以啟用或停用 .NET 特定執行時期最佳化。值包含 `always`、`never` 和 `provisioned-concurrency`。如需詳細資訊，請參閱[設定函數的佈建並行](provisioned-concurrency.md)。 + `TZ` – 環境的時區 (`:UTC`)。執行環境使用 NTP 來同步系統時鐘。 顯示的範例值會反映最新的執行時間。特定變數或其值是否存在，可能會因先前的執行時間而有所不同。 # 保護 Lambda 環境變數 若要保護您的環境變數，可以使用伺服器端加密來保護您的靜態資料，並使用用戶端加密來保護傳輸中的資料。 **注意** 為了提高資料庫安全性，我們建議您使用 AWS Secrets Manager 而非環境變數來存放資料庫登入資料。如需詳細資訊，請參閱[在 Lambda 函式中使用 Secrets Manager 秘密](with-secrets-manager.md)。 **靜態安全** Lambda 永遠使用 AWS KMS key提供靜態伺服器端加密。預設情況下，Lambda 使用 AWS 受管金鑰。如果此預設行為符合您的工作流程，您便不需要設定其他項目。Lambda 會在您的帳戶 AWS 受管金鑰 中建立 ，並為您管理許可。 AWS 不會向您收取使用此金鑰的費用。 如果您願意，您可以改為提供 AWS KMS 客戶受管金鑰。您可以這樣做以控制 KMS 金鑰的輪換或滿足您的組織對管理 KMS 金鑰的請求。當您使用客戶受管的金鑰時，只有您帳戶中具有 KMS 金鑰存取權的使用者才能檢視或管理函數上的環境變數。 客戶受管金鑰會產生標準 AWS KMS 費用。如需詳細資訊，請參閱 [AWS Key Management Service 定價](https://aws.amazon.com/kms/pricing/)。 **傳輸中安全** 基於額外的安全性考量，您可啟用傳輸中加密輔助工具，此類工具能確保環境變數在傳輸過程中透過用戶端加密得到加密保護。 **若要為環境變數配置加密** 1. 使用 AWS Key Management Service (AWS KMS) 為 Lambda 建立任何客戶受管金鑰，以用於伺服器端和用戶端加密。如需詳細資訊，請參閱*AWS Key Management Service 開發人員指南*中的[建立金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。 1. 使用 Lambda 主控台，導覽至 **Edit environment variables** (編輯環境變數) 頁面。 1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。 1. 選擇一個函數。 1. 選擇 **Configuration** (組態)，然後從左側導覽列選擇 **Environment variables** (環境變數)。 1. 在 **Environment variables** (環境變數) 區段中，選擇 **Edit** (編輯)。 1. 展開 **Encryption configuration** (加密組態)。 1. (選用) 啟用主控台加密輔助工具，以透過用戶端加密保護傳輸中的資料。 1. 在**傳輸中加密**下，選擇**啟用傳輸中加密輔助工具**。 1. 對於每個要啟用主控台加密輔助工具的環境變數，請選擇該環境變數旁的**加密**選項。 1. 在 AWS KMS key 下加密傳輸中，選擇您在此程序開始時建立的客戶受管金鑰。 1. 選擇 **Execution role policy** (執行角色政策)，然後複製政策。此政策授予函數的執行角色解密環境變數的許可。 儲存此政策，以便在此程序的最後一個步驟中使用。 1. 向函數中新增解密環境變數的程式碼。若要查看範例，請選擇**解密秘密程式碼片段**。 1. (選用) 指定用於靜態加密的客戶受管金鑰。 1. 選擇 **Use a customer master key** (使用客戶主金鑰)。 1. 選擇在此程序開始時建立的客戶受管金鑰。 1. 選擇 **Save** (儲存)。 1. 設定許可。 如果搭配使用客戶受管金鑰和伺服器端加密，請向您希望其能檢視或管理該函數環境變數的任何使用者或角色授予許可。如需詳細資訊，請參閱[管理伺服器端加密 KMS 金鑰的許可](#managing-permissions-to-your-server-side-encryption-key)。 如果您要啟用用戶端加密來增強傳輸中安全，您的函數需要許可來呼叫 `kms:Decrypt` API 操作。將您先前在此程序中儲存的政策新增至函數的[執行角色](lambda-intro-execution-role.md)。 ## 管理伺服器端加密 KMS 金鑰的許可 您的使用者或函數的執行角色不需要任何 AWS KMS 許可，即可使用預設加密金鑰。若要使用客戶受管金鑰，您需要使用金鑰的許可。Lambda 會使用您的許可，在金鑰上建立授權。這麼做可讓 Lambda 使用它來進行加密。 + `kms:ListAliases` – 在 Lambda 主控台中檢視金鑰。 + `kms:CreateGrant`、`kms:Encrypt` - 在函數上設定客戶受管金鑰。 + `kms:Decrypt` - 檢視及管理使用客戶受管金鑰加密的環境變數。 您可以從 AWS 帳戶 或從金鑰的資源型許可政策取得這些許可。 `ListAliases` 是由 [Lambda 的 受管政策](access-control-identity-based.md)提供。金鑰政策會將其餘許可授予 **Key users** (金鑰使用者) 群組中的使用者。 沒有 `Decrypt` 許可的使用者仍然可以管理函數，但是無法在 Lambda 主控台中檢視或管理環境變數。如要防止使用者檢視環境變數，請將拒絕存取預設金鑰、客戶受管金鑰，或是所有金鑰的陳述式新增到使用者的許可。 **Example IAM 政策 - 透過金鑰 ARN 拒絕存取** **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Deny", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc" } ] } ``` 如需有關管理金鑰許可的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》**中的 [AWS KMS中的金鑰政策](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。