REST API 배포에 대한 스테이지 변수 설정 - Amazon API Gateway

REST API 배포에 대한 스테이지 변수 설정

단계 변수는 REST API의 배포 단계와 연결된 구성 속성으로 정의되는 이름-값 페어입니다. 환경 변수와 비슷한 역할을 하며 API 설정 및 매핑 템플릿에 사용할 수 있습니다.

예를 들어 단계 구성에서 단계 변수를 정의한 다음, 변수 값을 REST API의 메서드에 대한 HTTP 통합의 URL 문자열로 설정할 수 있습니다. 나중에 API 설정에 있는 연결된 스테이지 변수 이름을 사용하여 URL 문자열을 참조할 수 있습니다. 이렇게 하면 스테이지 변수 값을 해당 URL로 재설정함으로써 각 스테이지의 서로 다른 엔드포인트에서 동일한 API 설정을 사용할 수 있습니다.

매핑 템플릿에서 단계 변수를 액세스하거나 구성 파라미터를 AWS Lambda 또는 HTTP 백엔드에 전달할 수도 있습니다.

매핑 템플릿에 대한 자세한 내용은 API Gateway 매핑 템플릿과 액세스 로깅 변수 참조 단원을 참조하십시오.

사용 사례

API Gateway의 배포 단계에서 알파, 베타, 프로덕션 등 각 API에 대한 여러 릴리스 단계를 관리할 수 있습니다. 단계 변수를 사용하여 API 배포 단계가 다양한 백엔드 엔드포인트와 상호 작용하도록 구성할 수 있습니다.

예를 들어, API에서 백엔드 웹 호스트(예: http://example.com)에 GET 요청을 HTTP 프록시로 전달할 수 있습니다. 이 경우 단계 변수에 백엔드 웹 호스트를 구성하여 개발자가 프로덕션 엔드포인트를 호출할 때 API Gateway에서 example.com을 호출하도록 합니다. 베타 엔드포인트를 호출할 때 API Gateway는 베타 단계에 대한 단계 변수에 구성된 값을 사용하고, 다른 웹 호스트(예: beta.example.com)를 호출합니다. 마찬가지로, API의 각 단계에서 다른 AWS Lambda 함수 이름을 지정하는 데 단계 변수를 사용할 수 있습니다.

매핑 템플릿을 통해 Lambda 함수로 구성 파라미터를 전달할 때도 단계 변수를 사용할 수 있습니다. 예를 들어 API의 여러 스테이지에서 동일한 Lambda 함수를 다시 사용하고 싶을 수 있으나, 이 함수는 호출 중인 스테이지에 따라 서로 다른 Amazon DynamoDB 테이블에서 데이터를 읽어 와야 합니다. 이때 Lambda 함수에 대한 요청을 생성하는 매핑 템플릿에서 단계 변수를 사용하여 테이블 이름을 Lambda로 전달할 수 있습니다.

단계 변수는 API 사양의 보안 정의 섹션에 적용되지 않습니다. 예를 들어 다른 단계에서는 다른 Amazon Cognito 사용자 풀을 사용할 수 없습니다.

예제

스테이지 변수를 사용하여 HTTP 통합 엔드포인트를 사용자 지정하려면, 먼저 지정된 이름(예: url)의 스테이지 변수를 구성하고 여기에 값(예: example.com)을 할당합니다. 그런 다음 메소드 구성에서 HTTP 프록시 통합을 설정합니다. 엔드포인트의 URL을 입력하는 대신 스테이지 변수 값인 http://${stageVariables.url}을 사용하도록 API Gateway에 지정할 수 있습니다. API Gateway는 API의 실행 단계에 따라 실행 시간에 단계 변수 ${}를 이 값으로 대체할 수 있습니다.

비슷한 방식으로 단계 변수를 참조하여 자격 증명 필드에서 Lambda 함수 이름, AWS 서비스 프록시 경로 또는 AWS 역할 ARN을 지정할 수 있습니다.

Lambda 함수 이름을 단계 변수 값으로 지정하려면 Lambda; 함수에 대한 권한을 수동으로 구성해야 합니다. 이를 위해 AWS Command Line Interface(AWS CLI)를 사용할 수 있습니다.

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction

다음 예제에서는 API 메서드 대신 AWS 계정의 미국 서부(오레곤) 리전에서 호스팅하는 Lambda 함수(helloWorld)를 호출할 수 있도록 API Gateway 권한을 할당합니다.

arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello

다음은 AWS CLI을 사용하는 동일한 명령입니다.

aws lambda add-permission --function-name arn:aws:lambda:us-east-1:123123123123:function:helloWorld --source-arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction