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

# 在 中使用環境變數 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 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)，而非環境變數來存放登入資料或敏感資訊。若要利用此功能，請參閱[使用 AWS AppSync HTTP 資料來源叫用 AWS 服務](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. 在 **APIs**頁面上，選擇 GraphQL API 的名稱。

1. 在 API 首頁的導覽窗格中，選擇**設定**。

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

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

1. 輸入索引鍵和值。

1. 如有必要，請重複步驟 5 和 6 來新增更多索引鍵值。如果您需要移除索引鍵值，請選擇**移除**選項和要移除的索引鍵 (key)。

1. 選擇**提交**。

**提示**  
建立金鑰和值時，必須遵循幾個規則：  
金鑰必須以字母開頭。
金鑰長度必須至少為兩個字元。
索引鍵只能包含字母、數字和底線字元 (\$1)。
值長度最多可達 512 個字元。
您可以在 GraphQL API 中設定最多 50 個鍵值對。

## 設定環境變數 (API)
<a name="configuring-environment-variables-api"></a>

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

若要使用 APIs擷取環境變數，您可以使用 `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", …}'
```

下列範例`abcdefghijklmnopqrstuvwxyz`會使用 `put-graphql-api-environment-variables`命令，在 ID 為 的 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: ""
```

## 環境變數和合併 APIs
<a name="configuring-environment-variables-merged-api"></a>

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

## 擷取環境變數
<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
      },
    ],
  };
}
```

------