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 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.
nota
También puede utilizar laAWSSDK al desarrollar aplicaciones con Storage Gateway. LaAWSLos SDK para Java, .NET y PHP envuelven la API de Storage Gateway subyacente, lo que simplifica 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
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.
| Encabezado | Description (Descripción) |
|---|---|
Authorization |
El encabezado de autorización contiene varios elementos de información sobre la solicitud que habilitanAWS Storage Gatewaypara 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 delAWSProceso de firma V4. Los detalles de la firma se tratan en el tema Firma de solicitudes. |
Content-Type |
Usar
|
Host |
Use el encabezado del host para especificar elAWS Storage Gatewaypunto final al que envías tu 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 API para Storage Gateway. |
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:
-
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.
-
Tarea 3: Creación de una firma
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. 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 marca temporal de la solicitud es "Mon, 10 Sep 2012 00:00:00" GMT.
-
El punto de enlace es la región EE.UU. Este (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 este API (ni para ningún 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, 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.
| Excepción | Mensaje | Código de estado HTTP |
|---|---|---|
IncompleteSignatureException |
La firma especificada está incompleta. | 400: solicitud maligna |
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ónCó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 maligna |
InvalidClientTokenId |
El certificado X.509 oAWSEl ID de clave de acceso proporcionado no existe 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 maligna |
InvalidSignatureException |
La firma de solicitud que calculamos no coincide con la firma que proporcionó. Compruebe suAWSClave de acceso y método de firma. | 400: solicitud maligna |
MissingAction |
Falta un parámetro de operación o acción en la solicitud. | 400: solicitud maligna |
MissingAuthenticationToken |
La solicitud debe contener un valor válido (registrado)AWSID de clave de acceso o certificado X.509. | 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 maligna |
SerializationException |
Se ha producido un error durante la serialización. Compruebe que la carga útil de JSON esté bien formada. | 400: solicitud maligna |
ServiceUnavailable |
La solicitud no se ha ejecutado correctamente debido a un error temporal del servidor. | 503 Service Unavailable |
SubscriptionRequiredException |
LaAWSEl ID de clave de acceso de necesita una suscripción al servicio. | 400: solicitud maligna |
ThrottlingException |
Tasa superada. | 400: solicitud maligna |
UnknownOperationException |
Se ha especificado una operación desconocida. Las operaciones válidas se muestran en Operaciones en Storage Gateway. | 400: solicitud maligna |
UnrecognizedClientException |
El token de seguridad incluido en la solicitud no es válido. | 400: solicitud maligna |
ValidationException |
El valor de un parámetro de entrada es incorrecto o está fuera del intervalo. | 400: solicitud maligna |
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 |
| Conflicto de configuración de endpoint de asociación de sistemas de archivos |
La configuración de endpoint de File System Association existente entra en conflicto con la configuración especificada. |
Sistema de archivos asociado |
| Dirección de punto final de la asociación del sistema de archivos ya en uso |
La dirección IP del endpoint especificada ya está en uso. |
Sistema de archivos asociado |
| Falta la dirección IP del punto final de la asociación del sistema de archivos |
Falta la dirección IP del endpoint de la asociación del sistema de archivos. |
Sistema de archivos asociado |
| No se ha encontrado la asociación del sistema de archivos |
La asociación del sistema de archivos especificada no se ha encontrado. |
|
| No se ha encontrado el sistema de archivos |
El sistema de archivos especificado no se ha encontrado. |
Sistema de archivos asociado |
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.
Type: 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.
Type: Recopilación
- errorCode
-
Uno de los códigos de error de operación .
Type: Cadena
- errorDetails
-
Este campo no se utiliza en la versión actual de la API.
Type: Cadena
- message
-
Uno de los mensajes de código de error de operación.
Type: 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." }
Operaciones en Storage Gateway
Para ver la lista de operaciones de Storage Gateway, consulteActionsen laAWS Storage GatewayReferencia de la API.
