Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Referencia de la 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 información acerca de las regiones y los puntos de enlace disponibles para Storage Gateway, consulte Puntos de enlace y cuotas de AWS Storage Gateway en la Referencia general de AWS.
nota
También puede utilizar los SDK de AWS cuando desarrolle aplicaciones con Storage Gateway. Los SDK de AWS para Java, .NET y PHP integran la API de Storage Gateway subyacente y simplifican las tareas de programación. Para obtener información sobre la descarga de las bibliotecas de SDK, consulte Código de muestra y bibliotecas
Temas
Encabezados de solicitud obligatorios de AWS Storage Gateway
En esta sección se describen los encabezados obligatorios que debe enviar con cada solicitud POST a AWS 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 a AWS Storage Gateway. Los encabezados siguientes que comienzan con “x-amz” son encabezados específicos de AWS. El resto de los encabezados que se muestran son encabezados comunes utilizados en transacciones HTTP.
| Encabezado | Descripción |
|---|---|
Authorization |
El encabezado de autorización contiene varios elementos de información sobre la solicitud que permiten a AWS Storage Gateway determinar si la solicitud es una acción válida para el solicitante. El formato de este encabezado es el siguiente (se han agregado saltos de línea para mejorar la legibilidad):
En la sintaxis anterior, debe especificar el valor de YourAccessKey, el año, el mes y el día (yyyymmdd), la región y el valor de CalculatedSignature. El formato del encabezado de autorización se rige por los requisitos del proceso de firma de AWS V4. Los detalles de la firma se tratan en el tema Firmar solicitudes. |
Content-Type |
Utilice
|
Host |
Utilice el encabezado de host para especificar el punto de conexión de AWS Storage Gateway donde desea enviar la solicitud. Por ejemplo,
|
x-amz-date |
Debe proporcionar la marca temporal que figura en el encabezado HTTP
|
x-amz-target |
Este encabezado especifica la versión de la API y la operación que se está solicitando. Los valores de encabezado de destino se forman concatenando la versión de la API con el nombre de la API y están en el siguiente formato.
El valor de operationName (p. ej. "ActivateGateway") se encuentra en la lista de la API, Referencia de la API para Storage Gateway. |
Firmar solicitudes
Storage Gateway requiere que se firmen todas las solicitudes enviadas 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 mediante AWS Signature Version 4. El proceso para calcular una firma se puede dividir en tres tareas:
-
Tarea 1: Creación de una solicitud canónica
Reorganice la solicitud HTTP en formato canónico. Es preciso utilizar un formato canónico, ya que Storage Gateway utiliza el mismo formato canónico cuando recalcula una firma para compararla con la que se ha enviado.
-
Tarea 2: Creación de una cadena para firmar
Crear una cadena que se utilizará como uno de los valores de entrada de la función hash criptográfica. La cadena, denominada cadena para firmar, es una concatenación del nombre del algoritmo hash, la fecha de la solicitud, una cadena de ámbito de credenciales y la solicitud en formato canónico de la tarea anterior. La cadena del ámbito de credenciales es una concatenación de fecha, región e información del servicio.
-
Cree una firma para su solicitud mediante una función hash criptográfica que acepte dos cadenas de entrada: la cadena para firmar y una clave derivada. La clave derivada se calcula a partir de la clave de acceso secreta, utilizando el ámbito de credenciales para crear una serie de códigos de autenticación de mensajes basados en hash (HMAC).
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.
El ejemplo supone lo siguiente:
-
La marca temporal de la solicitud es "Mon, 10 Sep 2012 00:00:00" GMT.
-
El punto de conexión es la región Este de EE. UU. (Ohio).
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:SignatureToBeCalculatedContent-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 esta API (ni para ninguna API de Storage Gateway).
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, 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 el siguiente:
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 solamente 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.
| Excepción | Mensaje | Código de estado HTTP |
|---|---|---|
IncompleteSignatureException |
La firma especificada está incompleta. | 400 Solicitud errónea |
InternalFailure |
El procesamiento de la solicitud ha fallado debido a un error o una excepción desconocidos. | 500 Error de servidor interno |
InternalServerError |
Uno de los mensajes de código de error de operación Códigos de error de operación. | 500 Error de servidor interno |
InvalidAction |
La acción u operación solicitada no es válida. | 400 Solicitud errónea |
InvalidClientTokenId |
El certificado X.509 o el ID de clave de acceso de AWS proporcionado no existen en nuestros registros. | 403: prohibido |
InvalidGatewayRequestException |
Uno de los mensajes de código de error de operación de Códigos de error de operación. | 400 Solicitud errónea |
InvalidSignatureException |
La firma de solicitud que calculamos no coincide con la firma que proporcionó. Compruebe la clave de acceso de AWS y el método de firma. | 400 Solicitud errónea |
MissingAction |
Falta un parámetro de operación o acción en la solicitud. | 400 Solicitud errónea |
MissingAuthenticationToken |
La solicitud debe contener un certificado X.509 o bien un ID de clave de acceso de AWS válido (registrado). | 403: prohibido |
RequestExpired |
La solicitud es posterior a la fecha de vencimiento o la fecha de la solicitud (con un margen de 15) o la fecha de la solicitud ocurre más de 15 minutos en el futuro. | 400 Solicitud errónea |
SerializationException |
Se ha producido un error durante la serialización. Compruebe que la carga útil de JSON esté bien formada. | 400 Solicitud errónea |
ServiceUnavailable |
La solicitud no se ha ejecutado correctamente debido a un error temporal del servidor. | 503 Service Unavailable |
SubscriptionRequiredException |
El ID de clave de acceso de AWS necesita una suscripción al servicio. | 400 Solicitud errónea |
ThrottlingException |
Tasa superada. | 400 Solicitud errónea |
TooManyRequests |
Demasiadas solicitudes. | 429 Demasiadas solicitudes |
UnknownOperationException |
Se ha especificado una operación desconocida. Las operaciones válidas se muestran en Acciones de la API de Storage Gateway. | 400 Solicitud errónea |
UnrecognizedClientException |
El token de seguridad incluido en la solicitud no es válido. | 400 Solicitud errónea |
ValidationException |
El valor de un parámetro de entrada es incorrecto o está fuera del intervalo. | 400 Solicitud errónea |
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.
| Código de error de operación | Mensaje | Operaciones que devuelven este código de error |
|---|---|---|
ActivationKeyExpired |
La clave de activación especificada ha vencido. | ActivateGateway |
ActivationKeyInvalid |
La clave de activación especificada no es válida. | ActivateGateway |
ActivationKeyNotFound |
La clave de activación especificada no se ha encontrado. | ActivateGateway |
BandwidthThrottleScheduleNotFound |
La limitación de ancho de banda especificada no se ha encontrado. | DeleteBandwidthRateLimit |
CannotExportSnapshot |
La snapshot especificada no se puede exportar. | |
InitiatorNotFound |
El iniciador especificado no se ha encontrado. | DeleteChapCredentials |
DiskAlreadyAllocated |
El disco especificado ya está asignado. | |
DiskDoesNotExist |
El disco especificado no existe. | |
DiskSizeNotGigAligned |
El disco especificado no está alineado en gigabytes. | |
DiskSizeGreaterThanVolumeMaxSize |
El tamaño de disco especificada es mayor que el tamaño del volumen máximo. | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
El tamaño de disco especificada es menor que el tamaño del volumen. | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
La información de certificado especificada es un duplicado. | ActivateGateway |
| FileSystemAssociationEndpointConfigurationConflict |
La configuración de punto de conexión final de la asociación de sistema de archivos entra en conflicto con la configuración especificada. |
AssociateFileSystem |
| FileSystemAssociationEndpointIpAddressAlreadyInUse |
La dirección IP del punto de conexión especificada ya está en uso. |
AssociateFileSystem |
| FileSystemAssociationEndpointIpAddressMissing |
Falta la dirección IP del punto de conexión de la asociación del sistema de archivos. |
AssociateFileSystem |
| FileSystemAssociationNotFound |
No se ha encontrado la asociación de sistema de archivos especificada. |
|
| FileSystemNotFound |
No se ha encontrado el sistema de archivos especificado. |
AssociateFileSystem |
GatewayInternalError |
Se produjo un error interno de la gateway. | |
GatewayNotConnected |
La gateway especificada no está conectada. | |
GatewayNotFound |
La gateway especificada no se ha encontrado. | |
GatewayProxyNetworkConnectionBusy |
La conexión de red proxy de la gateway especificada está ocupada. | |
InternalError |
Se ha producido un error interno. | |
InvalidParameters |
La solicitud especificada contiene parámetros no válidos. | |
LocalStorageLimitExceeded |
El límite de almacenamiento local se ha superado. | |
LunInvalid |
El valor de LUN especificado no es válido. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
El número de volúmenes máximo se ha superado. | |
NetworkConfigurationChanged |
La configuración de red de la gateway ha cambiado. | |
NotSupported |
La operación especificada no es compatible. | |
OutdatedGateway |
La gateway especificada está obsoleta. | ActivateGateway |
SnapshotInProgressException |
La snapshot especificada está en curso. | DeleteVolume |
SnapshotIdInvalid |
La snapshot especificada no es válida. | |
StagingAreaFull |
El espacio provisional está lleno. | |
TargetAlreadyExists |
El destino especificado ya existe. | |
TargetInvalid |
El destino especificado no es válido. | |
TargetNotFound |
El destino especificado no se ha encontrado. | |
UnsupportedOperationForGatewayType |
La operación especificada no es válida para el tipo de gateway. | |
VolumeAlreadyExists |
El volumen especificado ya existe. | |
VolumeIdInvalid |
El volumen especificado no es válido. | DeleteVolume |
VolumeInUse |
El volumen especificado ya se está usando. | DeleteVolume |
VolumeNotFound |
El volumen especificado no se ha encontrado. | |
VolumeNotReady |
El volumen especificado no está listo. |
Respuestas de error
Cuando se produce un error, la información de encabezado de la respuesta contiene:
-
Content-Type: application/x-amz-json-1.1
-
Un código de estado HTTP
4xxo5xxadecuado
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.
- __type
-
Una de las excepciones de Excepciones.
Tipo: cadena
- Error
-
Contiene detalles del error específicos de la API. En los errores generales (es decir, no específicos de ninguna API), esta información de error no se muestra.
Tipo: recopilación
- errorCode
-
Uno de los códigos de error de operación .
Tipo: cadena
- errorDetails
-
Este campo no se utiliza en la versión actual de la API.
Tipo: cadena
- message
-
Uno de los mensajes de código de error de operación.
Tipo: cadena
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." }
Acciones de la API de Storage Gateway
Para ver una lista completa de las operaciones de Storage Gateway, consulte Acciones en la Referencia de la API de AWS Storage Gateway.
