使用環境變數 AWS AppSync - AWS AppSync
配置環境變量（控制台）設定環境變數 (API)設定環境變數 (CFN)環境變數和合併的 API擷取環境變數

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用環境變數 AWS AppSync

您可以使用環境變量來調整 AWS AppSync 解析器和函數的行為，而無需更新代碼。環境變量是與您的 API 配置一起存儲的字符串對，可供解析器和函數在運行時使用。對於您必須參考僅在初始設定期間可用的組態資料，但在執行期間需要由解析器和函數使用的組態資料時，這些資料特別有用。環境變數會在程式碼中公開組態資料，因此減少對這些值進行硬式編碼的需求。

注意

若要提高資料庫安全性，建議您使用 Secrets Manager 或 AWS Systems Manager 參數存放區，而不要使用環境變數來儲存認證或機密資訊。若要利用此功能，請參閱使用 AWS AppSync HTTP 資料來源叫用 AWS 服務。

環境變量必須遵循幾個行為和規則才能正常運行：

  • JavaScript 解析器/函數和 VTL 模板都支持環境變量。

  • 在函數調用之前不會評估環境變量。

  • 環境變量僅支持字符串值。

  • 環境變數中的任何定義值都會被視為字串常值，而不會展開。

  • 理想情況下，應該在函數代碼中執行變量評估。

配置環境變量（控制台）

您可以建立變數並定義其索引鍵值配對，以設定 AWS AppSync GraphQL API 的環境變數。您的解析器和函數將使用環境變量的密鑰名稱在運行時檢索值。若要在 AWS AppSync 主控台中設定環境變數：

  1. 登入 AWS Management Console 並開啟AppSync主控台。

  2. 在 [API] 頁面上，選擇 GraphQL API 的名稱。

  3. 在 API 首頁的導覽窗格中，選擇 [設定]。

  4. 在環境變數下，選擇新增環境變數。

  5. 選擇 Add environment variable (新增環境變數)。

  6. 輸入索引鍵和值。

  7. 如有必要，請重複步驟 5 和 6 以加入更多關鍵值。如果您需要移除索引鍵值，請選擇 [移除] 選項和要移除的金鑰。

  8. 選擇提交。

提示

創建鍵和值時必須遵循一些規則：

  • 金鑰必須以字母開頭。

  • 金鑰必須至少有兩個字元。

  • 鍵只能包含字母、數字和底線字元 (_)。

  • 值最多可以有 512 個字元。

  • 您可以在 GraphQL API 中設定多達 50 個鍵值組。

設定環境變數 (API)

若要使用 API 設定環境變數，您可以使用PutGraphqlApiEnvironmentVariables. 對應的 CLI 命令是put-graphql-api-environment-variables。

若要使用 API 擷取環境變數，您可以使用GetGraphqlApiEnvironmentVariables. 對應的 CLI 命令是get-graphql-api-environment-variables。

該命令必須包含 API ID 和環境變量列表：

aws appsync put-graphql-api-environment-variables \  
  --api-id "<api-id>" \
  --environment-variables '{"key1":"value1","key2":"value2", …}'

下列範例會在 API 中設定兩個環境變數，其 ID 為abcdefghijklmnopqrstuvwxyz使用put-graphql-api-environment-variables指令：

aws appsync put-graphql-api-environment-variables \  
  --api-id "abcdefghijklmnopqrstuvwxyz" \
  --environment-variables '{"USER_TABLE":"users_prod","DEBUG":"true"}'

請注意，當您使用put-graphql-api-environment-variables指令套用環境變數時，環境變數結構的內容會被覆寫；這表示現有的環境變數將會遺失。要在添加新環境變量時保留現有的環境變量，請在請求中包括所有現有的鍵值對以及新的鍵值對。使用上面的例子，如果你想添加"EMPTY":""，你可以做到以下幾點：

aws appsync put-graphql-api-environment-variables \  
  --api-id "abcdefghijklmnopqrstuvwxyz" \
  --environment-variables '{"USER_TABLE":"users_prod","DEBUG":"true", "EMPTY":""}'

若要擷取目前的組態，請使用以下get-graphql-api-environment-variables指令：

aws appsync get-graphql-api-environment-variables --api-id "<api-id>"

使用上面的例子，您可以使用以下命令：

aws appsync get-graphql-api-environment-variables --api-id "abcdefghijklmnopqrstuvwxyz"

結果將顯示環境變量及其關鍵值的列表：

{
    "environmentVariables": {
        "USER_TABLE": "users_prod",
        "DEBUG": "true",
        "EMPTY": ""
    }
}

設定環境變數 (CFN)

您可以使用下面的模板創建環境變量：

AWSTemplateFormatVersion: 2010-09-09
Resources:
  GraphQLApiWithEnvVariables:
    Type: "AWS::AppSync::GraphQLApi"
    Properties:
      Name: "MyApiWithEnvVars"
      AuthenticationType: "AWS_IAM"
      EnvironmentVariables:
        EnvKey1: "non-empty"
        EnvKey2: ""

環境變數和合併的 API

在來源 API 中定義的環境變數也可以在合併的 API 中使用。合併 API 中的環境變數為唯讀且無法更新。請注意，您的環境變數金鑰在所有 Source API 中必須是唯一的，才能成功合併；重複的金鑰永遠會導致合併失敗。

擷取環境變數

要在函數代碼中檢索環境變量，請從解析器和函數中的ctx.env對象中檢索值。以下是一些實際操作的例子。

Publishing to Amazon SNS

在此範例中，我們的 HTTP 解析器會將訊息傳送至 Amazon SNS 主題。只有在定義 GraphQL API 的堆疊和主題部署完成後，才會知道主題的 ARN。

/**
 * Sends a publish request to the SNS topic
 */
export function request(ctx) {
    const TOPIC_ARN = ctx.env.TOPIC_ARN;
    const { input: values } = ctx.args;
    // this custom function sends values to the SNS topic
    return publishToSNSRequest(TOPIC_ARN, values);
}
Transactions with DynamoDB

在此範例中，如果針對測試部署 API 或已在生產環境中部署，DynamoDB 表的名稱會有所不同。解析器代碼不需要更改。環境變數的值會根據 API 的部署位置進行更新。

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { authorId, postId } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: ctx.env.POST_TABLE,
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ postId }),
        // rest of the configuration
      },
      {
        table: ctx.env.AUTHOR_TABLE,
        operation: 'UpdateItem',
        key: util.dynamodb.toMapValues({ authorId }),
        // rest of the configuration
      },
    ],
  };
}