AWS Storage Gateway API 참조

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

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. 아래에 표시된 헤더는 다음과 같습니다.AWS-지정 헤더입니다. 나머지 헤더는 HTTP 트랜잭션에 사용되는 공통 헤더입니다.

Authorization: AWS4-HMAC_SHA456 
Credentials=YourAccessKey/yyymmdd/region/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=CalculatedSignature

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

Host: storagegateway.region.amazonaws.com

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

x-amz-target: StorageGateway_APIversion.operationName

요청에 서명하기

Storage Gateway는 전송한 모든 요청에 서명하여 요청을 인증하도록 요구합니다. 요청에 서명하려면 암호화 해시 함수를 이용해 디지털 서명을 계산해야 합니다. 암호화 해시는 입력을 근거로 하여 고유 해시 값을 반환하는 함수입니다. 해시 함수에 대한 입력에는 요청 텍스트와 보안 액세스 키가 포함됩니다. 해시 함수는 요청에 서명으로 포함하는 해시 값을 반환합니다. 서명은 요청에서 Authorization 헤더의 일부입니다.

Storage Gateway는 요청을 수신한 후 사용자가 요청에 서명할 때와 동일한 해시 함수 및 입력을 사용하여 서명을 재계산합니다. 결과 서명이 요청 서명과 일치할 경우 Storage Gateway는 요청을 처리합니다. 그렇지 않으면 요청이 거부됩니다.

다음을 사용하는 인증 지원AWS서명 버전 4. 서명을 계산하기 위한 프로세스는 다음 세 작업으로 나뉠 수 있습니다.

서명 계산 예시

다음 예시에서는 ListGateways에 대해 서명을 생성하는 세부 과정을 안내합니다. 이 예시는 서명 계산 방법을 점검하기 위한 참조로 사용할 수 있습니다. 다른 참조 계산은 Amazon Web Services 글로서리의 서명 버전 4 테스트 제품군에 포함되어 있습니다.

이 예시에서는 다음과 같이 가정합니다.

일반 요청 구문(JSON 본문 포함)은 다음과 같습니다.

POST / HTTP/1.1
Host: storagegateway.us-east-2.amazonaws.com
x-amz-Date: 20120910T000000Z
Authorization: SignatureToBeCalculated
Content-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은 특정 작업 오류 코드를 부여하는 작업 오류 코드(작업 오류 코드) 메시지 코드 중 하나를 반환합니다.

작업 오류 코드

다음 표에는 AWS Storage Gateway 작업 오류 코드와 해당 코드를 반환할 수 있는 API 간의 매핑이 나와 있습니다. 모든 작업 오류 코드는 두 가지 일반적인 예외 중 하나와 함께 반환됩니다.InternalServerError과InvalidGatewayRequestException—설명됨예외.

오류 응답

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

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

{
    "__type": "String",
    "message": "String",
    "error":
        { "errorCode": "String",
          "errorDetails": "String"
        }
}

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

오류 응답 예시

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 참조.