Step Functions APIs 워크플로에서 서드파티 호출하기

HTTP태스크는 워크플로우에서 Salesforce 및 Stripe와 같은 공용API, 제3자를 호출할 수 있는 작업 워크플로 상태 상태 유형입니다. API제3자에게 전화를 걸려면 리소스와 함께 태스크 상태를 사용하세요. arn:aws:states:::http:invoke 그런 다음, 사용할 방법 APIURL, 인증 세부 정보와 같은 API 엔드포인트 구성 세부 정보를 제공합니다.

Workflow Studio를 사용하여 HTTP 태스크가 포함된 상태 머신을 빌드하는 경우 Workflow Studio는 해당 HTTP 작업에 대한 IAM 정책이 포함된 실행 역할을 자동으로 생성합니다. 자세한 내용은 워크플로 스튜디오에서 HTTP 태스크를 테스트하기 위한 역할 단원을 참조하십시오.

HTTP작업 정의

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

"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태스크의 정의에는 다음 필드가 포함됩니다.

태스크에 대한 인증 HTTP

HTTP태스크에는 API 공급자의 인증 자격 증명을 안전하게 관리하는 EventBridge 연결이 필요합니다. 연결은 API 제3자를 인증하는 데 사용할 인증 유형과 자격 증명을 지정합니다. 연결을 사용하면 API 키와 같은 암호를 상태 시스템 정의에 하드 코딩하지 않아도 됩니다. EventBridge 연결은 기본OAuth, API 키 권한 부여 체계를 지원합니다.

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

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

다음 이미지는 EventBridge 연결을 사용하여 타사 API 호출에 대한 인증을 Step Functions 처리하는 방법을 보여줍니다. 타사 API 공급자의 자격 증명을 관리하는 EventBridge 연결입니다. EventBridge연결 및 권한 부여 매개변수를 암호화된 형식으로 Secrets Manager 저장하기 위해 암호를 생성합니다.

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

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

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

다음 목록은 제3자를 호출하기 전에 데이터를 Step Functions 병합하는 방법을 설명합니다. API

다음 예제에서는 HTTP Task와 EventBridge 연결 모두에서 HeadersQueryParameters, 및 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 연결에 중복 키가 지정되어 있습니다. 따라서 는 HTTP 태스크의 값을 연결의 값으로 Step Functions 덮어씁니다. 다음 코드 스니펫은 타사에 Step Functions 보내는 HTTP 요청을 보여줍니다. API

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 -encoding을 적용합니다.

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

필드를 사용하여 URL -encoding을 지정합니다. Transform 이 필드에는 요청 본문에 URL -encoding을 적용할지 여부를 지정하는 RequestBodyEncoding 필드가 포함되어 있습니다. RequestBodyEncoding필드를 지정하면 제3자에게 전화를 걸기 전에 JSON 요청 본문을 form-urlencoded 요청 본문으로 Step Functions 변환합니다. API 또한 URL -encoded 데이터를 수락하면 content-type 헤더가 반드시 application/x-www-form-urlencoded 포함되므로 APIs 헤더를 지정해야 합니다. content-type

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

IAM태스크를 실행할 수 있는 권한 HTTP

상태 시스템 실행 역할에는 타사를 호출할 수 있는 HTTP 태스크에 대한 states:InvokeHTTPEndpoint events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue,, 및 secretsmanager:DescribeSecret 권한이 있어야 API 합니다. 다음 IAM 정책 예제는 APIs Stripe를 호출하는 데 필요한 최소한의 권한을 상태 시스템 역할에 부여합니다. 또한 이 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, QueryParametersTransform, 및 RequestBody 매개변수를 포함하는 HTTP 태스크를 보여줍니다. HTTP태스크는 API 스트라이프인 https://api.stripe.com/v1/ 인보이스를 호출하여 인보이스를 생성합니다. 또한 HTTP 태스크는 URL 인코딩 옵션을 사용하여 요청 본문에 -encoding을 지정합니다. INDICES

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

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

교체하는 것을 잊지 마세요.italicized 텍스트를 리소스별 정보로 입력하세요.

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

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

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

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

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

반환된 응답에 대해 다음 조건 중 하나에 해당하는 경우 HTTP 태스크가 실패하고 States.Runtime 오류가 발생합니다.