Step Functions를 REST APIs 사용하여 API 게이트웨이 생성 - AWS Step Functions

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Step Functions를 REST APIs 사용하여 API 게이트웨이 생성

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

Step Functions의 AWS 서비스와 통합하는 방법에 대한 자세한 내용은 서비스 통합 및 단원을 참조하십시오Step FunctionsAPI의 서비스에 파라미터 전달.

최적화된 API 게이트웨이 통합의 주요 기능
  • apigateway:invoke: 에는 서비스 통합과 AWS SDK 동등한 기능이 없습니다. 대신 최적화된 API 게이트웨이 서비스는 API 게이트웨이 엔드포인트를 직접 호출합니다.

API 게이트웨이 기능 지원

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

  • Step Functions API GatewayRESTAPI와 API Gateway HTTP API 통합 모두에서 지원됩니다.

    • 권한 부여자: IAM (서명 버전 4 사용), 인증 없음, Lambda 권한 부여자(요청 파라미터 기반 및 사용자 지정 헤더가 있는 토큰 기반)

    • API 유형: 리전

    • API 관리: API 게이트웨이 API 도메인 이름, API 단계, 경로, 쿼리 파라미터, 요청 본문

  • Step Functions API Gateway HTTP API 통합에서 지원됩니다. 엣지 최적화 옵션을 제공하는 Step Functions API Gateway REST API 통합APIs은 지원되지 않습니다.

  • Step Functions API Gateway 통합에서 지원되지 않는 기능:

    • 권한 부여자: Amazon Cognito, 기본 Open ID Connect / OAuth 2.0, 토큰 기반 Lambda 권한 부여자에 대한 권한 부여 헤더

    • API 유형: 프라이빗

    • API 관리: 사용자 지정 도메인 이름

API Gateway 및 HTTP 해당 및 REST에 대한 자세한 내용은 다음을 APIs참조하세요.

요청 형식

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

필수 요청 파라미터

  • ApiEndpoint

    • 유형: String

    • API 게이트웨이의 호스트 이름입니다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 Gateway에서이 배포된 단계의 이름API입니다. $default 스테이지를 HTTP API 사용하는의 경우 선택 사항입니다.

  • Path

    • 유형: String

    • API 엔드포인트 뒤에 추가되는 경로 파라미터입니다.

  • QueryParameters

    • 유형: JSON

    • 쿼리 문자열은 같은 키와 연결된 값의 목록만 허용됩니다.

  • RequestBody

    • 유형: JSON 또는 String

    • HTTP 요청 본문입니다. 유형은 JSON 객체 또는 일 수 있습니다String. RequestBodyPATCH, POSTPUT HTTP 메서드에서만 지원됩니다.

  • AllowNullValues

    • 유형: BOOLEAN – 기본값: false

    • 기본 설정에서는 요청 입력 상태의 null 값이 로 전송되지 않습니다API. 다음 예제에서는 AllowNullValues가 상태 시스템 정의에서 true로 설정되지 않는 한 category 필드가 요청에 포함되지 않습니다.

      { "NewPet": { "type": "turtle", "price": 123, "category": null } }
      참고

      기본적으로 null 값이 요청 입력 상태인 필드는 로 전송되지 않습니다API. 상태 시스템 정의true에서를 로 설정API하여 null 값을 AllowNullValues에 강제로 전송할 수 있습니다.

  • 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가 상태 시스템의 역할을 수임하고 서명 버전 4(SigV4)로 요청에 서명한 다음를 호출합니다API.

  • 리소스 정책: Step Functions는 요청을 인증한 다음를 호출합니다API. 다음을 API 지정하는 리소스 정책을에 연결해야 합니다.

    1. API Gateway를 호출할 상태 시스템입니다.

      중요

      액세스를 제한하려면 상태 시스템을 지정해야 합니다. 그렇지 않으면에 대한 리소스 정책 인증으로 API 게이트웨이 요청을 인증하는 모든 상태 시스템에 액세스 권한이 부여API됩니다.

    2. 해당 Step Functions는 API Gateway:를 호출하는 서비스입니다"Service": "states.amazonaws.com".

    3. 액세스할 리소스는 다음과 같습니다.

      • region.

      • 지정된 리전account-id의 .

      • api-id.

      • stage-name.

      • HTTP-VERB (메서드).

      • resource-path-specifier.

    예제 리소스 정책은 IAM Step Functions 및 API Gateway에 대한 정책을 참조하세요.

    리소스 형식에 대한 자세한 내용은 API 게이트웨이 개발자 안내서의 GatewayAPI에서 실행하기 위한 권한의 리소스 형식을 참조하세요. API

    참고

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

서비스 통합 패턴

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

  • 요청 및 응답 - 기본 통합 패턴입니다. 그러면 Step Functions가 HTTP 응답을 받은 직후 다음 단계로 진행할 수 있습니다.

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

    { "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" }

오류 처리

오류가 발생하면 다음과 같이 errorcause가 반환됩니다.

  • HTTP 상태 코드를 사용할 수 있는 경우 오류가 형식으로 반환됩니다ApiGateway.<HTTP Status Code>.

  • HTTP 상태 코드를 사용할 수 없는 경우 오류가 형식으로 반환됩니다ApiGateway.<Exception>.

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

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

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

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

IAM Amazon API Gateway 호출 정책

다음 예제 템플릿은가 상태 시스템 정의의 리소스를 기반으로 IAM 정책을 AWS Step Functions 생성하는 방법을 보여줍니다. 자세한 내용은 Step Functions가 통합 서비스용 IAM 정책을 생성하는 방법Step Functions에서 서비스 통합 패턴 검색 단원을 참조하세요.

리소스:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:[[region]]:[[accountId]]:*" ] } ] }

다음 코드 예제는 API Gateway를 호출하기 위한 리소스 정책을 보여줍니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:<region>:<account-id>:<api-id>/<stage-name>/<HTTP-VERB>/<resource-path-specifier>", "Condition": { "StringEquals": { "aws:SourceArn": [ "<SourceStateMachineArn>" ] } } } ] }