AWS Transfer Family API 참조

Transfer Family에 대한 전체 API 참조 가이드는 AWS Transfer Family API 참조에서 확인할 수 있습니다.

AWS Transfer Family 는 다음 프로토콜을 통해 Amazon Simple Storage Service(Amazon S3) 스토리지 안팎으로 파일을 전송하는 데 사용할 수 있는 보안 전송 서비스입니다.

Secure Shell (SSH) File Transfer 프로토콜 (SFTP)
File Transfer 프로토콜 보안(FTPS)
File Transfer 프로토콜(FTP)
적용성 보고서 2(AS2)

서버, 사용자, 역할은 모두 Amazon 리소스 이름(ARN)으로 식별합니다. ARN을 사용하여 개체에 태그, 키 값 쌍을 할당할 수 있습니다. 태그는 이러한 개체(entity)를 그룹화하고 검색하는 데 사용할 수 있는 메타데이터입니다. 태그를 유용하게 사용할 수 있는 대표적인 분야는 회계입니다.

다음 규칙은 AWS Transfer Family ID 형식으로 관찰됩니다.

s-01234567890abcdef 양식에서 얻은 ServerId 값
key-01234567890abcdef 양식에서 얻은 SshPublicKeyId 값

Amazon 리소스 이름(ARN) 양식은 다음과 같은 형식을 취합니다.

사용자의 경우, ARN은 arn:aws:transfer:region:account-id:server/server-id 형식을 취합니다.

서버 ARN의 예: arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef
사용자의 경우, ARN은 arn:aws:transfer:region:account-id:user/server-id/username 형식을 취합니다.

예를 들면, arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1입니다.

사용 중인 DNS 항목(엔드포인트)은 다음과 같습니다.

transfer.region.amazonaws.com 형식을 취하는 API 엔드포인트
server-id.server.transfer.region.amazonaws.com 형식을 취하는 서버 엔드포인트

에 대한이 API 인터페이스 참조에는 관리하는 데 사용할 수 있는 프로그래밍 인터페이스에 대한 설명서가 AWS Transfer Family 포함되어 있습니다 AWS Transfer Family. 참조 구조는 다음과 같습니다.

작업의 영문자순 목록은 Actions를 참조하세요.
데이터 형식의 알파벳순 목록은 Types을 참조하세요.
공통 쿼리 파라미터 목록은 공통 파라미터를 참조하세요.
오류 코드에 대한 설명은 공통 오류를 참조하세요.

작은 정보

명령을 실제로 실행하는 대신 모든 API 직접 호출에 --generate-cli-skeleton 파라미터를 사용하여 파라미터 템플릿을 생성하고 표시할 수 있습니다. 그런 다음 생성된 템플릿을 사용하여 사용자 정의하고 이후 명령의 입력으로 사용할 수 있습니다. 자세한 내용은 파라미터 스켈레톤 파일 생성 및 사용을 참조하세요.

API 요청 만들기

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

참고

Transfer Family;를 사용하여 애플리케이션을 개발할 때 AWS SDKs를 사용할 수도 있습니다. Java, .NET 및 PHP용 AWS SDK는 프로그래밍 작업을 간소화하며 기본 Transfer Family API를 포함합니다. SDK 라이브러리 다운로드에 대한 정보는 샘플 코드 라이브러리 섹션을 참조하세요.

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 트랜잭션에 사용되는 공통 헤더입니다.

Transfer Family 요청 입력 및 서명

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

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

오류 응답

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

콘텐츠 타입: application/x-amz-json-1.1
적절한 4xx 또는 5xx HTTP 상태 코드

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


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

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

__타입

Transfer Family API 호출의 예외 중 하나입니다.

타입: 문자열

메시지 또는 메시지

작업 오류 코드 메시지 중 하나입니다.

참고

일부 예외에서 message가 사용되고 다른 예외에서 Message가 사용됩니다. 인터페이스의 코드를 확인하여 적절한 대/소문자를 확인할 수 있습니다. 또는 각 옵션을 테스트하여 어떤 옵션이 효과가 있는지 확인할 수 있습니다.

타입: 문자열

리소스

오류가 호출된 리소스입니다. 예컨대, 이미 존재하는 사용자를 만들려고 하면 Resource가 기존 사용자의 사용자 이름이 됩니다.

타입: 문자열

ResourceType

오류가 호출되는 리소스 타입입니다. 예컨대, 이미 존재하는 사용자를 만들려고 하면 ResourceType이 User가 됩니다.

타입: 문자열

RetryAfterSeconds

명령을 재시도하기 전에 대기하는 시간(초).

타입: 문자열

오류 응답 예

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 는 명령줄 도구 및 쿼리 API 대신 언어별 APIs를 사용하여 애플리케이션을 빌드하려는 소프트웨어 개발자를 위해 라이브러리, 샘플 코드, 자습서 및 기타 리소스를 제공합니다. 이러한 라이브러리는 보다 쉽게 시작하도록 요청 인증, 요청 재시도 및 오류 처리 같은 기본 기능(API에는 포함되지 않음)을 제공합니다. 빌드할 도구 AWS 참조

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

자격 증명 공급자

AWS Transfer Family 는 사용자를 인증하고 관리하기 위해 여러 자격 증명 공급자 유형을 지원합니다. 각 서버는 하나의 인증 방법만 사용할 수 있으며, 서버 생성 시이 방법을 선택해야 합니다.

서비스 관리형

SERVICE_MANAGED 인증 방법을 사용하면 사용자 자격 증명이 내부에 저장되고 관리됩니다 AWS Transfer Family. 사용자는 서버의 사용자 이름과 연결된 SSH 퍼블릭 키를 사용하여 인증됩니다.

각 사용자는 서비스에 저장된 SSH 퍼블릭 키를 하나 이상 가질 수 있습니다. 클라이언트가 파일 작업을 요청하면 저장된 퍼블릭 키에 대해 인증된 사용자 이름과 SSH 프라이빗 키를 제공합니다.

Directory Service

AWS_DIRECTORY_SERVICE 인증 방법을 사용하면 Directory Service for Microsoft Active AWS Directory(AWS Directory Service for Microsoft Active Directory)와 통합할 수 있습니다.

이 옵션을 사용하면 기존 Active Directory 그룹을 통해 사용자 인증 및 액세스를 관리할 수 있습니다. 사용자는 Active Directory 자격 증명을 사용하여 인증할 수 있습니다.

기본 제한은 서버당 100개의 Active Directory 그룹이며, 서비스 제한 증가를 통해 최대 150개의 그룹으로 늘릴 수 있습니다.

Lambda

AWS_LAMBDA 인증 방법을 사용하면를 사용하여 사용자 지정 자격 증명 공급자에 연결할 수 있습니다 AWS Lambda.

이 옵션은 기존 자격 증명 관리 시스템과 통합할 수 있는 유연성을 제공합니다. Lambda 함수는 사용자를 인증하고 적절한 액세스 정책을 반환하는 역할을 합니다.

사용자 지정(API Gateway)

API_GATEWAY 인증 방법(콘솔에 사용자 지정으로 표시됨)을 사용하면 사용자 인증과 액세스 제어를 모두 제공하는 사용자 지정 인증 방법을 사용할 수 있습니다.

이 메서드는 Amazon API Gateway에 의존하여, 자격 증명 공급자가 제공한 API 직접 호출을 이용해 사용자 요청을 확인합니다. 이 사용자 지정 메서드를 이용해 디렉터리 서비스, 데이터베이스 이름과 암호 쌍 또는 기타 메커니즘에 대해 사용자를 인증할 수도 있습니다.

모든 인증 방법에 대해 사용자에게 Amazon S3 버킷 또는 Amazon Elastic File System 파일 시스템에 대한 액세스를 정의하는 정책이 할당됩니다. 서버는 AssumeRole 작업과 함께 IAM 역할을 통해 사용자로부터 신뢰 관계를 상속하므로 사용자를 대신하여 파일 작업을 수행할 수 있습니다.

이름 지정 규칙

AWS Transfer Family 는 리소스 식별자 및 Amazon 리소스 이름(ARNs)에 표준화된 형식을 사용합니다. API로 작업할 때는 이러한 규칙을 이해하는 것이 AWS Transfer Family 중요합니다.

ID 형식

다음 규칙은 AWS Transfer Family ID 형식으로 관찰됩니다.

서버 IDs: s-01234567890abcdef 양식에서 얻은 ServerId 값
SSH 퍼블릭 키 IDs: key-01234567890abcdef 양식에서 얻은 SshPublicKeyId 값
커넥터 IDs: c-01234567890abcdef 양식에서 얻은 ConnectorId 값
워크플로 IDs: w-01234567890abcdef 양식에서 얻은 WorkflowId 값
프로필 IDs: p-01234567890abcdef 양식에서 얻은 ProfileId 값
WebApp IDs: webapp-01234567890abcdef 양식에서 얻은 WebAppId 값

ARN 형식

Amazon 리소스 이름(ARN) 양식은 다음과 같은 형식을 취합니다.

서버 ARNs

사용자의 경우, ARN은 arn:aws:transfer:region:account-id:server/server-id 형식을 취합니다.

예시: arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef.

사용자 ARNs

사용자의 경우, ARN은 arn:aws:transfer:region:account-id:user/server-id/username 형식을 취합니다.

예시: arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1.

커넥터 ARNs

커넥터의 경우 ARNs 취합니다arn:aws:transfer:region:account-id:connector/connector-id.

예시: arn:aws:transfer:us-east-1:123456789012:connector/c-01234567890abcdef.

워크플로 ARNs

워크플로의 경우 ARNs 취합니다arn:aws:transfer:region:account-id:workflow/workflow-id.

예시: arn:aws:transfer:us-east-1:123456789012:workflow/w-01234567890abcdef.

WebApp ARNs

웹 애플리케이션의 경우 ARNs 취합니다arn:aws:transfer:region:account-id:webapp/webapp-id.

예시: arn:aws:transfer:us-east-1:123456789012:webapp/webapp-01234567890abcdef.

ARN을 사용하여 개체에 태그, 키 값 쌍을 할당할 수 있습니다. 태그는 이러한 개체(entity)를 그룹화하고 검색하는 데 사용할 수 있는 메타데이터입니다. 태그를 유용하게 사용할 수 있는 대표적인 분야는 회계입니다.

DNS 및 엔드포인트

AWS Transfer Family 는 API 엔드포인트와 서버 엔드포인트 모두에 대해 표준화된 DNS 이름 지정 규칙을 사용합니다. 이러한 엔드포인트를 이해하는 것은 클라이언트를 구성하고 API를 호출하는 데 필수적입니다.

API 엔드포인트

API 엔드포인트는 API 호출을 통해 AWS Transfer Family 리소스를 관리하는 데 사용됩니다. 이러한 엔드포인트의 형식은 다음과 같습니다.

표준 API 엔드포인트

표준 API 엔드포인트는 형식을 취합니다transfer.region.amazonaws.com.

예시: transfer.us-east-1.amazonaws.com

듀얼 스택 API 엔드포인트

AWS Transfer Family 는 IPv4 또는 IPv6 요청을 사용하여 액세스할 수 있는 듀얼 스택 API 엔드포인트를 제공합니다.

https://transfer.region-code.api.aws
https://transfer-fips.region-code.api.aws

서버 엔드포인트

서버 엔드포인트는 파일 전송 클라이언트가 AWS Transfer Family 서버에 연결하는 데 사용됩니다. 이러한 엔드포인트의 형식은 다음과 같습니다.

표준 서버 엔드포인트

표준 서버 엔드포인트는 형식을 취합니다server-id.server.transfer.region.amazonaws.com.

예시: s-01234567890abcdef.server.transfer.us-east-1.amazonaws.com

사용자 지정 호스트 이름

AWS Transfer Family 서버에 대한 사용자 지정 호스트 이름을 구성할 수도 있습니다. 사용자 지정 호스트 이름을 사용하여 사용자에게 보다 사용자 친화적이거나 브랜드가 지정된 환경을 제공할 수 있습니다.

사용자 지정 호스트 이름을 사용하려면 다음을 수행해야 합니다.

도메인 이름 소유
유효한 인증서 제공
AWS Transfer Family 서버를 가리키도록 DNS 레코드 구성

AWS 리전별 AWS Transfer Family 엔드포인트의 전체 목록은 AWS Transfer Family 의 엔드포인트 및 할당량을 참조하세요AWS 일반 참조.

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

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

문서 규칙

AS2 문제

문서 이력