# API Gateway에서 REST API용 스테이지 변수 사용
<a name="stage-variables"></a>

스테이지 변수는 REST API의 배포 스테이지와 연결된 구성 속성으로 정의되는 키-값 페어입니다. 환경 변수와 비슷한 역할을 하며 API 설정 및 매핑 템플릿에 사용할 수 있습니다. API Gateway의 배포 스테이지를 통해 각 API에 대한 여러 릴리스 스테이지를 관리할 수 있으며, 스테이지 변수를 사용하여 다양한 백엔드 엔드포인트와 상호 작용하도록 API 배포 스테이지를 구성할 수 있습니다.

단계 변수는 자격 증명과 같은 중요한 데이터에 사용할 수 없습니다. 중요한 데이터를 통합에 전달하려면 AWS Lambda 권한 부여자를 사용합니다. Lambda 권한 부여자의 출력에서 중요한 데이터를 통합에 전달할 수 있습니다. 자세한 내용은 [API Gateway Lambda 권한 부여자의 출력](api-gateway-lambda-authorizer-output.md) 단원을 참조하십시오.

## 스테이지 변수 사용 사례
<a name="use-cases"></a>

스테이지 변수의 사용 사례는 다음과 같습니다.

**다른 백엔드 엔드포인트 지정**  
API에서 백엔드 웹 호스트에 `GET` 요청을 HTTP 프록시로 전달할 수 있습니다. 스테이지 변수를 사용하여 API 호출자가 프로덕션 엔드포인트를 간접적으로 호출할 때 API Gateway가 `example.com`을 직접적으로 호출하도록 할 수 있습니다. 그런 다음 API 호출자가 베타 스테이지를 간접적으로 호출하면 API Gateway는 다른 웹 호스트(예: `beta.example.com`)를 직접적으로 호출합니다. 마찬가지로, API의 각 단계에서 다른 AWS Lambda 함수 이름을 지정하는 데 단계 변수를 사용할 수 있습니다. `GET` 요청을 한 스테이지에서는 HTTP 프록시 통합으로, 다른 스테이지에서는 Lambda 프록시 통합으로 가리키는 등 다른 통합 엔드포인트를 설정하는 데는 스테이지 변수를 사용할 수 없습니다.  
Lambda 함수 이름을 단계 변수 값으로 지정할 때는 Lambda 함수에 대한 권한을 수동으로 구성해야 합니다. API Gateway 콘솔에서 Lambda 함수를 지정하면 적절한 권한을 구성하기 위한 AWS CLI 명령이 표시됩니다. 다음 AWS CLI 명령을 사용하여 이 작업을 수행할 수도 있습니다.  

```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```

**매핑 템플릿을 사용하여 정보 전달**  
매핑 템플릿에서 스테이지 변수를 액세스하거나 구성 파라미터를 AWS Lambda 또는 HTTP 백엔드에 전달할 수 있습니다. 예를 들어 API의 여러 스테이지에 동일한 Lambda 함수를 재사용하려고 할 수 있지만, 이 함수는 스테이지에 따라 다른 Amazon DynamoDB 테이블에서 데이터를 읽어야 합니다. 이때 Lambda 함수에 대한 요청을 생성하는 매핑 템플릿에서 단계 변수를 사용하여 테이블 이름을 Lambda에 전달할 수 있습니다.

스테이지 변수를 사용하려면 먼저 스테이지 변수를 구성한 다음 값을 할당합니다. 예를 들어 HTTP 통합 엔드포인트를 사용자 지정하려면 먼저 `url` 스테이지 변수를 생성한 다음 API의 통합 요청에서 스테이지 변수 값 **http://\$1\$1stageVariables.url\$1**을 입력합니다. 이 값은 API가 실행되는 단계에 따라 실행 시간에 단계 변수 `${}`를 대체하도록 API Gateway에 지시합니다. 자세한 내용은 [API Gateway에서 REST API에 대한 스테이지 변수 설정](how-to-set-stage-variables-aws-console.md) 단원을 참조하십시오.

# API Gateway에서 REST API에 대한 스테이지 변수 설정
<a name="how-to-set-stage-variables-aws-console"></a>

이 섹션에서는 Amazon API Gateway 콘솔을 사용하여 샘플 API의 두 가지 배포 스테이지에 대해 다양한 스테이지 변수를 설정하는 방법을 보여줍니다. API Gateway에서 스테이지 변수를 사용하는 방법을 이해하려면 이 섹션의 모든 절차를 따르는 것이 좋습니다.

## 사전 조건
<a name="how-to-set-stage-variables-aws-console-prerequisites"></a>

시작하기 전에 다음 사전 요구 사항을 충족하는지 확인하세요.
+ API Gateway에 사용 가능한 API가 있어야 합니다. [API Gateway에서 REST API 개발](rest-api-develop.md)의 지침을 따르세요.
+ API는 1회 이상 배포되어야 합니다. [API Gateway에서 REST API 배포](how-to-deploy-api.md)의 지침을 따르세요.
+ 배포된 API에 대한 첫 단계를 생성해야 합니다. [새 단계 생성](set-up-stages.md#how-to-create-stage-console)의 지침을 따르세요.

  

## 스테이지 변수를 사용하여 API를 통해 HTTP 엔드포인트 간접 호출
<a name="how-to-set-stage-variables-aws-console-http-endpoint"></a>

이 절차에서는 HTTP 엔드포인트에 대한 스테이지 변수 1개와 API에 대한 스테이지 2개를 생성하는 방법을 설명합니다. 또한 이 섹션의 다음 절차에 사용되는 스테이지 변수 `url`, `stageName` 및 `function`도 생성합니다.

**스테이지 변수를 사용하여 API를 통해 HTTP 엔드포인트를 간접적으로 호출하려면**

1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.

1. API를 생성한 다음 API의 루트 리소스에 `GET` 메서드를 생성합니다. 통합 유형을 **HTTP**로 설정하고 **엔드포인트 URL**을 **http://\$1\$1stageVariables.url\$1**로 설정합니다.

1. API를 **beta**라는 스테이지에 배포합니다.

1. 기본 탐색 창에서 **스테이지**를 선택한 후 **베타** 스테이지를 선택합니다.

1. **스테이지 변수** 탭에서 **편집**을 선택합니다.

1. **스테이지 변수 추가**를 선택합니다.

1. **이름**에 **url**을 입력합니다. **값**에 **httpbin.org/get**을 입력합니다.

1. **스테이지 변수 추가**를 선택하고 다음을 수행합니다.

   **이름**에 **stageName**을 입력합니다. **값**에 **beta**을 입력합니다.

1. **스테이지 변수 추가**를 선택하고 다음을 수행합니다.

   **이름**에 **function**을 입력합니다. **값**에 **HelloWorld**을 입력합니다.

1. **Save**(저장)를 선택합니다.

1.  이제 두 번째 스테이지를 생성합니다. **스테이지** 탐색 창에서 **스테이지 생성**을 선택합니다. **단계 이름**에 **prod**를 입력합니다. **배포**에서 최신 배포를 선택한 후 **스테이지 생성**을 선택합니다.

1.  **베타** 스테이지와 마찬가지로, 동일한 세 스테이지 변수(**url**, **stageName**, **function**)를 각각 다른 값(**petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod**, **HelloEveryone**)으로 설정합니다.

1. **단계** 탐색 창에서 **베타**를 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 웹 브라우저에 입력합니다. 그러면 API의 루트 리소스에 대한 [**beta**] 단계 `GET` 요청이 시작됩니다.
**참고**  
[**Invoke URL**] 링크는 [**beta**] 단계에서 API의 루트 리소스를 가리킵니다. 웹 브라우저에 URL을 입력하면 루트 리소스에서 링크 **베타** 스테이지 `GET` 메서드를 호출합니다. 루트 리소스 자체가 아닌 하위 리소스에 메서드가 정의된 경우, 웹 브라우저에 URL을 입력하면 `{"message":"Missing Authentication Token"}` 오류 응답이 반환됩니다. 이 경우 특정 하위 리소스의 이름을 **URL 호출(Invoke URL)** 링크에 추가해야 합니다.

1. [**beta**] 단계 `GET` 요청에서 받은 응답은 다음에 표시됩니다. 브라우저로 [**http://httpbin.org/get**] 페이지를 탐색해 결과를 확인할 수도 있습니다. 이 값은 [**beta**] 단계의 `url` 변수에 할당되었습니다. 이 두 응답은 동일합니다.

1. **단계(Stages)** 탐색 창에서 **prod** 단계를 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 웹 브라우저에 입력합니다. 그러면 API의 루트 리소스에 대한 **prod** 단계 `GET` 요청이 시작됩니다.

1. [**prod**] 단계 `GET` 요청에서 받은 응답은 다음에 표시됩니다. 브라우저로 **http://petstore-demo-endpoint.execute-api.com/petstore/pets** 페이지를 탐색해 결과를 확인할 수 있습니다. 이 값은 [**prod**] 단계의 `url` 변수에 할당되었습니다. 이 두 응답은 동일합니다.

## 스테이지별 메타데이터를 HTTP 백엔드로 전달
<a name="how-to-set-stage-variables-aws-console-stage-metadata"></a>

이 절차에서는 쿼리 파라미터 표현식에서 스테이지 변수 값을 사용하여 스테이지별 메타데이터를 HTTP 백엔드로 전달하는 방법에 대해 설명합니다. 이전 절차에서 선언된 `stageName` 스테이지 변수를 사용하겠습니다.

**스테이지별 메타데이터를 HTTP 백엔드로 전달하려면**

1. **리소스** 탐색 창에서 **GET** 메서드를 선택합니다.

   쿼리 문자열 파라미터를 메서드의 URL에 추가하려면 **메서드 요청** 탭을 선택한 다음 **메서드 요청 설정** 섹션에서 **편집**을 선택합니다.

1. **URL 쿼리 문자열 파라미터**를 선택하고 다음을 수행합니다.

   1. **쿼리 문자열 추가(Add query string)**를 선택합니다.

   1. **이름**에 **stageName**을 입력합니다.

   1. **필수** 상태로 유지하고 **캐싱**을 해제합니다.

1. **Save**(저장)를 선택합니다.

1. **통합 요청** 탭을 선택한 다음 **통합 요청 설정** 섹션에서 **편집**을 선택합니다.

1. **엔드포인트 URL**의 경우 이전에 정의한 URL 값에 **?stageName=\$1\$1stageVariables.stageName\$1**을 추가하여 전체 **엔드포인트 URL**이 **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**이 되도록 합니다.

1. **배포 API**를 선택하고 **베타** 스테이지를 선택합니다.

1. 기본 탐색 창에서 **스테이지**를 선택합니다. **단계** 탐색 창에서 **베타**를 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 웹 브라우저에 입력합니다.
**참고**  
 `url` 변수 "http://httpbin.org/get"에서 지정한 바와 같이 HTTP 엔드포인트가 쿼리 파라미터 표현식을 수락하고 응답으로 `args` 객체로 반환하기 때문에 베타 스테이지를 사용합니다.

1. 응답은 다음과 같습니다. `beta` 단계 변수에 할당된 `stageName`는 백엔드에 `stageName` 인수로 전달됩니다.

      
![\[url 스테이지 변수를 사용하여 HTTP 엔드포인트에 대한 API의 GET 메서드로부터 받은 응답입니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)

## 스테이지 변수를 사용하여 API를 통해 Lambda 함수 간접 호출
<a name="how-to-set-stage-variables-aws-console-lambda-function"></a>

이 절차에서는 스테이지 변수를 사용하여 Lambda 함수를 API 백엔드로 호출하는 방법을 설명합니다. `function`에서 선언된 [스테이지 변수를 사용하여 API를 통해 HTTP 엔드포인트 간접 호출](#how-to-set-stage-variables-aws-console-http-endpoint) 스테이지 변수를 사용합니다.

 Lambda 함수를 단계 변수의 값으로 설정할 때는 **HelloWorld**, **HelloWorld:1** 또는 **HelloWorld:alpha**와 같이 별칭이나 버전 사양이 포함될 수 있는 함수의 로컬 이름을 사용합니다. 해당 함수의 ARN을 사용하면 안 됩니다(예: **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). API Gateway 콘솔은 Lambda 함수에 대한 스테이지 변수 값을 정규화되지 않은 함수 이름으로 가정하고 주어진 스테이지 변수를 ARN으로 확장합니다.

**스테이지 변수를 사용하여 API를 통해 Lambda 함수를 간접적으로 호출하려면**

1. 기본 Node.js 런타임을 사용하여 **HelloWorld**라는 Lambda 함수를 생성합니다. 코드에는 다음이 포함되어 있습니다.

   ```
   export const handler = function(event, context, callback) {
       if (event.stageName)
           callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
       else
           callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
   };
   ```

   Lambda 함수를 생성하는 방법에 대한 자세한 내용은 [REST API 콘솔 시작하기](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function)를 참조하세요.

1. **리소스** 창에서 **리소스 생성**을 선택하고 다음을 수행합니다.

   1. **리소스 경로**에서 **/**를 선택합니다.

   1. **리소스 이름**에 **lambdav1**을 입력합니다.

   1. **리소스 생성**을 선택합니다.

1. **/lambdav1** 리소스를 선택한 다음 **메서드 생성**을 선택합니다.

   뒤이어 다음과 같이 하세요.

   1. **메서드 유형**에서 **GET**을 선택합니다.

   1. **통합 유형**에서 **Lambda 함수**를 선택합니다.

   1. **Lambda 프록시 통합**을 비활성화된 상태로 유지합니다.

   1. **Lambda 함수**에서 `${stageVariables.function}`을(를) 입력합니다.  
![\[function 단계 변수에서 지정한 대로 Lambda 함수와 통합된 GET 메서드를 생성합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**작은 정보**  
**권한 명령 추가**라는 메시지가 표시되면 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령을 복사합니다. `function` 스테이지 변수에 할당될 각 Lambda 함수에서 명령을 실행합니다. 예를 들어, `$stageVariables.function` 값이 `HelloWorld`이면 다음 AWS CLI 명령을 실행합니다.  

      ```
      aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
      ```
 그렇지 않으면 메서드 호출 시 `500 Internal Server Error` 응답이 반환됩니다. `${stageVariables.function}`을 스테이지 변수에 할당된 Lambda 함수 이름으로 바꾸어야 합니다.  
   

![\[생성한 메서드에서 간접적으로 호출할 Lambda 함수에 권한을 추가하는 AWS CLI 명령입니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)


   1. **메서드 생성**을 선택합니다.

1. **프로덕션** 및 **베타** 스테이지 모두에 API를 배포합니다.

1. 기본 탐색 창에서 **스테이지**를 선택합니다. **단계** 탐색 창에서 **베타**를 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 웹 브라우저에 입력합니다. URL에 **/lambdav1**을 추가한 다음 Enter 키를 누릅니다.

   응답은 다음과 같습니다.

   ```
   "Hello, World! I'm not sure where I'm calling from..."
   ```

## 단계 변수를 통해 Lambda 함수에 단계별 메타데이터 전달
<a name="pass-version-info-to-lambda-backend-with-stage-variable"></a>

이 절차에서는 단계 변수를 사용하여 Lambda 함수로 단계별 구성 메타데이터를 전달하는 방법을 설명합니다. `POST` 메서드 및 입력 매핑 템플릿을 만들어 앞서 설명한 `stageName` 스테이지 변수를 사용해 페이로드를 생성합니다.

**스테이지 변수를 통해 Lambda 함수에 스테이지별 메타데이터를 전달하려면**

1. **/lambdav1** 리소스를 선택한 다음 **메서드 생성**을 선택합니다.

   뒤이어 다음과 같이 하세요.

   1. **메서드 유형**에서 **POST**를 선택합니다.

   1. **통합 유형**에서 **Lambda 함수**를 선택합니다.

   1. **Lambda 프록시 통합**을 비활성화된 상태로 유지합니다.

   1. **Lambda 함수**에서 `${stageVariables.function}`을(를) 입력합니다.

   1. **권한 명령 추가**라는 메시지가 표시되면 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령을 복사합니다. `function` 스테이지 변수에 할당될 각 Lambda 함수에서 명령을 실행합니다.

   1. **메서드 생성**을 선택합니다.

1. **통합 요청** 탭을 선택한 다음 **통합 요청 설정** 섹션에서 **편집**을 선택합니다.

1. **매핑 템플릿**을 선택한 다음 **매핑 템플릿 추가**를 선택합니다.

1. **콘텐츠 유형**에 **application/json**을 입력합니다.

1. **템플릿 본문**에 다음 템플릿을 입력합니다.

   ```
   #set($inputRoot = $input.path('$'))
   {
       "stageName" : "$stageVariables.stageName"
   }
   ```
**참고**  
 매핑 템플릿에서 스테이지 변수는 따옴표 안에 참조되어야 합니다(`"$stageVariables.stageName"` 또는 `"${stageVariables.stageName}"`에서와 같이). 다른 곳에서는 따옴표 없이 참조해야 합니다(`${stageVariables.function}`에서와 같이).

1. **Save**(저장)를 선택합니다.

1. **베타** 및 **프로덕션** 스테이지 모두에 API를 배포합니다.

1. REST API 클라이언트를 사용하여 스테이지별 메타데이터를 전달하려면 다음을 수행합니다.

   1. **단계** 탐색 창에서 **베타**를 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 REST API 클라이언트의 입력 필드에 입력합니다. **/lambdav1**을 추가한 후 요청을 제출합니다.

      응답은 다음과 같습니다.

      ```
      "Hello, World! I'm calling from the beta stage."
      ```

   1. **스테이지** 탐색 창에서 **프로덕션**을 선택합니다. **스테이지 세부 정보**에서 복사 아이콘을 선택해 API의 호출 URL을 복사하여 REST API 클라이언트의 입력 필드에 입력합니다. **/lambdav1**을 추가한 후 요청을 제출합니다.

      응답은 다음과 같습니다.

      ```
      "Hello, World! I'm calling from the prod stage."
      ```

1. **테스트** 기능을 사용하여 스테이지별 메타데이터를 전달하려면 다음을 수행합니다.

   1. **리소스** 탐색 창에서 **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

   1. **function**에 **HelloWorld**를 입력합니다.

   1. **stageName**에 **beta**를 입력합니다.

   1. **테스트**를 선택합니다. `POST` 요청에 본문을 추가할 필요는 없습니다.

      응답은 다음과 같습니다.

      ```
      "Hello, World! I'm calling from the beta stage."
      ```

   1. 이전 단계를 반복하여 **프로덕션** 스테이지를 테스트할 수 있습니다. **stageName**에 **Prod**를 입력합니다.

      응답은 다음과 같습니다.

      ```
      "Hello, World! I'm calling from the prod stage."
      ```

# API Gateway의 REST API용 API Gateway의 스테이지 변수 참조
<a name="aws-api-gateway-stage-variables-reference"></a>

 다음과 같은 경우에 API Gateway 단계 변수를 사용할 수 있습니다.

## 파라미터 매핑 표현식
<a name="stage-variables-in-parameter-mapping-expressions"></a>

API 메서드의 요청 또는 응답 헤더 파라미터를 부분적으로 바꾸지 않고도 파라미터 매핑 표현식에 단계 변수를 사용할 수 있습니다. 다음 예에서는 `$` 및 `{...}`로 묶지 않고 단계 변수를 참조합니다.
+ `stageVariables.<variable_name>`

## 매핑 템플릿
<a name="stage-variables-in-mapping-templates"></a>

 다음 예에서 보듯 단계 변수는 매핑 템플릿 어디에서나 사용할 수 있습니다.
+  `{ "name" : "$stageVariables.<variable_name>"}`
+ `{ "name" : "${stageVariables.<variable_name>}"}`

## HTTP 통합 URI
<a name="stage-variables-in-integration-HTTP-uris"></a>

다음 예제에서 보듯 스테이지 변수를 HTTP 통합 URL의 일부로 사용할 수 있습니다.
+ 프로토콜이 없는 전체 URI - `http://${stageVariables.<variable_name>}`
+ 전체 도메인 - `http://${stageVariables.<variable_name>}/resource/operation`
+ 하위 도메인 - `http://${stageVariables.<variable_name>}.example.com/resource/operation`
+ 경로 - `http://example.com/${stageVariables.<variable_name>}/bar`
+ 쿼리 문자열 - `http://example.com/foo?q=${stageVariables.<variable_name>}` 

## AWS 통합 URI
<a name="stage-variables-in-integration-aws-uris"></a>

 다음 예에서 보듯 단계 변수를 경로 구성 요소 또는 AWS URI의 일부로 사용할 수 있습니다.
+ `arn:aws:apigateway:<region>:<service>:${stageVariables.<variable_name>}`

## AWS 통합 URI(Lambda 함수)
<a name="stage-variables-in-integration-lambda-functions"></a>

 다음 예제와 같이 Lambda 함수 이름 또는 버전/별칭 대신에 단계 변수를 사용할 수 있습니다.
+ `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations`
+ `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations`

**참고**  
Lambda 함수에 대해 단계 변수를 사용하려면 함수가 API와 동일한 계정에 있어야 합니다. 단계 변수는 교차 계정 Lambda 함수를 지원하지 않습니다.

## Amazon Cognito 사용자 풀
<a name="stage-variables-in-integration-lambda-functions"></a>

`COGNITO_USER_POOLS` 권한 부여자의 Amazon Cognito 사용자 풀 대신 스테이지 변수를 사용할 수 있습니다.
+ `arn:aws:cognito-idp:<region>:<account_id>:userpool/${stageVariables.<variable_name>}`

## AWS 통합 자격 증명
<a name="stage-variables-in-integration-aws-credentials"></a>

 다음 예에서 보듯 단계 변수를 AWS 사용자/역할 자격 증명 ARN의 일부로 사용할 수 있습니다.
+  `arn:aws:iam::<account_id>:${stageVariables.<variable_name>}`