Step Functions 워크플로APIs에서 타사 호출

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

Workflow Studio를 사용하여 HTTP 태스크가 포함된 상태 시스템을 빌드하는 경우 Workflow Studio는 를 사용하여 실행 역할을 자동으로 생성합니다.IAM HTTP 태스크에 대한 정책입니다. 자세한 내용은 Workflow Studio에서 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. 연결을 사용하면 API 키와 같은 하드 코딩 보안 암호가 상태 시스템 정의에 포함되지 않도록 할 수 있습니다. EventBridge 연결은 기본, OAuth및 API 키 권한 부여 체계를 지원합니다.

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

연결을 생성하고 권한 부여 파라미터를 추가하면 는 에서 보안 암호를 EventBridge 생성합니다 AWS Secrets Manager. 이 보안 암호에서 는 연결 및 권한 부여 파라미터를 암호화된 형식으로 EventBridge 저장합니다. 연결을 성공적으로 생성하거나 업데이트하려면 Secrets Manager를 사용할 권한이 AWS 계정 있는 를 사용해야 합니다. 에 대한 자세한 내용은 IAM 상태 시스템이 EventBridge 연결에 액세스하는 데 필요한 권한은 섹션을 참조하세요IAM HTTP 태스크를 실행할 수 있는 권한.

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

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

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

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

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

다음 예제에서는 HTTP 작업 및 Headers의 QueryParameters, 및 RequestBody 필드를 설정합니다.EventBridge 연결.

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 태스크의 값을 연결의 값으로 덮어씁니다. 다음 코드 조각은 다음과 같은 HTTP 요청을 보여줍니다.Step Functions 는 타사 로 전송합니다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- 인코딩

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

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

요청 본문에서 배열을 인코딩하려면 Step Functions 는 다음 배열 인코딩 옵션을 제공합니다.

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

HTTP 태스크가 타사 를 호출하려면 상태 시스템 실행 역할에 states:InvokeHTTPEndpoint, events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue, 및 secretsmanager:DescribeSecret 권한이 있어야 합니다API. 다음 IAM 정책 예제에서는 Stripe를 호출하는 데 필요한 최소 권한을 상태 시스템 역할에 부여합니다APIs. 또한 이 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 작업은 Stripe API, https://api.stripe.com/v1/invoices를 호출하여 송장을 생성합니다. HTTP 또한 작업은 URL인코딩 옵션을 사용하여 요청 본문에 대한 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"
}

다음 예제는 다음과 같은 HTTP 요청을 보여줍니다.Step Functions 는 Stripe 로 전송합니다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 작업 테스트

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

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

반환된 응답에 대해 다음 조건 중 하나가 true인 경우 States.Runtime 오류와 함께 HTTP 작업이 실패합니다.