서비스 통합 패턴

AWS Step Functions Amazon States 언어로 서비스와 직접 통합됩니다. 세 가지 서비스 통합 패턴을 사용하여 이러한 AWS 서비스를 제어할 수 있습니다

서비스를 직접적으로 호출하고 Step Functions에서 HTTP 응답을 가져온 후 즉시 다음 상태로 진행할 수 있습니다.
서비스를 직접적으로 호출하고 작업이 완료될 때까지 Step Functions가 기다리도록 합니다.
작업 토큰으로 서비스를 직접적으로 호출하고 Step Functions는 해당 토큰이 페이로드와 함께 반환될 때까지 기다리도록 합니다.

이러한 각 서비스 통합 패턴은 작업 정의의 "Resource" 필드에 URI를 만드는 방법에 의해 제어됩니다.

통합 서비스의 구성 AWS Identity and Access Management (IAM) 에 대한 자세한 내용은 을 참조하십시오. 통합 서비스용 IAM 정책

요청 및 응답

작업 상태의 "Resource" 문자열에서 서비스를 지정하고 리소스만 제공하면 Step Functions는 HTTP 응답을 기다린 후 다음 상태로 진행합니다. Step Functions는 작업이 완료될 때까지 기다리지 않습니다.

다음 예제에서는 Amazon SNS 주제를 게시하는 방법을 보여줍니다.


"Send message to SNS":{  
   "Type":"Task",
   "Resource":"arn:aws:states:::sns:publish",
   "Parameters":{  
      "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic",
      "Message":"Hello from Step Functions!"
   },
   "Next":"NEXT_STATE"
}

이 예제는 Amazon SNS의 Publish API를 참조합니다. 워크플로는 Publish API를 호출한 후 다음 상태로 진행합니다.

작은 정보

요청 응답 서비스 통합 패턴을 사용하는 샘플 워크플로를 사용자 AWS 계정환경에 배포하려면 모듈 2 - AWS Step Functions 워크숍의 요청 응답을 참조하십시오.

작업 실행(.sync)

Amazon AWS Batch ECS와 같은 통합 서비스의 경우 Step Functions는 요청이 완료될 때까지 기다린 후 다음 상태로 진행할 수 있습니다. Step Functions가 기다리도록 하려면 리소스 URI 뒤에 .sync 접미사를 추가하여 작업 상태 정의에서 "Resource" 필드를 지정합니다.

예를 들어, AWS Batch 작업을 제출할 때는 이 예제와 같이 상태 시스템 정의의 "Resource" 필드를 사용하십시오.


"Manage Batch task": {
  "Type": "Task",
  "Resource": "arn:aws:states:::batch:submitJob.sync",
  "Parameters": {
    "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition",
    "JobName": "testJob",
    "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue"
  },
  "Next": "NEXT_STATE"
}

리소스 Amazon 리소스 이름(ARN)에 추가된 .sync 부분이 있으면 이는 Step Functions가 작업이 완료될 때까지 기다린다는 의미입니다. AWS Batch submitJob을 호출한 후 워크플로가 일시 중지됩니다. 작업이 완료되면 Step Functions는 다음 상태로 진행합니다. 자세한 내용은 AWS Batch 샘플 프로젝트를 참조하십시오배치 작업 관리(AWS Batch, Amazon SNS).

이 (.sync) 서비스 통합 패턴을 사용하는 작업이 중단되고 Step Functions가 작업을 취소할 수 없으면 통합 서비스에서 추가 요금이 발생할 수 있습니다. 다음과 같은 경우에 작업을 중단할 수 있습니다.

상태 시스템 실행이 중지되었습니다.
확인할 수 없는 오류가 발생하여 Parallel 상태의 다른 브랜치가 실패합니다.
확인할 수 없는 않는 오류가 발생하여 Map 상태 반복이 실패합니다.

Step Functions는 작업을 취소하기 위해 최선을 다합니다. 예를 들어 Step Functions states:startExecution.sync 작업이 중단되면 Step Functions StopExecution API 작업을 직접적으로 호출합니다. 하지만 Step Functions에서 작업을 취소하지 못할 수도 있습니다. 이에 대한 이유는 다음과 같지만 이에 국한되지는 않습니다.

IAM 실행 역할에 해당 API 직접 호출을 수행할 수 있는 권한이 없습니다.
일시적으로 서비스가 중단되었습니다.

.sync 서비스 통합 패턴을 사용하면 Step Functions는 할당된 할당량과 이벤트를 사용하는 폴링을 사용하여 작업 상태를 모니터링합니다. 동일한 계정 내에서 .sync 호출하는 경우 Step Functions는 EventBridge 이벤트를 사용하고 상태에 지정된 API를 폴링합니다. Task 크로스 계정 .sync 간접 호출의 경우 Step Functions는 폴링만 사용합니다. 예를 들어states:StartExecution.sync, 의 경우 Step Functions는 DescribeExecutionAPI에서 폴링을 수행하고 할당된 할당량을 사용합니다.

작은 정보

Run a Job (.sync) 서비스 통합 패턴을 사용하는 샘플 워크플로를 사용자 AWS 계정환경에 배포하려면 워크숍의 모듈 3 - Run a Job (.sync) 을 AWS Step Functions 참조하십시오.

작업이 완료될 때까지 대기(.sync)를 지원하는 통합 서비스 목록을 보려면 Step Functions를 위한 최적화된 통합 단원을 참조하십시오.

참고

.sync 패턴을 사용하는 서비스 통합에는 추가 IAM 권한이 필요합니다. 자세한 정보는 통합 서비스용 IAM 정책을 참조하세요.

경우에 따라 Step Functions가 작업이 완전히 완료되기 전까지 워크플로를 계속하기를 원할 수 있습니다. 작업 토큰을 사용하여 콜백 대기 서비스 통합 패턴을 사용할 때와 같은 방법으로 이 작업을 수행할 수 있습니다. 이렇게 하려면 작업 토큰을 작업에 전달한 다음 SendTaskSuccess 또는 SendTaskFailure API 직접 호출을 사용하여 반환합니다. Step Functions는 해당 호출에서 제공한 데이터를 사용하여 작업을 완료하고 작업 모니터링을 중지하며 워크플로를 계속합니다.

작업 토큰을 사용하여 콜백 대기

콜백 작업은 작업 토큰이 반환될 때까지 워크플로를 일시 중지하는 방법을 제공합니다. 작업은 사람의 승인을 대기하거나, 타사와 통합하거나 레거시 시스템을 호출해야 할 수 있습니다. 이러한 작업의 경우 워크플로 실행이 1년 서비스 할당량(상태 제한과 관련된 할당량 참조)에 도달할 때까지 Step Functions를 일시 중지하고 외부 프로세스나 워크플로가 완료될 때까지 기다릴 수 있습니다. 이러한 상황에서 Step Functions를 사용하면 AWS SDK 서비스 통합과 일부 최적화 서비스 통합에 태스크 토큰을 전달할 수 있습니다. 작업은 SendTaskSuccess 또는 SendTaskFailure 호출을 통해 해당 작업 토큰을 다시 수신할 때까지 일시 중지됩니다.

콜백 작업 토큰을 사용하는 Task 상태 시간이 초과되면 새로운 무작위 토큰이 생성됩니다. 컨텍스트 객체에서 작업 토큰에 액세스할 수 있습니다.

참고

작업 토큰은 1자 이상, 1024자 이하여야 합니다.

AWS SDK .waitForTaskToken 통합과 함께 사용하려면 사용하는 API에 태스크 토큰을 배치할 파라미터 필드가 있어야 합니다.

참고

동일한 계정 내 보안 주체로부터 작업 토큰을 전달해야 합니다. AWS 다른 계정의 보안 주체로부터 토큰을 보내면 토큰이 작동하지 않습니다. AWS

작은 정보

콜백 태스크 토큰 서비스 통합 패턴을 사용하는 샘플 워크플로를 사용자에게 AWS 계정배포하려면 모듈 4 - 워크샵의 태스크 토큰을 사용한 콜백 대기 섹션을 참조하십시오. AWS Step Functions

작업 토큰 대기(.waitForTaskToken)를 지원하는 통합 서비스 목록은 Step Functions를 위한 최적화된 통합 단원을 참조하십시오.

주제

작업 토큰 예제
컨텍스트 객체에서 토큰 가져오기
대기 작업에 대한 하트비트 시간 제한 구성

작업 토큰 예제

이 예제에서 Step Functions 워크플로는 외부 마이크로서비스와 통합하여 승인 워크플로의 일부로 크레딧 확인을 수행해야 합니다. Step Functions는 작업 토큰이 메시지의 일부로 포함된 Amazon SQS 메시지를 게시합니다. 외부 시스템은 Amazon SQS와 통합되고 대기열에서 메시지를 풀링합니다. 이 작업이 완료되면 결과와 원래 작업 토큰을 반환합니다. 그러면 Step Functions가 워크플로를 계속합니다.

Amazon SQS를 참조하는 작업 정의의 "Resource" 필드 끝에 .waitForTaskToken이 추가되어 있습니다.


"Send message to SQS": {
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
    "MessageBody": {
        "Message": "Hello from Step Functions!",
        "TaskToken.$": "$$.Task.Token"
     }
  },
  "Next": "NEXT_STATE"
}

이는 Step Functions에게 일시 중지하고 작업 토큰을 기다리라고 지시합니다. .waitForTaskToken을 사용하여 리소스를 지정하면 특정 경로 지정($$.Task.Token)이 있는 상태 정의의 "Parameters" 필드에서 작업 토큰에 액세스할 수 있습니다. 처음 $$.는 경로가 컨텍스트 객체에 액세스하고 진행 중인 실행에서 현재 작업에 대한 작업 토큰을 가져오도록 지정합니다

작업이 완료되면 외부 서비스가 taskToken이 포함되어 있는 SendTaskSuccess 또는 SendTaskFailure를 직접적으로 호출합니다. 그런 다음에만 워크플우는 다음 상태로 계속합니다.

참고

프로세스가 SendTaskSuccess 또는 SendTaskFailure와 함께 작업 토큰을 전달하는 데 실패하는 경우 무기한 대기하지 않도록 하려면 대기 작업에 대한 하트비트 시간 제한 구성 단원을 참조하십시오.

컨텍스트 객체에서 토큰 가져오기

컨텍스트 객체는 실행에 대한 정보가 포함된 내부 JSON 객체입니다. 상태 입력과 마찬가지로, 실행 중에 "Parameters" 필드의 경로를 사용하여 이 객체에 액세스할 수 있습니다. 작업 정의 내에서 액세스하는 경우 작업 토큰을 포함하여 특정 실행에 대한 정보가 포함됩니다.


{
    "Execution": {
        "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName",
        "Input": {
           "key": "value"
        },
        "Name": "executionName",
        "RoleArn": "arn:aws:iam::123456789012:role...",
        "StartTime": "2019-03-26T20:14:13.192Z"
    },
    "State": {
        "EnteredTime": "2019-03-26T20:14:13.192Z",
        "Name": "Test",
        "RetryCount": 3
    },
    "StateMachine": {
        "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName",
        "Name": "name"
    },
    "Task": {
        "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
    }
}

작업 정의의 "Parameters" 필드 내부에서 특정 경로를 사용하여 작업 토큰에 액세스할 수 있습니다. 입력 또는 컨텍스트 객체에 액세스하려면 먼저 .$를 파라미터 이름에 추가하여 파라미터가 경로가 되도록 지정합니다. 다음은 "Parameters" 지정에서 입력 및 컨텍스트 객체의 노드를 지정합니다.


"Parameters": {
   "Input.$": "$",
   "TaskToken.$": "$$.Task.Token"
 },

두 경우 모두 .$를 파라미터 이름에 추가하면 Step Functions에 경로를 예상하라고 지시하는 것입니다. 첫 번째 경우 "$"는 전체 입력이 포함된 경로입니다. 두 번째 경우, $$.는 경로가 컨텍스트 객체에 액세스하도록 지정하고 $$.Task.Token은 파라미터를 진행 중인 실행의 컨텍스트 객체에 있는 작업 토큰의 값으로 설정합니다.

Amazon SQS 예제에서 "Resource" 필드의 .waitForTaskToken은 Step Functions에 작업 토큰이 반환될 때까지 기다리라고 지시합니다. "TaskToken.$": "$$.Task.Token" 파라미터는 해당 토큰을 Amazon SQS 메시지의 일부로 전달합니다.


"Send message to SQS": {
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
    "MessageBody": {
        "Message": "Hello from Step Functions!",
        "TaskToken.$": "$$.Task.Token"
     }
  },
  "Next": "NEXT_STATE"
}

컨텍스트 객체에 대한 자세한 내용은 이 가이드의 컨텍스트 객체 단원에 있는 입/출력 처리 항목을 참조하십시오.

대기 작업에 대한 하트비트 시간 제한 구성

작업 토큰을 대기하고 있는 작업은 실행이 1년 서비스 할당량에 도달할 때까지 대기합니다(상태 제한과 관련된 할당량 참조). 실행 멈춤을 방지하기 위해 상태 머신 정의에서 하트비트 제한 시간 간격을 구성할 수 있습니다. HeartbeatSeconds 필드를 사용항 제한 시간 간격을 지정합니다.


{
  "StartAt": "Push to SQS",
  "States": {
    "Push to SQS": {
      "Type": "Task",
      "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
      "HeartbeatSeconds": 600,
      "Parameters": {
        "MessageBody": { "myTaskToken.$": "$$.Task.Token" },
        "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue"
      },
      "ResultPath": "$.SQS",
      "End": true
    }
  }
}

이 상태 시스템 정의에서 작업은 메시지를 Amazon SQS로 푸시하고 제공된 작업 토큰을 사용하여 외부 프로세스가 다시 직접적으로 호출할 때까지 기다립니다. "HeartbeatSeconds": 600 필드는 하트비트 제한 시간 간격을 10분으로 설정합니다. 이 작업은 이러한 API 작업 중 하나를 사용하여 작업 토큰이 반환될 때까지 대기합니다.

대기 중인 작업이 10분 기간 이내에 유효한 작업 토큰을 수신하지 않으면 이 작업은 States.Timeout 오류 이름과 함께 실패합니다.

자세한 내용은 콜백 작업 샘플 프로젝트인 콜백 패턴 예제(Amazon SQS, Amazon SNS, Lamda) 를 참조하십시오.

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

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

문서 규칙

타사 API 호출

파라미터를 서비스 API에 전달