本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 AWS AppSync 中使用环境变量
<a name="environment-variables"></a>

您可以使用环境变量来调整 AWS AppSync 解析器和函数的行为，而无需更新代码。环境变量是与您的 API 配置一起存储的字符串对，可供您的解析器和函数在运行时使用。如果您必须引用的配置数据仅在初始设置期间可用，而您的解析器和函数需要在运行期间使用配置数据，那么环境变量特别有用。环境变量在您的代码中公开配置数据，从而减少了对这些值进行硬编码的需求。

**注意**  
为了提高数据库的安全性，建议您使用 [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 或 [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) 而不是环境变量来存储凭证或敏感信息。要利用此特征，请参阅 [Invoking AWS services with AWS AppSync HTTP data sources](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-http-resolvers-js.html#invoking-aws-services-js)。

环境变量必须遵循多种行为和规则才能正常运行：
+ JavaScript 解析器/函数和 VTL 模板都支持环境变量。
+ 不会在调用函数之前评估环境变量。
+ 环境变量**仅**支持字符串值。
+ 环境变量中定义的任何值都视为字符串文本，且不会展开。
+ 理想情况下，应在函数代码中执行变量评估。

## 配置环境变量（控制台）
<a name="configuring-environment-variables-console"></a>

您可以通过创建变量并定义其键值对，为 AWS AppSync GraphQL API 配置环境变量。您的解析器和函数将使用环境变量的键名在运行时检索值。在 AWS AppSync 控制台中设置环境变量：

1. 登录到 AWS 管理控制台，然后打开 [AppSync 控制台](https://console.aws.amazon.com/appsync/)。

1. 在 **API** 页面上，选择一个 GraphQL API 的名称。

1. 在您的 API 主页的导航窗格中，选择**设置**。

1. 在**环境变量**下，选择**添加环境变量**。

1. 选择**添加环境变量**。

1. 输入键和值。

1. 如有必要，请重复步骤 5 和 6 以添加更多键值。如果需要删除键值，请选择**删除**选项和要删除的键。

1. 选择**提交**。

**提示**  
创建键和值时必须遵循以下几条规则：  
键必须以字母开头。
键长度必须至少为两个字符。
键只能包含字母、数字和下划线字符（\$1）。
值最长可达 512 个字符。
最多可在 GraphQL API 中配置 50 个键/值对。

## 配置环境变量（API）
<a name="configuring-environment-variables-api"></a>

要使用 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", …}'
```

以下示例使用 `put-graphql-api-environment-variables` 命令在 ID 为 `abcdefghijklmnopqrstuvwxyz` 的 API 中设置了两个环境变量：

```
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）
<a name="configuring-environment-variables-cfn"></a>

可以使用下面的模板创建环境变量：

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

## 环境变量和合并的 API
<a name="configuring-environment-variables-merged-api"></a>

源 API 中定义的环境变量也可在合并的 API 中使用。合并的 API 中的环境变量是只读变量，无法更新。请注意，环境变量键在所有源 API 中必须唯一，才会成功合并；重复的键始终会导致合并失败。

## 检索环境变量
<a name="retrieving-environment-variables"></a>

要检索函数代码中的环境变量，请从解析器和函数中的 `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
      },
    ],
  };
}
```

------