기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
API 참조
콘솔의 사용 외에도, AWS Storage Gateway API를 사용하여 게이트웨이를 프로그래밍 방식으로 구성 및 관리할 수 있습니다. 이 섹션은 AWS Storage Gateway 운영, 인증 요청 확인 및 오류 처리를 설명합니다. Storage Gateway에 사용할 수 있는 리전 및 엔드포인트에 대한 자세한 내용은AWS Storage Gateway엔드포인트 및 할당량의AWS일반 참조.
참고
도 사용할 수 있습니다.AWSStorage Gateway를 사용하여 애플리케이션을 개발할 때 SD 이AWSJava, .NET 및 PHP용 SDK는 기본 Storage Gateway API를 포함하여 프로그래밍 작업을 간소화합니다. SDK 라이브러리 다운로드에 대한 정보는 샘플 코드 라이브러리
AWS Storage Gateway필수 요청 헤더
이 단원에서는 모든 POST 요청과 함께 전송해야 하는 필수 헤더에 대해 설명합니다.AWS Storage Gateway. 호출하려는 작업을 포함하는 요청에 대한 핵심 정보, 요청 날짜 및 요청 전송자의 권한을 부여함을 나타내는 정보를 식별할 HTTP 헤더를 포함해야 합니다. 헤더는 대소문자를 구별하고 헤더의 순서는 중요하지 않습니다.
다음은 ActivateGateway 작업에서 사용하는 헤더의 예입니다.
POST / HTTP/1.1 Host: storagegateway.us-east-2.amazonaws.com Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120425/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=9cd5a3584d1d67d57e61f120f35102d6b3649066abdd4bf4bbcf05bd9f2f8fe2 x-amz-date: 20120912T120000Z x-amz-target: StorageGateway_20120630.ActivateGateway
다음은 POST 요청과 함께 포함해야 하는 헤더입니다.AWS Storage Gateway. 아래에 표시된 헤더는 “x-amz”로 시작합니다.AWS-지정 헤더입니다. 나머지 헤더는 HTTP 트랜잭션에 사용되는 공통 헤더입니다.
| 헤더 | 설명 |
|---|---|
Authorization |
권한 부여 헤더는 활성화하는 요청에 대한 몇 가지 정보를 포함합니다.AWS Storage Gateway를 사용하여 요청이 요청자에게 유효한 작업인지 확인합니다. 이 헤더의 형식은 다음과 같습니다(가독성을 높이기 위해 줄 바꿈 추가).
이전 구문에서는 YourAccessKey, 연도, 월, 일(yyyymmdd), 해당 리전 및 CalculatedSignature를 지정합니다. 권한 부여 헤더의 형식은 다음 요구 사항에 따라 결정됩니다.AWSV4 서명 프로세스. 서명 관련 세부 정보는 요청에 서명하기 단원에 나와 있습니다. |
Content-Type |
사용
|
Host |
호스트 헤더를 사용하여 다음을 지정합니다.AWS Storage Gateway요청을 보내는 엔드포인트입니다. 예,
|
x-amz-date |
HTTP
|
x-amz-target |
이 헤더는 API의 버전과 요청 중인 작업을 지정합니다. 대상 헤더 값은 API 버전을 API 이름과 연결하여 구성하며 형식은 다음과 같습니다.
이operationName값 (예: “ActivateGateway”) 은 API 목록에서 찾을 수 있으며,API 참조. |
요청에 서명하기
Storage Gateway는 요청에 서명하여 전송하는 모든 요청을 인증해야 합니다. 요청에 서명하려면 암호화 해시 함수를 이용해 디지털 서명을 계산해야 합니다. 암호화 해시는 입력을 근거로 하여 고유 해시 값을 반환하는 함수입니다. 해시 함수에 대한 입력에는 요청 텍스트와 보안 액세스 키가 포함됩니다. 해시 함수는 요청에 서명으로 포함하는 해시 값을 반환합니다. 서명은 요청에서 Authorization 헤더의 일부입니다.
Storage Gateway는 요청을 수신한 후 사용자가 요청에 서명할 때와 동일한 해시 함수 및 입력을 사용하여 서명을 재계산합니다. 결과 서명이 요청 서명과 일치할 경우 Storage Gateway는 요청을 처리합니다. 그렇지 않으면 요청이 거부됩니다.
다음을 사용하는 인증 지원AWS서명 버전 4. 서명을 계산하기 위한 프로세스는 다음 세 작업으로 나뉠 수 있습니다.
-
HTTP 요청을 정규 형식으로 재배열합니다. 정규 형식을 사용해야 하는 이유는 Storage Gateway가 서명을 재계산하여 본인이 전송한 서명과 비교할 때 동일한 정규 형식을 사용하기 때문입니다.
-
암호화 해시 함수에 대한 입력 값 중 하나로 사용할 문자열을 만듭니다. 서명할 문자열이라는 문자열은 해시 알고리즘의 이름, 요청 날짜, 자격 증명 범위 문자열, 이전 작업에서 정규화된 요청을 연결한 것입니다. 자격 증명 범위 문자열 자체는 날짜, 리전 및 서비스 정보를 연결한 것입니다.
-
서명할 문자열과 파생된 의 두 입력 문자열을 허용하는 암호화 해시 함수를 사용하여 요청에 대한 서명을 만듭니다. 파생된 키는 보안 액세스 키로 시작해 자격 증명 범위 문자열을 사용하여 일련의 해시 기반 메시지 인증 코드(HMAC)를 생성하는 방법으로 계산합니다.
서명 계산 예시
다음 예시에서는 ListGateways에 대해 서명을 생성하는 세부 과정을 안내합니다. 이 예시는 서명 계산 방법을 점검하기 위한 참조로 사용할 수 있습니다. 다른 참조 계산은 Amazon Web Services 글로서리의 서명 버전 4 테스트 제품군에 포함되어 있습니다.
이 예시에서는 다음과 같이 가정합니다.
-
해당 요청의 타임스탬프는 "2012년 9월 10일 월요일 00:00:00시" GMT입니다.
-
엔드포인트는 미국 동부 (오하이오) 리전입니다.
일반 요청 구문(JSON 본문 포함)은 다음과 같습니다.
POST / HTTP/1.1 Host: storagegateway.us-east-2.amazonaws.com x-amz-Date: 20120910T000000Z Authorization:SignatureToBeCalculatedContent-type: application/x-amz-json-1.1 x-amz-target: StorageGateway_20120630.ListGateways {}
POST / content-type:application/x-amz-json-1.1 host:storagegateway.us-east-2.amazonaws.com x-amz-date:20120910T000000Z x-amz-target:StorageGateway_20120630.ListGateways content-type;host;x-amz-date;x-amz-target 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
정규 요청의 마지막 줄은 요청 본문의 해시입니다. 또한 정규 요청에서 비어 있는 세 번째 줄에 주의해야 합니다. 이유는 이 API (또는 Storage Gateway API) 에 대해 쿼리 파라미터가 없기 때문입니다.
AWS4-HMAC-SHA256 20120910T000000Z 20120910/us-east-2/storagegateway/aws4_request 92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e
서명할 문자열의 첫째 줄은 알고리즘, 둘째 줄은 타임스탬프, 셋째 줄은 자격 증명 범위, 마지막 줄은 작업 1 정규 요청의 해시입니다.
을 위한 파생된 키는 다음과 같이 표시할 수 있습니다.
derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-2"),"storagegateway"),"aws4_request")
보안 액세스 키인 wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY 사용되는 경우 계산된 서명은 다음과 같습니다.
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
마지막 단계는 Authorization 헤더를 생성하는 것입니다. 데모용 액세스 키 AKIAIOSFODNN7EXAMPLE 의 경우 헤더는 다음과 같습니다 (가독성을 높이기 위해 줄 바꿈을 추가함). AKIAIOSFODNN7EXAMPLE
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120910/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
오류 응답
이 단원에서는 AWS Storage Gateway 오류에 대한 참조 정보를 제공합니다. 이 오류는 오류 예외 및 작업 오류 코드로 표시됩니다. 예를 들어 오류 예외 InvalidSignatureException은 요청 서명에 문제가 있는 경우 모든 API 응답이 반환합니다. 그러나 작업 오류 코드 ActivationKeyInvalid는 ActivateGateway API에 대해서만 반환됩니다.
오류 유형에 따라 Storage Gateway는 예외만 반환하거나 예외 및 작업 오류 코드를 모두 반환할 수 있습니다. 오류 응답 예시는 오류 응답에 있습니다.
예외
다음 표에는 AWS Storage Gateway API 예외가 나와 있습니다. AWS Storage Gateway 작업이 오류 응답을 반환할 때 응답 본문에는 이러한 예외 중 하나가 포함되어 있습니다. InternalServerError와 InvalidGatewayRequestException은 특정 작업 오류 코드를 부여하는 작업 오류 코드(작업 오류 코드) 메시지 코드 중 하나를 반환합니다.
| 예외 | Message | HTTP 상태 코드 |
|---|---|---|
IncompleteSignatureException |
지정한 서명이 불완전합니다. | 400 잘못된 요청 |
InternalFailure |
알 수 없는 오류, 예외 또는 장애로 인해 요청 처리가 실패했습니다. | 500 Internal Server Error |
InternalServerError |
작업 오류 코드 작업 오류 코드 메시지 중 하나입니다. | 500 Internal Server Error |
InvalidAction |
요청된 동작 또는 작업이 유효하지 않습니다. | 400 잘못된 요청 |
InvalidClientTokenId |
X.509 인증서 또는AWS제공된 액세스 키 ID가 AWS의 레코드에 존재하지 않습니다. | 403 금지됨 |
InvalidGatewayRequestException |
작업 오류 코드의 작업 오류 코드 메시지 중 하나입니다. | 400 잘못된 요청 |
InvalidSignatureException |
우리가 계산한 요청 서명이 사용자가 제공한 서명과 일치하지 않습니다. 확인AWS액세스 키와 서명 방법. | 400 잘못된 요청 |
MissingAction |
요청에서 작업 또는 작업 파라미터가 누락되었습니다. | 400 잘못된 요청 |
MissingAuthenticationToken |
요청은 유효한 (등록된) 를 포함해야 합니다.AWS키 ID 또는 X.509 인증서에 액세스합니다. | 403 금지됨 |
RequestExpired |
요청이 만료 날짜 또는 요청 날짜(15분 패딩)를 지났거나 요청 날짜가 향후 15분 초과 후에 효력이 발생합니다. | 400 잘못된 요청 |
SerializationException |
직렬화 도중에 오류가 발생했습니다. JSON 페이로드의 형식이 올바른지 확인합니다. | 400 잘못된 요청 |
ServiceUnavailable |
서버의 일시적 장애로 인해 요청이 실패하였습니다. | [503 Service Unavailable] |
SubscriptionRequiredException |
이AWS액세스 키 ID는 서비스 가입이 필요합니다. | 400 잘못된 요청 |
ThrottlingException |
속도를 초과하였습니다. | 400 잘못된 요청 |
UnknownOperationException |
알 수 없는 작업을 지정하였습니다. 유효한 작업은 Storage Gateway에 나열되어 있습니다. | 400 잘못된 요청 |
UnrecognizedClientException |
요청에 포함된 보안 토큰이 잘못되었습니다. | 400 잘못된 요청 |
ValidationException |
입력 파라미터의 값이 잘못되었거나 범위를 벗어났습니다. | 400 잘못된 요청 |
작업 오류 코드
다음 표에는 AWS Storage Gateway 작업 오류 코드와 해당 코드를 반환할 수 있는 API 간의 매핑이 나와 있습니다. 모든 작업 오류 코드는 두 가지 일반적인 예외 중 하나와 함께 반환됩니다.InternalServerError과InvalidGatewayRequestException—설명됨예외.
| 작업 오류 코드 | Message | 이 오류 코드를 반환하는 작업 |
|---|---|---|
ActivationKeyExpired |
지정한 정품 인증 키가 만료되었습니다. | ActivateGateway |
ActivationKeyInvalid |
지정한 정품 인증 키가 유효하지 않습니다. | ActivateGateway |
ActivationKeyNotFound |
지정한 정품 인증 키를 찾을 수 없습니다. | ActivateGateway |
BandwidthThrottleScheduleNotFound |
지정한 대역폭 제한을 찾을 수 없습니다. | DeleteBandwidthRateLimit |
CannotExportSnapshot |
지정한 스냅샷을 내보낼 수 없습니다. | |
InitiatorNotFound |
지정된 초기자를 찾을 수 없습니다. | DeleteChapCredentials |
DiskAlreadyAllocated |
지정한 디스크가 이미 할당되었습니다. | |
DiskDoesNotExist |
지정한 디스크가 존재하지 않습니다. | |
DiskSizeNotGigAligned |
지정한 디스크가 기가바이트 정렬되어 있지 않습니다. | |
DiskSizeGreaterThanVolumeMaxSize |
지정한 디스크 크기가 최대 볼륨 크기보다 큽니다. | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
지정한 디스크 크기가 볼륨 크기보다 작습니다. | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
지정한 인증서 정보가 중복되어 있습니다. | ActivateGateway |
| 파일 시스템연결엔드포인트 구성충돌 |
기존 파일 시스템 연결 엔드포인트 구성이 지정된 구성과 충돌합니다. |
어소시에이트파일 시스템 |
| 파일 시스템연관엔드포인티패드드레스레디사용 |
지정된 엔드포인트 IP 주소가 이미 사용 중입니다. |
어소시에이트파일 시스템 |
| 파일 시스템연관엔드포인티패드드레스시스 |
파일 시스템 연결 엔드포인트 IP 주소가 누락되었습니다. |
어소시에이트파일 시스템 |
| 파일 시스템연결찾을 수 없음 |
지정한 파일 시스템 연결을 찾을 수 없습니다. |
|
| 파일 시스템찾을 수 없음 |
지정한 파일 시스템을 찾을 수 없습니다. |
어소시에이트파일 시스템 |
GatewayInternalError |
게이트웨이 내부 오류가 발생하였습니다. | |
GatewayNotConnected |
지정한 게이트웨이가 연결되지 않았습니다. | |
GatewayNotFound |
지정한 게이트웨이를 찾을 수 없습니다. | |
GatewayProxyNetworkConnectionBusy |
지정한 게이트웨이 프록시 네트워크 연결이 사용 중입니다. | |
InternalError |
내부 오류가 발생했습니다. | |
InvalidParameters |
지정한 요청에 잘못된 파라미터가 포함되어 있습니다. | |
LocalStorageLimitExceeded |
로컬 스토리지 한도를 초과했습니다. | |
LunInvalid |
지정한 LUN이 유효하지 않습니다. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
최대 볼륨 수를 초과하였습니다. | |
NetworkConfigurationChanged |
게이트웨이 네트워크 구성이 변경되었습니다. | |
NotSupported |
지정한 작업을 지원하지 않습니다. | |
OutdatedGateway |
지정한 게이트웨이의 날짜가 만료되었습니다. | ActivateGateway |
SnapshotInProgressException |
지정한 스냅샷이 진행 중입니다. | DeleteVolume |
SnapshotIdInvalid |
지정한 스냅샷이 유효하지 않습니다. | |
StagingAreaFull |
스테이징 영역이 가득 찼습니다. | |
TargetAlreadyExists |
지정한 대상이 이미 존재합니다. | |
TargetInvalid |
지정한 대상이 유효하지 않습니다. | |
TargetNotFound |
지정한 대상을 찾을 수 없습니다. | |
UnsupportedOperationForGatewayType |
지정한 작업이 게이트웨이 유형에 유효하지 않습니다. | |
VolumeAlreadyExists |
지정한 볼륨이 이미 존재합니다. | |
VolumeIdInvalid |
지정한 볼륨이 유효하지 않습니다. | DeleteVolume |
VolumeInUse |
지정한 볼륨이 이미 사용 중입니다. | DeleteVolume |
VolumeNotFound |
지정한 볼륨을 찾을 수 없습니다. | |
VolumeNotReady |
지정한 볼륨이 아직 준비되지 않았습니다. |
오류 응답
오류가 있는 경우, 응답 헤더 정보에는 다음 내용이 포함됩니다.
-
Content-Type: application/x-amz-json-1.1
-
적절한
4xx또는5xxHTTP 상태 코드
오류 응답의 본문에는 발생한 오류에 대한 정보가 포함됩니다. 다음 샘플 오류 응답은 모든 오류 응답에 공통된 응답 요소의 출력 구문을 나타냅니다.
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
다음 표는 이전 구문에 표시된 JSON 오류 응답 필드를 설명합니다.
- __유형
-
예외의 예외 중 하나.
Type: 문자열
- 오류
-
API별 오류의 세부 정보를 포함합니다. 일반적인 오류(즉 API에 고유한 오류가 아닌 경우)에서는 이 오류 정보가 표시되지 않습니다.
Type: 수집
- errorCode
-
작업 오류 코드 중 하나입니다 .
Type: 문자열
- errorDetails
-
이 필드는 현재 API 버전에서는 사용되지 않습니다.
Type: 문자열
- message
-
작업 오류 코드 메시지 중 하나입니다.
Type: 문자열
오류 응답 예시
DescribeStorediSCSIVolumes API를 사용할 경우 존재하지 않는 게이트웨이 ARN 요청 입력을 지정하면 다음 JSON 본문이 반환됩니다.
{ "__type": "InvalidGatewayRequestException", "message": "The specified volume was not found.", "error": { "errorCode": "VolumeNotFound" } }
Storage Gateway가 요청과 함께 전송된 서명과 일치하지 않는 서명을 계산하면 다음 JSON 본문이 반환됩니다.
{ "__type": "InvalidSignatureException", "message": "The request signature we calculated does not match the signature you provided." }
Storage Gateway
Storage Gateway 작업 목록은 단원을 참조하십시오.작업의AWS Storage GatewayAPI 참조.
