타사 API 호출 - AWS Step Functions
HTTP 태스크 정의HTTP 태스크 필드HTTP 태스크에 대한 인증EventBridge 연결 및 HTTP 태스크 정의 데이터 병합요청 본문에 URL 인코딩 적용HTTP 태스크를 실행하기 위한 IAM 권한HTTP 태스크 예제HTTP 태스크 테스트지원되지 않는 HTTP 태스크 응답

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

타사 API 호출

HTTP 태스크는 워크플로에서 Salesforce 및 Stripe 등 모든 퍼블릭 타사 API를 호출할 수 있는 일종의 작업 상태입니다. 타사 API를 호출하려면 arn:aws:states:::http:invoke 리소스와 함께 태스크 상태를 사용합니다. 그런 다음 API URL, 사용할 방법, 인증 세부 정보 등 API 엔드포인트 구성 세부 정보를 입력합니다.

Workflow Studio를 사용하여 HTTP 태스크가 포함된 상태 머신을 빌드하는 경우, Workflow Studio는 HTTP 태스크에 대한 IAM 정책이 포함된 실행 역할을 자동으로 생성합니다. 자세한 정보는 Workflow Studio에서 HTTP 태스크를 테스트하기 위한 역할을 참조하세요.

HTTP 태스크 정의

ASL 정의는 http:invoke 리소스가 있는 HTTP 태스크를 나타냅니다. 다음 HTTP 태스크 정의는 모든 고객 목록을 반환하는 Stripe API를 호출합니다.

"Call third-party API": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.stripe.com/v1/customers",
    "Authentication": {
      "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

HTTP 태스크 필드

HTTP 태스크의 정의에는 다음 필드가 포함됩니다.

Resource(필수)

태스크 유형을 지정하려면 Resource 필드에 해당 ARN을 입력합니다. HTTP 태스크의 경우 다음과 같이 Resource 필드를 지정합니다.

"Resource": "arn:aws:states:::http:invoke"
Parameters(필수)

호출하려는 타사 API에 대한 정보를 입력하는 ApiEndpoint, Method, ConnectionArn 필드가 포함되어 있습니다. Parameters에는 Headers, QueryParameters 등 옵션 필드도 포함되어 있습니다.

ParametersParameters필드에서와 같이 정적 JSON과 JsonPath구문의 조합을 지정할 수 있습니다. 자세한 정보는 파라미터를 서비스 API에 전달을 참조하세요.

ApiEndpoint(필수)

호출하려는 타사 API의 URL을 지정합니다. URL에 쿼리 파라미터를 추가하려면 QueryParameters 필드를 사용합니다. 다음 예제에서는 Stripe API를 호출하여 모든 고객 목록을 가져오는 방법을 보여 줍니다.

"ApiEndpoint":"https://api.stripe.com/v1/customers"

JsonPath구문을 사용하여 타사 API URL이 포함된 JSON 노드를 선택하여 참조 경로를 지정할 수도 있습니다. 예를 들어 특정 고객 ID를 사용하여 Stripe의 API 중 하나를 호출하고 싶다고 가정해 보겠습니다. 다음 상태 입력을 제공했다고 생각해 보세요.

{
    "customer_id": "1234567890",
    "name": "John Doe"
}

Stripe API를 사용하여 이 고객 ID의 세부 정보를 검색하려면 다음 예제와 같이 ApiEndpoint를 지정합니다. 이 예제에서는 내장 함수와 참조 경로를 사용합니다.

"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"

런타임 시 Step Functions는 다음처럼 ApiEndpoint 값을 확인합니다.

https://api.stripe.com/v1/customers/1234567890
Method(필수)

타사 API를 호출하는 데 사용할 HTTP 메서드를 지정합니다. HTTP 태스크에서 GET, POST, POST, POST, POST, POST, HEAD 중 하나를 지정할 수 있습니다.

예를 들어 GET 메서드를 사용하려면 다음과 같이 Method 필드를 지정합니다.

"Method": "GET"

참조 경로를 사용하여 런타임에 메서드를 지정할 수도 있습니다. 예를 들어 "Method.$": "$.myHTTPMethod"입니다.

Authentication(필수)

타사 API 호출을 인증하는 방법을 지정하는 ConnectionArn 필드를 포함합니다. Step Functions는 Amazon EventBridge의 연결 리소스를 사용하여 특정 ApiEndpoint의 인증을 지원합니다.

ConnectionArn(필수)

EventBridge 연결 ARN을 지정합니다.

HTTP 태스크에는 API 제공자의 인증 자격 증명을 안전하게 관리하는 EventBridge 연결이 필요합니다. 연결은 타사 API를 인증하는 데 사용할 권한 부여 유형과 보안 인증을 지정합니다. 연결을 사용하면 API 키 등의 암호가 상태 머신 정의에 하드 코딩되는 것을 방지할 수 있습니다. 연결 시 Headers, QueryParameters, RequestBody 파라미터를 지정할 수도 있습니다.

EventBridge 연결을 생성할 때 인증 세부 정보를 제공합니다. HTTP 태스크에서 인증이 작동하는 방식에 대한 자세한 내용은 HTTP 태스크에 대한 인증 섹션을 참조하세요.

다음 예제는 HTTP 태스크 정의에서 Authentication 필드를 지정하는 방법을 보여 줍니다.

"Authentication": {
  "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
}
Headers (선택 사항)

API 엔드포인트에 추가 컨텍스트와 메타데이터를 입력합니다. 헤더를 문자열 또는 JSON 배열로 지정할 수 있습니다.

EventBridge 연결에서 헤더를 지정하고 HTTP 태스크에서 Headers 필드를 지정할 수 있습니다. Headers 필드에는 API 공급자에 대한 인증 세부 정보를 포함하지 않는 것이 좋습니다. 이러한 세부 정보는 EventBridge 연결에 포함하기 바랍니다.

Step Functions는 EventBridge 연결에서 지정한 헤더를 HTTP 태스크 정의에서 지정한 헤더에 추가합니다. 정의 및 연결에 동일한 헤더 키가 있는 경우, Step Functions는 EventBridge 연결에 지정된 해당 값을 해당 헤더에 사용합니다. Step Functions가 데이터 병합을 수행하는 방법에 대한 자세한 내용은 EventBridge 연결 및 HTTP 태스크 정의 데이터 병합 섹션을 참조하세요.

다음 예제는 타사 API 호출에 포함될 헤더를 지정합니다. content-type 

"Headers": {
  "content-type": "application/json"
}

참조 경로를 사용하여 런타임에 헤더를 지정할 수도 있습니다. 예를 들어 "Headers.$": "$.myHTTPHeaders"입니다.

Step Functions는 User-Agent, Range, Host 헤더를 설정합니다. Step Functions는 호출하는 API를 기반으로 Host 헤더 값을 설정합니다. 다음은 이러한 헤더 값의 예제입니다.

User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1,
Range: bytes=0-262144,
Host: api.stripe.com

HTTP 태스크 정의에는 다음 헤더를 사용할 수 없습니다. 이러한 헤더를 사용하면 HTTP 태스크에 States.Runtime 오류가 발생하여 실패합니다.

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • 연결

  • Content-Encoding

  • Content-MD5

  • 날짜

  • Expect

  • 전달됨

  • From

  • Host

  • HTTP2-Settings

  • If-Match

  • If-Modified-Since

  • If-None-Match

  • If-Range

  • If-Unmodified-Since

  • Max-Forwards

  • 오리진(Origin)

  • Pragma

  • Proxy-Authorization

  • 참조자

  • Server

  • TE

  • 트레일러

  • Transfer-Encoding

  • 업그레이드

  • Via

  • 경고

  • x-forwarded-*

  • x-amz-*

  • x-amzn-*

QueryParameters (선택 사항)

API URL 끝에 키-값 쌍을 삽입합니다. 쿼리 파라미터를 문자열, JSON 배열 또는 JSON 객체로 지정할 수 있습니다. Step Functions는 타사 API를 호출할 때 쿼리 파라미터를 자동으로 URL로 인코딩합니다.

예를 들어 Stripe API를 호출하여 미국 달러(USD)로 거래를 하는 고객을 검색한다고 가정해 보겠습니다. 다음 QueryParameters를 상태 입력으로 제공했다고 생각해 보세요.

"QueryParameters": {
  "currency": "usd"
}

런타임 시 Step Functions는 다음과 같이 API URL에 QueryParameters를 추가합니다.

https://api.stripe.com/v1/customers/search?currency=usd

참조 경로를 사용하여 런타임에 쿼리 파라미터를 지정할 수도 있습니다. 예를 들어 "QueryParameters.$": "$.myQueryParameters"입니다.

EventBridge 연결에서 쿼리 파라미터를 지정한 경우 Step Functions는 HTTP 태스크 정의에서 지정한 쿼리 파라미터에 이러한 쿼리 파라미터를 추가합니다. 정의 및 연결에 동일한 쿼리 파라미터 키가 있는 경우, Step Functions는 EventBridge 연결에 지정된 해당 값을 해당 헤더에 사용합니다. Step Functions가 데이터 병합을 수행 방법에 대한 자세한 내용은 EventBridge 연결 및 HTTP 태스크 정의 데이터 병합 섹션을 참조하세요.

Transform (선택 사항)

RequestBodyEncoding 및 RequestEncodingOptions 필드를 포함합니다. 기본적으로 Step Functions는 요청 본문을 JSON 데이터로 API 엔드포인트에 보냅니다.

API 공급자가 form-urlencoded 요청 본문을 수락하는 경우 Transform 필드를 사용하여 요청 본문의 URL 인코딩을 지정합니다. 또한 content-type 헤더를 application/x-www-form-urlencoded로 지정해야 합니다. 그러면 Step Functions는 요청 본문을 자동으로 URL로 인코딩합니다.

RequestBodyEncoding

요청 본문의 URL 인코딩을 지정합니다. NONE 또는 URL_ENCODED 값 중 하나를 지정할 수 있습니다.

  • NONE - HTTP 요청 본문은 RequestBody 필드의 직렬화된 JSON이 됩니다. 이것이 기본값입니다.

  • URL_ENCODED - HTTP 요청 본문은 RequestBody 필드의 URL로 인코딩된 양식 데이터입니다.

RequestEncodingOptions

RequestBodyEncoding을 URL_ENCODED로 설정한 경우 요청 본문의 배열에 사용할 인코딩 옵션을 결정합니다.

Step Functions는 다음의 배열 인코딩 옵션을 지원합니다. 이러한 옵션에 대한 자세한 정보와 예제는 요청 본문에 URL 인코딩 적용 섹션을 참조하세요.

  • INDICES - 배열 요소의 인덱스 값을 사용하여 배열을 인코딩합니다. 기본적으로 Step Functions는 이 인코딩 옵션을 사용합니다.

  • REPEAT - 배열의 각 항목에서 키를 반복합니다.

  • COMMAS - 키의 모든 값을 쉼표로 구분된 값 목록으로 인코딩합니다.

  • BRACKETS - 배열의 각 항목에서 키를 반복하고 키에 대괄호([])를 추가하여 배열임을 나타냅니다.

다음 예제에서는 요청 본문 데이터의 URL 인코딩을 설정합니다. 또한 요청 본문의 배열에 COMMAS 인코딩 옵션을 사용하도록 지정합니다.

"Transform": {
  "RequestBodyEncoding": "URL_ENCODED",
  "RequestEncodingOptions": {
    "ArrayFormat": "COMMAS"
  }
}
RequestBody (선택 사항)

상태 입력에 입력하는 JSON 데이터를 수용합니다. RequestBody에서는 정적 JSON과 JsonPath구문의 조합을 지정할 수 있습니다. 예를 들어 다음 상태 입력을 제공한다고 가정해 봅니다.

{
    "CardNumber": "1234567890",
    "ExpiryDate": "09/25"
}

런타임 시 요청 본문에서 CardNumber 및 ExpiryDate의 이러한 값을 사용하려면 요청 본문에 다음의 JSON 데이터를 지정하면 됩니다.

"RequestBody": {
  "Card": {
    "Number.$": "$.CardNumber",
    "Expiry.$": "$.ExpiryDate",
    "Name": "John Doe",
    "Address": "123 Any Street, Any Town, USA"
  }
}

호출하려는 타사 API에 form-urlencoded 요청 본문이 필요한 경우 요청 본문 데이터에 URL 인코딩을 지정해야 합니다. 자세한 정보는 요청 본문에 URL 인코딩 적용을 참조하세요.

HTTP 태스크에 대한 인증

HTTP 태스크에는 API 제공자의 인증 자격 증명을 안전하게 관리하는 EventBridge 연결이 필요합니다. 연결은 타사 API를 인증하는 데 사용할 권한 부여 유형과 보안 인증을 지정합니다. 연결을 사용하면 API 키 등의 암호가 상태 머신 정의에 하드 코딩되는 것을 방지할 수 있습니다. EventBridge 연결은 기본, OAuth 및 API 키 인증 체계를 지원합니다.

EventBridge 연결을 생성할 때 인증 세부 정보를 제공합니다. 또한 API에 대한 권한 부여에 필요한 헤더, 본문 및 쿼리 파라미터를 포함할 수 있습니다. 타사 API를 호출하는 모든 HTTP 태스크에 연결 ARN을 포함해야 합니다.

연결을 생성하고 권한 부여 매개변수를 추가하면 비밀이 EventBridge 생성됩니다 AWS Secrets Manager. 이 시크릿에는 연결 및 권한 부여 파라미터를 암호화된 형태로 EventBridge 저장합니다. 연결을 성공적으로 만들거나 업데이트하려면 Secrets Manager를 사용할 권한이 AWS 계정 있는 서버를 사용해야 합니다. 상태 머신이 EventBridge 연결에 액세스하는 데 필요한 IAM 권한에 대한 자세한 내용은 을 참조하십시오HTTP 태스크를 실행하기 위한 IAM 권한.

다음 이미지는 Step Functions가 EventBridge 연결을 사용하여 타사 API 호출에 대한 권한 부여를 처리하는 방법을 보여 줍니다.

프로세스 Step Functions는 EventBridge 연결을 사용하여 타사 API 공급자의 권한 부여 보안 인증을 관리합니다. EventBridge는 연결 및 권한 부여 파라미터를 암호화된 형식으로 저장하기 위해 Secrets Manager에 암호를 생성합니다.

EventBridge 연결 및 HTTP 태스크 정의 데이터 병합

HTTP 태스크를 호출할 때 EventBridge 연결 및 HTTP 태스크 정의의 데이터를 지정할 수 있습니다. 이 데이터에는Headers, QueryParameters, RequestBody 파라미터가 포함됩니다. 타사 API를 호출하기 전에 Step Functions는 요청 본문이 문자열이고 연결 본문 파라미터가 비어 있지 않은 경우를 제외하고 모든 경우에 요청 본문을 연결 본문 파라미터와 병합합니다. 이 경우 HTTP 태스크에 States.Runtime 오류가 발생하여 실패합니다.

HTTP 태스크 정의 및 EventBridge 연결에 지정된 중복 키가 있는 경우 Step Functions는 HTTP 태스크의 값을 연결의 값으로 덮어씁니다.

다음 목록에는 타사 API를 호출하기 전에 Step Functions가 데이터를 병합하는 방법이 나와 있습니다.

  • 헤더 - Step Functions는 연결에서 지정한 헤더를 HTTP 태스크의 Headers 필드에 있는 헤더에 추가합니다. 헤더 키 간에 충돌이 있으면 Step Functions는 연결에 지정된 값을 해당 헤더에 사용합니다. 예를 들어 HTTP 태스크 정의와 EventBridge 연결 모두에서 content-type 헤더를 지정한 경우 Step Functions는 연결에 지정된 content-type 헤더 값을 사용합니다.

  • 쿼리 파라미터 - Step Functions는 연결에서 지정한 모든 쿼리 파라미터를 HTTP 태스크의 QueryParameters 필드에 있는 쿼리 파라미터에 추가합니다. 쿼리 파라미터 키 간에 충돌이 있으면 Step Functions는 연결에 지정된 값을 해당 쿼리 파라미터에 사용합니다. 예를 들어 HTTP 태스크 정의와 EventBridge 연결 모두에서 maxItems 쿼리 파라미터를 지정한 경우 Step Functions는 연결에 지정된 maxItems 쿼리 파라미터 값을 사용합니다.

  • 본문 파라미터

    • Step Functions는 연결에 지정된 모든 요청 본문 값을 HTTP 태스크의 RequestBody 필드에 있는 요청 본문에 추가합니다. 요청 본문 키 간에 충돌이 있으면 Step Functions는 연결에 지정된 값을 요청 본문에 사용합니다. 예를 들어 HTTP 태스크 정의와 EventBridge 연결 모두에서 RequestBody의 Mode 필드를 지정했다고 가정해 봅니다. Step Functions는 연결에 지정된 Mode 필드 값을 사용합니다.

    • 요청 본문을 JSON 객체 대신 문자열로 지정하고 EventBridge 연결에 요청 본문도 포함된 경우 Step Functions는 두 위치에 지정된 요청 본문을 병합할 수 없습니다. States.Runtime 오류가 발생하여 HTTP 태스크가 실패합니다.

    Step Functions는 요청 본문 병합이 완료된 후 모든 변환을 적용하고 요청 본문을 직렬화합니다.

다음 예제에서는 HTTP 태스크와 EventBridge 연결 모두에서 Headers, QueryParameters, RequestBody 필드를 설정합니다.

HTTP 태스크 정의

{
  "Comment": "Data merging example for HTTP Task and EventBridge connection",
  "StartAt": "ListCustomers",
  "States": {
    "ListCustomers": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "Authentication": {
          "ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "ApiEndpoint": "https:/example.com/path",
        "Method": "GET",
        "Headers": {
          "Request-Id": "my_request_id",
          "Header-Param": "state_machine_header_param"
        },
        "RequestBody": {
          "Job": "Software Engineer",
          "Company": "AnyCompany",
          "BodyParam": "state_machine_body_param"
        },
        "QueryParameters": {
          "QueryParam": "state_machine_query_param"
        }
      }
    }
  }
}

EventBridge 연결

{
  "AuthorizationType": "API_KEY",
  "AuthParameters": {
    "ApiKeyAuthParameters": {
      "ApiKeyName": "ApiKey",
      "ApiKeyValue": "key_value"
    },
    "InvocationHttpParameters": {
      "BodyParameters": [
        {
          "Key": "BodyParam",
          "Value": "connection_body_param"
        }
      ],
      "HeaderParameters": [
        {
          "Key": "Header-Param",
          "Value": "connection_header_param"
        }
      ],
      "QueryStringParameters": [
        {
          "Key": "QueryParam",
          "Value": "connection_query_param"
        }
      ]
    }
  }
}

이 예시에서는 HTTP 태스크 및 EventBridge 연결에 중복 키가 지정됩니다. 따라서 Step Functions는 HTTP 태스크의 값을 연결의 값으로 덮어씁니다. 다음 코드 조각은 Step Functions가 타사 API로 보내는 HTTP 요청을 보여 줍니다.

POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

요청 본문에 URL 인코딩 적용

기본적으로 Step Functions는 요청 본문을 JSON 데이터로 API 엔드포인트에 보냅니다. 타사 API 공급자가 form-urlencoded 요청 본문을 요구하는 경우 요청 본문에 URL 인코딩을 지정해야 합니다. 그러면 Step Functions는 선택한 URL 인코딩 옵션에 따라 요청 본문을 자동으로 URL로 인코딩합니다.

Transform 필드를 사용하여 URL 인코딩을 지정합니다. 이 필드에는 요청 본문에 URL 인코딩을 적용할지 여부를 지정하는 RequestBodyEncoding 필드가 포함됩니다. RequestBodyEncoding 필드를 지정하면 타사 API를 호출하기 전에 JSON 요청 본문이 Step Functions 요청 본문으로 변환됩니다. 또한 URL로 인코딩된 데이터를 수용하는 API는 content-type 헤더를 예상하기 때문에 content-type 헤더를 application/x-www-form-urlencoded로 지정해야 합니다.

요청 본문에 배열을 인코딩하기 위해 Step Functions는 다음의 배열 인코딩 옵션을 제공합니다.

  • INDICES - 배열의 각 항목에서 키를 반복하고 키에 대괄호([])를 추가하여 배열임을 나타냅니다. 이 대괄호에는 배열 요소의 인덱스가 포함됩니다. 인덱스를 추가하면 배열 요소의 순서를 지정하는 데 도움이 됩니다. 기본적으로 Step Functions는 이 인코딩 옵션을 사용합니다.

    예를 들어 요청 본문에 다음 배열이 포함된 경우를 알아봅니다.

    {"array": ["a","b","c","d"]}

    Step Functions는 배열을 다음 문자열로 인코딩합니다.

    array[0]=a&array[1]=b&array[2]=c&array[3]=d

  • REPEAT - 배열의 각 항목에서 키를 반복합니다.

    예를 들어 요청 본문에 다음 배열이 포함된 경우를 알아봅니다.

    {"array": ["a","b","c","d"]}

    Step Functions는 배열을 다음 문자열로 인코딩합니다.

    array=a&array=b&array=c&array=d

  • COMMAS - 키의 모든 값을 쉼표로 구분된 값 목록으로 인코딩합니다.

    예를 들어 요청 본문에 다음 배열이 포함된 경우를 알아봅니다.

    {"array": ["a","b","c","d"]}

    Step Functions는 배열을 다음 문자열로 인코딩합니다.

    array=a,b,c,d

  • BRACKETS - 배열의 각 항목에서 키를 반복하고 키에 대괄호([])를 추가하여 배열임을 나타냅니다.

    예를 들어 요청 본문에 다음 배열이 포함된 경우를 알아봅니다.

    {"array": ["a","b","c","d"]}

    Step Functions는 배열을 다음 문자열로 인코딩합니다.

    array[]=a&array[]=b&array[]=c&array[]=d

HTTP 태스크를 실행하기 위한 IAM 권한

상태 머신 실행 역할에는 타사 API를 호출하기 위한 HTTP 태스크에 대한 states:InvokeHTTPEndpoint, events:RetrieveConnectionCredentials, secretsmanager:GetSecretValue, secretsmanager:DescribeSecret 권한이 있어야 합니다. 다음 IAM 정책 예제에서는 Stripe API를 호출하기 위해 상태 머신 역할에 필요한 최소 권한을 부여합니다. 또한 이 IAM 정책은 Secrets Manager에 저장된 이 EventBridge 연결의 암호를 포함하여 특정 연결에 액세스할 수 있는 권한을 상태 시스템 역할에 부여합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "states:InvokeHTTPEndpoint",
            "Resource": "arn:aws:states:us-east-2:123456789012:stateMachine:myStateMachine",
            "Condition": {
                "StringEquals": {
                    "states:HTTPMethod": "GET"
                },
                "StringLike": {
                    "states:HTTPEndpoint": "https://api.stripe.com/*"
                }
            }
        },
        {
            "Sid": "Statement2",
            "Effect": "Allow",
            "Action": [
                "events:RetrieveConnectionCredentials",
            ],
            "Resource": "arn:aws:events:us-east-2:123456789012:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
        },
        {
            "Sid": "Statement3",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

HTTP 태스크 예제

다음 상태 머신 정의는 Headers, QueryParameters, Transform, RequestBody 파라미터가 포함된 HTTP 태스크를 보여 줍니다. HTTP 태스크는 Stripe API(https://api.stripe.com/v1/invoices)를 호출하여 인보이스를 생성합니다. 또한 HTTP 태스크는 INDICES 인코딩 옵션을 사용하여 요청 본문의 URL 인코딩을 지정합니다.

EventBridge 연결을 생성했는지 확인하세요. 다음 예제에서는 BASIC 권한 부여 유형을 사용하여 만든 연결을 보여 줍니다.

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

기울임꼴 텍스트를 리소스별 정보로 바꿔야 합니다.

{
  "Comment": "A state machine that uses HTTP Task",
  "StartAt": "CreateInvoiceAPI",
  "States": {
    "CreateInvoiceAPI": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "ApiEndpoint": "https://api.stripe.com/v1/invoices",
        "Method": "POST",
        "Authentication": {
          "ConnectionArn": ""arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "Headers": {
          "Content-Type": "application/x-www-form-urlencoded"
        },
        "RequestBody": {
          "customer.$": "$.customer_id",
          "description": "Monthly subscription",
          "metadata": {
            "order_details": "monthly report data"
          }
        },
        "Transform": {
          "RequestBodyEncoding": "URL_ENCODED",
          "RequestEncodingOptions": {
            "ArrayFormat": "INDICES"
          }
        }
      },
      "Retry": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.429",
            "States.Http.StatusCode.503",
            "States.Http.StatusCode.504",
            "States.Http.StatusCode.502"
          ],
          "BackoffRate": 2,
          "IntervalSeconds": 1,
          "MaxAttempts": 3,
          "JitterStrategy": "FULL"
        }
      ],
      "Catch": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.404",
            "States.Http.StatusCode.400",
            "States.Http.StatusCode.401",
            "States.Http.StatusCode.409",
            "States.Http.StatusCode.500"
          ],
          "Comment": "Handle all non 200 ",
          "Next": "HandleInvoiceFailure"
        }
      ],
      "End": true
    }
  }
}

이 상태 머신을 실행하려면 다음 예제와 같이 고객 ID를 입력합니다.

{
    "customer_id": "1234567890"
}

다음 예제는 Step Functions가 Stripe API로 보내는 HTTP 요청을 보여 줍니다.

POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

HTTP 태스크 테스트

콘솔, SDK 또는 를 통해 TestStateAPI를 사용하여 HTTP 태스크를 AWS CLI 테스트할 수 있습니다. 다음 절차는 Step Functions 콘솔에서 TestState API를 사용하는 방법을 설명합니다. HTTP 태스크가 예상대로 작동할 때까지 API 요청, 응답 및 권한 부여 세부 정보를 반복해서 테스트할 수 있습니다.

Step Functions 콘솔에서 HTTP 태스크 상태 테스트

  1. Step Functions 콘솔을 엽니다.

  2. 상태 머신 생성을 선택하여 상태 머신 생성을 시작하거나 HTTP 태스크가 포함된 기존 상태 머신을 선택합니다.

    기존 상태 머신에서 태스크를 테스트하는 경우 4단계를 참조하세요.

  3. Workflow Studio의 디자인 모드에서 HTTP 태스크를 시각적으로 구성합니다. 또는 코드 모드를 선택하여 로컬 개발 환경에서 상태 머신 정의를 복사하여 붙여넣을 수 있습니다.

  4. 디자인 모드인 Workflow Studio의 Inspector 패널에서 테스트 상태를 선택합니다.

  5. 테스트 상태 대화 상자에서 다음을 수행합니다.

    1. 실행 역할에서 상태를 테스트할 실행 역할을 선택합니다. HTTP 태스크에 대해 충분한 권한을 갖춘 역할이 없으면 Workflow Studio에서 HTTP 태스크를 테스트하기 위한 역할 섹션을 확인하여 역할을 생성합니다.

    2. (선택 사항) 선택한 상태에서 테스트에 필요한 모든 JSON 입력을 제공합니다.

    3. 검사 레벨에서 기본값인 정보를 그대로 유지합니다. 이 레벨은 API 직접 호출 및 상태 출력의 상태를 보여 줍니다. 이는 API 응답을 빠르게 확인하는 데 유용합니다.

    4. 테스트 시작을 선택합니다.

    5. 테스트가 성공하면 상태 출력이 테스트 상태 대화 상자 오른쪽에 나타납니다. 테스트가 실패하면 오류가 나타납니다.

      대화 상자의 상태 세부 정보 탭에서 상태 정의와 EventBridge 연결 링크를 볼 수 있습니다.

    6. 검사 레벨을 추적으로 변경합니다. 이 레벨은 원시 HTTP 요청 및 응답을 보여 주며 헤더, 쿼리 파라미터 및 기타 API별 세부 정보를 확인하는 데 유용합니다.

    7. 비밀 공개 확인란을 선택합니다. 이 설정을 추적과 함께 사용하면 API 키와 같이 EventBridge 연결에 삽입되는 민감한 데이터를 볼 수 있습니다. 콘솔에 액세스하는 데 사용하는 IAM 사용자 ID에는 states:RevealSecrets 작업을 수행할 권한이 있어야 합니다. 이 권한이 없으면 Step Functions에서 테스트가 시작될 때 액세스 거부 오류가 발생합니다. IAM 권한을 설정하는 states:RevealSecrets 정책에 대한 예제는 IAM TestState API 사용 권한 섹션을 참조하세요.

      다음 이미지는 성공한 HTTP 태스크 테스트를 보여 줍니다. 이 상태의 검사 레벨은 TRACE로 설정되어 있습니다. 다음 이미지의 HTTP 요청 및 응답 탭은 타사 API 호출의 결과를 보여 줍니다.

      추적 레벨의 테스트에 성공한 일부 상태의 출력입니다.

    8. 테스트 시작을 선택합니다.

    9. 테스트가 성공하면 HTTP 요청 및 응답 탭에서 HTTP 세부 정보를 볼 수 있습니다.

지원되지 않는 HTTP 태스크 응답

반환된 응답이 다음 조건 중 하나에 해당하면 HTTP 태스크에서 States.Runtime 오류가 발생하여 작업이 실패합니다.

  • 응답에는 application/octet-stream, image/*, video/*, audio/*의 콘텐츠 유형 헤더가 포함되어 있습니다.

  • 응답은 유효한 문자열로 읽을 수 없습니다. 이진 데이터 또는 이미지 데이터를 예로 들 수 있습니다.