Referencia de API para Storage Gateway

Además de utilizar la consola, puede utilizar la API de AWS Storage Gateway para configurar y administrar las gateways mediante programación. En esta sección se describen las operaciones de AWS Storage Gateway, la solicitud de formas para la autenticación y la administración de errores. Para obtener más información acerca de las regiones y los puntos de enlace disponibles para Storage Gateway, consulteAWS Storage GatewayCuotas y puntos de enlace deen laAWSReferencia general de.

AWS Storage GatewayEncabezados de solicitud obligatorios

En esta sección se describen los encabezados obligatorios que debe enviar con cada solicitud POST aAWS Storage Gateway. Puede incluir encabezados HTTP para identificar información clave sobre la solicitud, incluidas la operación que desea invocar, la fecha de la solicitud y la información que indica su autorización como remitente de la solicitud. Los encabezados no distinguen entre mayúsculas y minúsculas y el orden de los encabezados no es importante.

En el siguiente ejemplo, se muestran los encabezados que se utilizan en la operación 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

Los siguientes son los encabezados que se deben incluir con las solicitudes POST paraAWS Storage Gateway. Los encabezados siguientes que comienzan con «x-amz» sonAWS-Encabezados específicos. El resto de los encabezados que se muestran son encabezados comunes utilizados en transacciones 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

Firma de solicitudes

Storage Gateway requiere que se firmen todas las solicitudes que se envíen, para autenticarlas. Para firmar una solicitud, se calcula una firma digital mediante una función hash criptográfica. Un hash criptográfico es una función que devuelve un valor hash único basado en la entrada. La entrada a la función hash incluye el texto de la solicitud y la clave de acceso secreta. La función hash devuelve un valor hash que se incluye en la solicitud como la firma. La firma forma parte del encabezado de la Authorization de la solicitud.

Tras recibir la solicitud, Storage Gateway recalcula la firma utilizando la misma función hash y los datos especificados para firmar la solicitud. Si la firma resultante coincide con la firma de la solicitud, Storage Gateway procesa la solicitud. De lo contrario, la solicitud se rechaza.

Storage Gateway admite la autenticación medianteAWSSignature Version 4. El proceso para calcular una firma se puede dividir en tres tareas:

Ejemplo de cálculo de firma

En el siguiente ejemplo, se presentan los detalles de la creación de una firma para ListGateways. Puede utilizar el ejemplo como referencia para comprobar su método de cálculo de firmas. Encontrará otros cálculos de referencia en Conjunto de pruebas de Signature Version 4, en la Referencia general de Amazon Web Services.

El ejemplo supone lo siguiente:

La sintaxis general de la solicitud (incluido el cuerpo JSON) es:

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
{}

El formato canónico de la solicitud calculado para es:

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

La última línea de la solicitud canónica es el hash del cuerpo de la solicitud. Además, observe que la tercera línea de la solicitud canónica está vacía. Esto se debe a que no hay parámetros de consulta para este API (ni para ningún API de Storage Gateway).

La cadena para firmar de es:

AWS4-HMAC-SHA256
20120910T000000Z
20120910/us-east-2/storagegateway/aws4_request
92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e

La primera línea de la cadena para firmar es el algoritmo, la segunda es la marca temporal, la tercera es el ámbito de credenciales y la última es el hash de la solicitud canónica de la tarea 1.

En , la clave derivada se pude representar como sigue:

derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-2"),"storagegateway"),"aws4_request")

Si se utiliza la clave de acceso secreta, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, entonces la firma calculada es:

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

El último paso consiste en construir el encabezado Authorization. Para la clave de acceso de demostración AKIAIOSFODNN7EXAMPLE, el encabezado (al que se han agregado saltos de línea para que resulte más legible) es:

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

Respuestas de error

En esta sección se ofrece información de referencia acerca de errores de AWS Storage Gateway. Estos errores se representan mediante una excepción de error y un código de error de operación. Por ejemplo, cualquier respuesta de la API devuelve la excepción de error InvalidSignatureException si hay un problema con la firma de la solicitud. Sin embargo, el código de error de operación ActivationKeyInvalid solamente lo devuelve la API ActivateGateway.

Según el tipo de error, Storage Gateway puede devolver solo una excepción o puede devolver una excepción y un código de error de operación. Ejemplos de respuestas de error se muestran en Respuestas de error.

Excepciones

La siguiente tabla muestra las excepciones de la API AWS Storage Gateway. Cuando una operación de AWS Storage Gateway devuelve una respuesta de error, el cuerpo de la respuesta contiene una de estas excepciones. Las excepciones InternalServerError e InvalidGatewayRequestException devuelven uno de los códigos de mensaje Códigos de error de operación de los códigos de error de operación que proporcionan el código de error de operación específico.

Códigos de error de operación

En la tabla siguiente se muestra el mapeo entre los códigos de error de operación de AWS Storage Gateway y las API que pueden devolver los códigos. Todos los códigos de error de operación se devuelven con una o dos excepciones generales, InternalServerError e InvalidGatewayRequestException que se describen en Excepciones.

Respuestas de error

Cuando se produce un error, la información de encabezado de la respuesta contiene:

El cuerpo de una respuesta de error contiene información sobre el error que se ha producido. El siguiente ejemplo de respuesta de error muestra la sintaxis de salida de los elementos de respuesta comunes a todas las respuestas de error.

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

En la tabla siguiente se explican los campos de respuesta de error JSON que se muestran en la sintaxis anterior.

Ejemplos de respuestas de error

El siguiente cuerpo JSON se devuelve si utiliza la API DescribeStorediSCSIVolumes y especifica una entrada de solicitud ARN de gateway que no existe.

{
  "__type": "InvalidGatewayRequestException",
  "message": "The specified volume was not found.",
  "error": {
    "errorCode": "VolumeNotFound"
  }
}

El siguiente cuerpo JSON se devuelve si Storage Gateway calcula una firma que no coincida con la firma enviada con una solicitud.

{  
  "__type": "InvalidSignatureException",  
  "message": "The request signature we calculated does not match the signature you provided." 
}  

Operaciones en Storage Gateway

Para ver la lista de operaciones de Storage Gateway, consulteActionsen laAWS Storage GatewayReferencia de la API.