API Gateway 기능 지원 요청 형식 인증 및 권한 부여 서비스 통합 패턴 출력 형식 오류 처리

Step Functions를 사용하여 API Gateway 직접 호출

Step Functions는 Amazon States Language (ASL) 에서 직접 특정 AWS 서비스를 제어할 수 있습니다. 자세한 내용은 다른 서비스와 함께 사용 및 파라미터를 서비스 API에 전달 섹션을 참조하세요.

최적화된 API 게이트웨이 통합과 API Gateway AWS SDK 통합의 차이점

apigateway:invoke: AWS SDK 서비스 통합에는 이에 상응하는 기능이 없습니다. 대신 최적화된 API Gateway 서비스에서 API Gateway 엔드포인트를 직접 호출합니다.

Amazon API Gateway를 사용하여 HTTP 및 REST API를 생성, 게시, 유지 및 모니터링합니다. API Gateway와 통합하려면 코드를 작성하거나 다른 인프라를 사용하지 않고도 API Gateway HTTP 또는 API Gateway REST 엔드포인트를 직접 호출하는 Step Functions에서 Task 상태를 정의합니다. Task 상태 정의에는 API 직접 호출에 필요한 모든 정보가 포함됩니다. 다른 인증 방법을 선택할 수도 있습니다.

참고

Step Functions는 API Gateway를 통해 HTTP 엔드포인트를 호출할 수 있지만 현재 일반 HTTP 엔드포인트를 직접적으로 호출할 수는 없습니다.

API Gateway 기능 지원

Step Functions API Gateway 통합은 API Gateway 기능 전부가 아닌 일부만 지원합니다. 지원되는 기능에 대한 자세한 목록은 다음을 참조하세요.

Step Functions API Gateway REST API 및 API Gateway HTTP API 통합 모두에서 지원됩니다.
- 권한 부여자: IAM(Signature Version 4 사용), 인증 없음, 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 개념 페이지
API Gateway 개발자 안내서의 HTTP API와 REST API 중에서 선택

요청 형식

Task 상태 정의를 만들면 Step Functions에서 파라미터를 검증하고 직접 호출을 수행하는 데 필요한 URL을 빌드한 다음 API를 직접적으로 호출합니다. 응답에는 HTTP 상태 코드, 헤더 및 응답 본문이 포함됩니다. 요청 형식에는 필수 및 선택적 파라미터가 있습니다.

필수 요청 파라미터

ApiEndpoint
- 유형: String
- API Gateway URL의 호스트 이름입니다. 형식은 <API ID>.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
- AllowNullValues를 true로 설정하면 다음과 같은 null 값을 전달할 수 있습니다.
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "name": null
    }
}
```
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", 
    "Parameters": {
        "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)로 요청에 서명한 다음 API를 직접적으로 호출합니다.
리소스 정책: Step Functions는 요청을 인증한 다음 API를 직접적으로 호출합니다. 다음을 지정하는 API에 리소스 정책을 연결해야 합니다.
1. API Gateway를 간접적으로 호출할 상태 시스템입니다.
  
  중요
  액세스를 제한하려면 상태 시스템을 지정해야 합니다. 그렇지 않으면 API에 대한 리소스 정책 인증을 사용하여 API Gateway 요청을 인증하는 모든 상태 시스템에 액세스 권한이 부여됩니다.
2. 해당 Step Functions는 API Gateway를 직접적으로 호출하는 서비스입니다("Service": "states.amazonaws.com").
3. 액세스할 리소스는 다음과 같습니다.
  - region
  - 지정된 리전의 account-id
  - api-id
  - stage-name
  - HTTP-VERB(메서드)
  - . resource-path-specifier
리소스 정책 예제는 Step Functions의 IAM 정책 및 API Gateway를 참조하세요.

리소스 형식에 대한 자세한 내용은 API Gateway 개발자 안내서의 API Gateway의 API 실행 권한의 리소스 형식을 참조하세요.

참고
리소스 정책은 REST API에서만 지원됩니다.

서비스 통합 패턴

API Gateway 통합은 두 가지 서비스 통합 패턴을 지원합니다.

요청 및 응답 - 기본 통합 패턴입니다. 이를 사용하면 Step Functions에서 HTTP 응답을 수신한 직후에 다음 단계로 진행할 수 있습니다.

작업 토큰을 사용하여 콜백 대기(.waitForTaskToken) - 페이로드와 함께 작업 토큰이 반환될 때까지 기다립니다. .waitForTaskToken패턴을 사용하려면 추가하십시오. waitForTask다음 예와 같이 작업 정의의 Resource 필드 끝에 토큰을 입력합니다.


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
    "Parameters": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "POST", 
        "Headers": { 
            "TaskToken.$": "States.Array($$.Task.Token)"
        },
        "Stage": "prod",
        "Path": "bills/add",
        "QueryParameters": {},
        "RequestBody": {
            "billId": "my-new-bill"
        },
        "AuthType": "IAM_ROLE"
    } 
}

출력 형식

다음 출력 파라미터가 제공됩니다.

명칭	유형	설명
`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 Status Code> 형식으로 반환됩니다.
HTTP 상태 코드를 사용할 수 없는 경우 오류는 ApiGateway.<Exception> 형식으로 반환됩니다.

두 경우 모두 cause는 문자열로 반환됩니다.

다음 예제에서는 오류가 발생한 응답을 보여줍니다.


{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}

참고

2XX 상태 코드는 성공을 나타내며 오류는 반환되지 않습니다. 다른 모든 상태 코드나 예외 발생으로 인해 오류가 발생합니다.

자세한 내용은 다음을 참조하세요.

API Gateway 개발자 안내서의 Amazon API Gateway 개념
아마존 API 게이트웨이에 대한 IAM 정책
API Gateway 직접 호출하는 방법을 보여주는 샘플 프로젝트

API Gateway 개발자 안내서의 Amazon API Gateway 개념

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

최적화된 통합

Amazon Athena