API 요청 만들기

콘솔의 사용 외에도, AWS Transfer Family API를 사용하여 서버를 프로그래밍 방식으로 구성 및 관리할 수 있습니다. 이 섹션은 AWS Transfer Family 작동, 인증 요청 확인 및 오류 처리를 설명합니다. Transfer Family에서 사용할 수 있는 지역 및 엔드포인트에 대한 자세한 설명은 AWS 일반 참조의 AWS Transfer Family엔드포인트 및 할당량을 참조하세요.

Transfer Family 필수 요청 헤더

이 섹션에서는 AWS Transfer Family에 대한 모든 POST 요청과 함께 전송해야 하는 필수 헤더에 대해 설명합니다. 호출하려는 작업을 포함하는 요청에 대한 핵심 정보, 요청 날짜 및 요청 전송자의 권한을 부여함을 나타내는 정보를 식별할 HTTP 헤더를 포함해야 합니다. 헤더는 대소문자를 구별하고 헤더의 순서는 중요하지 않습니다.

다음은 ListServers 작업에서 사용하는 헤더의 예입니다.

POST / HTTP/1.1
Host: transfer.us-east-1.amazonaws.com
x-amz-target: TransferService.ListServers
x-amz-date: 20220507T012034Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20220507/us-east-1/transfer/aws4_request,
    SignedHeaders=content-type;host;x-amz-date;x-amz-target,
    Signature=13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de
Content-Type: application/x-amz-json-1.1
Content-Length: 17

{"MaxResults":10}

다음은 Transfer Family에 대한 POST 요청과 함께 포함해야 하는 헤더입니다. "x-amz"로 시작하는 아래의 헤더는 AWS에 고유한 헤더입니다. 나머지 헤더는 HTTP 트랜잭션에 사용되는 공통 헤더입니다.

Content-Type: application/x-amz-json-1.1

Host: transfer.region.amazonaws.com

x-amz-date: YYYYMMDD'T'HHMMSS'Z'

x-amz-target: TransferService.operationName

Transfer Family 요청 입력 및 서명

모든 요청 입력은 요청 본문의 JSON 페이로드의 일부로 전송되어야 합니다. 모든 요청 필드가 선택 사항(예: ListServers)인 작업의 경우 요청 본문에 {}와 같이 빈 JSON 객체를 제공해야 합니다. Transfer Family 페이로드 요청/응답의 구조는 기존 API 참조(예: DescribeServer)에 문서화되어 있습니다.

Transfer Family는 AWS 서명 버전 4를 이용한 인증을 지원합니다. 자세한 설명은 AWS API 요청 서명을 참조하세요.

오류 응답

오류가 있는 경우, 응답 헤더 정보에는 다음 내용이 포함됩니다.

오류 응답의 본문에는 발생한 오류에 대한 정보가 포함됩니다. 다음 샘플 오류 응답은 모든 오류 응답에 공통된 응답 요소의 출력 구문을 나타냅니다.

{
    "__type": "String",
    "Message": "String", <!-- Message is lowercase in some instances -->
    "Resource": String,
    "ResourceType": String
    "RetryAfterSeconds": String
}

다음 표는 이전 구문에 표시된 JSON 오류 응답 필드를 설명합니다.

오류 응답 예

DescribeServer API를 호출하고 존재하지 않는 서버를 지정하면 다음 JSON 본문이 반환됩니다.

{
  "__type": "ResourceNotFoundException",
  "Message": "Unknown server",
  "Resource": "s-11112222333344444",
  "ResourceType": "Server"
}

API 실행 시 병목 현상이 발생하는 경우 다음 JSON 본문이 반환됩니다.

{
   "__type":"ThrottlingException",
   "RetryAfterSeconds":"1"
}

CreateServer API를 사용하고 Transfer Family 서버를 생성할 수 있는 충분한 권한이 없는 경우 다음 JSON 본문이 반환됩니다.

{
  "__type": "AccessDeniedException",
  "Message": "You do not have sufficient access to perform this action."
}

CreateUser API를 사용하고 이미 존재하는 사용자를 지정하면 다음 JSON 본문이 반환됩니다.

{  
  "__type": "ResourceExistsException",  
  "Message": "User already exists",
  "Resource": "Alejandro-Rosalez",
  "ResourceType": "User"
}  

사용 가능한 라이브러리

AWS에서는 command-line 도구 및 Query API 대신 언어별로 고유한 API를 사용하여 애플리케이션을 빌드하는 것을 선호하는 소프트웨어 개발자를 위해 라이브러리, 샘플 코드, 자습서 및 기타 리소스를 제공합니다. 이러한 라이브러리는 보다 쉽게 시작하도록 요청 인증, 요청 재시도 및 오류 처리 같은 기본 기능(API에는 포함되지 않음)을 제공합니다. AWS 기반 도구를 참조하세요.

모든 언어의 라이브러리와 샘플 코드는 샘플 코드 및 라이브러리를 참조하세요.