기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Step Functions에서 API Gateway REST API 생성
Step Functions에서 Amazon API Gateway를 사용하여 HTTP 및 REST API를 생성, 게시, 유지 및 모니터링하는 방법을 알아봅니다. API Gateway와 통합하려면 코드를 작성하거나 다른 인프라를 사용하지 않고도 API Gateway HTTP 또는 API Gateway REST 엔드포인트를 직접 호출하는 Step Functions에서 `Task` 상태를 정의합니다. `Task` 상태 정의에는 API 직접 호출에 필요한 모든 정보가 포함됩니다. 다른 인증 방법을 선택할 수도 있습니다.
Step Functions의 AWS 서비스와 통합하는 방법에 대한 자세한 내용은 [ 서비스 통합](integrate-services.md) 및 섹션을 참조하세요[Step Functions의 서비스 API에 파라미터 전달](connect-parameters.md).
**최적화된 API Gateway 통합의 주요 기능**
`apigateway:invoke:` 에는 AWS SDK 서비스 통합과 동등한 기능이 없습니다. 대신 최적화된 API Gateway 서비스에서 API Gateway 엔드포인트를 직접 호출합니다.
## API Gateway 기능 지원
Step Functions API Gateway 통합은 API Gateway 기능 전부가 아닌 일부만 지원합니다. 지원되는 기능에 대한 자세한 목록은 다음을 참조하세요.
+ Step Functions API Gateway REST API 및 API Gateway HTTP API 통합 모두에서 지원됩니다.
+ **권한 부여자**: IAM([Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) 사용), 인증 없음, Lambda 권한 부여자(요청 파라미터 기반 및 사용자 지정 헤더가 있는 토큰 기반)
+ **API 유형**: 리전별
+ **API 관리**: API Gateway API 도메인 이름, API 단계, 경로, 쿼리 파라미터, 요청 본문
+ Step Functions API Gateway HTTP API 통합에서 지원됩니다. 엣지에 최적화된 API에 대한 옵션을 제공하는 Step Functions API Gateway REST API 통합은 지원되지 않습니다.
+ 다음은 Step Functions API Gateway 통합에서 지원되지 않습니다.
+ **권한 부여자**: Amazon Cognito, 기본 Open ID Connect/OAuth 2.0, 토큰 기반 Lambda 권한 부여자를 위한 인증 헤더
+ **API 유형:** 프라이빗
+ **API 관리**: 사용자 지정 도메인 이름
API Gateway, HTTP 및 REST API에 대한 자세한 내용은 다음을 참조하세요.
+ [Amazon API Gateway 개념](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html) 페이지
+ API Gateway 개발자 안내서의 [HTTP API와 REST API 중에서 선택](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html)
## 요청 형식
`Task` 상태 정의를 만들면 Step Functions에서 파라미터를 검증하고 직접 호출을 수행하는 데 필요한 URL을 빌드한 다음 API를 직접적으로 호출합니다. 응답에는 HTTP 상태 코드, 헤더 및 응답 본문이 포함됩니다. 요청 형식에는 필수 및 선택적 파라미터가 있습니다.
### 필수 요청 파라미터
+ `ApiEndpoint`
+ 유형: `String`
+ API Gateway URL의 호스트 이름입니다. 형식은 `.execute-api.region.amazonaws.com`입니다.
API ID에는 영숫자 조합(`0123456789abcdefghijklmnopqrstuvwxyz`)만 사용할 수 있습니다.
+ `Method`
+ 유형: `Enum`
+ HTTP 메서드로, 다음 중 하나여야 합니다.
+ `GET`
+ `POST`
+ `PUT`
+ `DELETE`
+ `PATCH`
+ `HEAD`
+ `OPTIONS`
### 선택적 요청 파라미터
+ `Headers`
+ 유형: `JSON`
+ HTTP 헤더는 같은 키와 연결된 값의 목록을 허용합니다.
+ `Stage`
+ 유형: `String`
+ API가 API Gateway에 배포되는 단계의 이름입니다. `$default` 단계를 사용하는 모든 HTTP API의 경우 선택 사항입니다.
+ `Path`
+ 유형: `String`
+ API 엔드포인트 다음에 추가되는 경로 파라미터입니다.
+ `QueryParameters`
+ 유형: `JSON`
+ 쿼리 문자열은 같은 키와 연결된 값의 목록만 허용됩니다.
+ `RequestBody`
+ 유형: `JSON` 또는 `String`
+ HTTP 요청 본문입니다. 유형은 `JSON` 객체나 `String`일 수 있습니다. `RequestBody`는 `PATCH`, `POST` 및 `PUT` HTTP 메서드에만 지원됩니다.
+ `AllowNullValues`
+ 유형: `BOOLEAN` – 기본값: `false`
+ 기본 설정에서는 요청 입력 상태의 **null** 값이 API로 전송되지 **않습니다**. 다음 예제에서는 `AllowNullValues`가 상태 머신 정의에서 `true`로 설정되지 않는 한 `category` 필드가 요청에 포함되지 **않습니다**.
```
{
"NewPet": {
"type": "turtle",
"price": 123,
"category": null
}
}
```
**참고**
기본적으로 요청 입력 상태가 **null** 값인 필드는 API로 전송되지 **않습니다**. 상태 머신 정의에서 `AllowNullValues`를 `true`로 설정하여 null 값을 API로 강제로 전송할 수 있습니다.
+ `AuthType`
+ 유형: `JSON`
+ 인증 방법입니다. 기본 방법은 `NO_AUTH`입니다. 허용 값은 다음과 같습니다.
+ `NO_AUTH`
+ `IAM_ROLE`
+ `RESOURCE_POLICY`
자세한 내용은 **인증 및 권한 부여**를 참조하세요.
**참고**
보안상의 이유로 현재 다음 HTTP 헤더 키는 허용되지 않습니다.
`X-Forwarded`, `X-Amz` 또는 `X-Amzn` 접두사가 있는 모든 항목
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`
다음 코드 예제에서는 Step Functions를 사용하여 API Gateway를 간접적으로 호출하는 방법을 보여줍니다.
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "GET",
"Headers": {
"key": ["value1", "value2"]
},
"Stage": "prod",
"Path": "bills",
"QueryParameters": {
"billId": ["123456"]
},
"RequestBody": {},
"AuthType": "NO_AUTH"
}
}
```
## 인증 및 권한 부여
다음 인증 방법을 사용할 수 있습니다.
+ **권한 없음**: 권한 부여 방법을 사용하지 않고 API를 직접 호출합니다.
+ **IAM 역할**: 이 메서드를 사용하면 Step Functions에서 상태 머신 역할을 가정하고 [Signature Version 4(SigV4)](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)로 요청에 서명한 다음 API를 직접적으로 호출합니다.
+ **리소스 정책**: Step Functions는 요청을 인증한 다음 API를 직접적으로 호출합니다. 다음을 지정하는 API에 리소스 정책을 연결해야 합니다.
1. API Gateway를 간접적으로 호출할 상태 머신입니다.
**중요**
액세스를 제한하려면 상태 머신을 지정해야 합니다. 그렇지 않으면 API에 대한 **리소스 정책** 인증을 사용하여 API Gateway 요청을 인증하는 모든 상태 머신에 액세스 권한이 부여됩니다.
1. 해당 Step Functions는 API Gateway를 직접적으로 호출하는 서비스입니다(`"Service": "states.amazonaws.com"`).
1. 액세스할 리소스는 다음과 같습니다.
+ *region*
+ 지정된 리전의 *account-id*
+ *api-id*
+ *stage-name*
+ *HTTP-VERB*(메서드)
+ *resource-path-specifier*
리소스 정책 예제는 [Step Functions의 IAM 정책 및 API Gateway](#api-gateway-iam)를 참조하세요.
리소스 형식에 대한 자세한 내용은 API Gateway 개발자 안내서의 [API Gateway의 API 실행 권한의 리소스 형식](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api)을 참조하세요.
**참고**
리소스 정책은 REST API에서만 지원됩니다.
## 서비스 통합 패턴
API Gateway 통합은 두 가지 서비스 통합 패턴을 지원합니다.
+ [요청 및 응답](connect-to-resource.md#connect-default) - 기본 통합 패턴입니다. 이를 사용하면 Step Functions에서 HTTP 응답을 수신한 직후에 다음 단계로 진행할 수 있습니다.
+ [작업 토큰을 사용하여 콜백 대기](connect-to-resource.md#connect-wait-token)(`.waitForTaskToken`) - 페이로드와 함께 작업 토큰이 반환될 때까지 기다립니다. `.waitForTaskToken` 패턴을 사용하려면 다음 예제와 같이 작업 정의의 **리소스** 필드 끝에 .waitForTaskToken을 추가합니다.
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.Task.Token %}"
},
"Stage": "prod",
"Path": "bills/add",
"QueryParameters": {},
"RequestBody": {
"billId": "my-new-bill"
},
"AuthType": "IAM_ROLE"
}
}
```
## 출력 형식
다음 출력 파라미터가 제공됩니다.
| 이름 | Type | 설명 |
| --- | --- | --- |
| ResponseBody | JSON 또는 String | API 직접 호출의 응답 본문입니다. |
| Headers | JSON | 응답 헤더입니다. |
| StatusCode | Integer | 응답의 HTTP 상태 코드입니다. |
| StatusText | String | 응답의 상태 텍스트입니다. |
다음은 응답 예제입니다.
```
{
"ResponseBody": {
"myBills": []
},
"Headers": {
"key": ["value1", "value2"]
},
"StatusCode": 200,
"StatusText": "OK"
}
```
## 오류 처리
오류가 발생하면 다음과 같이 `error` 및 `cause`가 반환됩니다.
+ HTTP 상태 코드를 사용할 수 있는 경우 오류는 `ApiGateway.` 형식으로 반환됩니다.
+ HTTP 상태 코드를 사용할 수 없는 경우 오류는 `ApiGateway.` 형식으로 반환됩니다.
두 경우 모두 `cause`는 문자열로 반환됩니다.
다음 예제에서는 오류가 발생한 응답을 보여줍니다.
```
{
"error": "ApiGateway.403",
"cause": "{\"message\":\"Missing Authentication Token\"}"
}
```
**참고**
`2XX` 상태 코드는 성공을 나타내며 오류는 반환되지 않습니다. 다른 모든 상태 코드나 예외 발생으로 인해 오류가 발생합니다.
## Amazon API Gateway 호출에 대한 IAM 정책
다음 예제 템플릿은가 상태 시스템 정의의 리소스를 기반으로 IAM 정책을 AWS Step Functions 생성하는 방법을 보여줍니다. 자세한 내용은 [Step Functions가 통합 서비스용 IAM 정책을 생성하는 방법](service-integration-iam-templates.md) 및 [Step Functions에서 서비스 통합 패턴 검색](connect-to-resource.md) 섹션을 참조하세요.
*리소스:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
다음 코드 예제에서는 API Gateway를 직접 호출하기 위한 리소스 정책을 보여줍니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "states.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
""
]
}
}
}
]
}
```