Este documento proporciona una descripción general de la API de XML de Cloud Storage y está destinado a desarrolladores de software. Se supone que estás familiarizado con los servicios RESTful y la programación web, y que te sientes cómodo con la creación de aplicaciones que operan mediante solicitudes HTTP. Si esto no te describe, considera una de las siguientes alternativas:
Si recién comienzas a usar Cloud Storage, primero debes probar la Guía de inicio rápido de Cloud Console o la Guía de inicio rápido de gsutil. En estos instructivos, se muestran los conceptos básicos del uso de Cloud Storage sin la necesidad de usar la API de forma directa.
Si trabajas en ciertos lenguajes de programación, puedes usar las bibliotecas cliente de Cloud Storage.
Si eres un desarrollador de aplicaciones web o para dispositivos móviles, puedes usar los SDK de Firebase para Cloud Storage.
Si no eres desarrollador de software y deseas almacenar tus datos personales en la nube y compartirlos con otras personas, puedes usar Google Drive.
Descripción general
La API de XML de Cloud Storage es una interfaz RESTful que te permite administrar datos de Cloud Storage de manera programática. Como una API de RESTful, se basa en la información de métodos y la información de alcance para definir las operaciones que se realizarán:
Información del método
Especifica la información del método con métodos HTTP estándar, como
DELETE
,GET
,HEAD
yPUT
.Información de alcance
Especificas la información de alcance con un extremo de acceso público (URI) y varios parámetros de alcance. Para la API de XML, los parámetros de alcance principales son los nombres del depósito y el objeto. Puedes ampliar aún más las operaciones con encabezados HTTP y parámetros de cadena de consulta.
Utiliza métodos HTTP para realizar operaciones en el recurso que especifiques en el alcance. Para ver la lista de operaciones disponibles en la API de XML, consulta Métodos de solicitud a la API de XML.
El acceso a Cloud Storage a través de la API de XML es útil cuando usas herramientas y bibliotecas que deben funcionar en diferentes proveedores de almacenamiento o cuando migras desde otro proveedor de almacenamiento a Cloud Storage. En el último caso, solo debes realizar algunos cambios simples a tus herramientas y bibliotecas existentes para comenzar a enviar solicitudes a Cloud Storage. Para obtener más información sobre la migración a Cloud Storage, consulta Migra de Amazon S3 a Google Cloud Storage.
Solicitudes
La API de XML de Cloud Storage proporciona una interfaz web para realizar solicitudes HTTP y controlar las respuestas HTTP. La API es compatible con los protocolos HTTP/1.1, HTTP/2 y HTTP/3. Cada solicitud implementa un método HTTP estándar. Junto con estos métodos, puedes usar varios encabezados de solicitud HTTP.
Autenticación
Todas las solicitudes a Cloud Storage deben autenticarse, a excepción de las solicitudes realizadas a objetos o depósitos accesibles de forma anónima. Si deseas obtener información detallada sobre cómo configurar los encabezados de autorización para las solicitudes de Cloud Storage, consulta Autenticación.
Extremos
La mayoría de las solicitudes a la API de XML de Cloud Storage usan el URI siguiente para acceder a depósitos y objetos:
storage.googleapis.com
Puedes ampliar este alcance más agregando un depósito y un objeto al URI. La URL resultante puede tomar dos formas:
BUCKET_NAME.storage.googleapis.com/OBJECT_NAME storage.googleapis.com/BUCKET_NAME/OBJECT_NAME
Puedes usar el URI de Cloud Storage con solicitudes no seguras (HTTP) y solicitudes seguras (HTTPS) que usan encriptación de capa de conexión segura (SSL).
Para extremos adicionales, como extremos de carga y descarga dedicados para la API de XML, consulta Solicita extremos.
Encabezados y parámetros de string de consulta
La API de XML de Cloud Storage admite encabezados de solicitud HTTP. También admite varios encabezados de solicitud de extensión (personalizadas), que tienen un prefijo x-goog-
. Los requisitos del encabezado de la solicitud varían según el tipo de solicitud que realices. Entre los encabezados de solicitud de uso frecuente se incluyen los siguientes:
Encabezado de la solicitud | Descripción | Uso |
---|---|---|
Authorization |
String de autenticación para solicitudes | Obligatorio para todas las solicitudes autenticadas. |
Content-Length |
El tamaño del cuerpo de la solicitud (sin incluir los encabezados) en bytes. | Obligatorio para todas las solicitudes PUT y POST, excepto las transferencias fragmentadas. |
Content-Type |
El tipo de MIME del cuerpo de la solicitud, como application/xml o text/html . |
Se recomienda para solicitudes que contienen un cuerpo de entidad. |
Date |
La fecha y la hora de la solicitud. | Obligatorio para todas las solicitudes. |
Host |
El URI para la solicitud. | Obligatorio para todas las solicitudes. |
x-goog-project-id |
El ID del proyecto que deseas usar. | Obligatorio para crear depósitos o enumerar depósitos, excepto cuando se usa la API de XML para interoperabilidad, como compatibilidad con Amazon S3. Para obtener más información, consulta Migra de Amazon S3 a Google Cloud Storage. |
La API de XML de Cloud Storage también admite diversos parámetros de cadena de consulta, que puedes usar para definir el alcance de tus solicitudes. Agrega parámetros de string de consulta a la parte de ruta HTTP de la solicitud con la siguiente sintaxis:
PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...
Para obtener una lista completa de los encabezados de la API de XML y los parámetros de string de consulta, revisa encabezados HTTP y parámetros de string de consulta.
Ejemplo de solicitud
En el siguiente ejemplo, se muestra una solicitud típica de Cloud Storage autenticada. Con esta solicitud, se recupera una lista de objetos que se almacenan en un depósito llamado travel-maps
. La solicitud limita la lista de objetos solo a los objetos que tienen el prefijo /europe/france
.
GET /?prefix=/europe/france/ HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 -0800 Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Respuestas
La API de XML de Cloud Storage muestra encabezados de respuesta HTTP estándar y varios encabezados de respuesta de extensión (personalizadas). Los encabezados de respuesta varían según la operación que realices. Entre los encabezados de respuesta que se usan con frecuencia se incluyen los siguientes:
Encabezado de respuesta | Descripción |
---|---|
Cache-Control |
La configuración de control de caché para la respuesta |
Content-Length |
El tamaño del cuerpo de la respuesta (sin incluir los encabezados) en bytes. |
Content-Type |
El tipo de MIME del cuerpo de la respuesta, como application/xml o text/html . |
Date |
La fecha y hora de la respuesta. |
ETag |
Una etiqueta de entidad HTTP 1.1, que puedes usar para determinar |
si un objeto ha cambiado.
Las respuestas también pueden incluir un código de estado. Cloud Storage usa códigos de estado HTTP estándar. Una respuesta de error incluye un documento XML en el cuerpo de la respuesta, que contiene información sobre las condiciones de error. Si deseas obtener una lista de los códigos de estado que usa la API de XML, consulta Códigos de error y de estados de HTTP.
A continuación, se muestra una respuesta típica de Cloud Storage. Este ejemplo es una respuesta a una solicitud para realizar una lista del contenido de un depósito. El nombre del depósito es travel-maps
y la solicitud tiene alcance para que solo se muestren en la lista los objetos con el prefijo /europe/france/
.
HTTP/1.1 200 OK Content-Length: 4061 Content-Type: application/xml Date: Wed, 17 Feb 2010 23:31:57 GMT Cache-Control: private, max-age=0 <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'> <Name>travel-maps</Name> <Prefix>/europe/france/</Prefix> <Marker></Marker> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/france/cannes.jpg</Key> <LastModified>2010-02-17T22:11:12.487Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <DisplayName></DisplayName> </Owner> </Contents> <Contents> <Key>europe/france/paris.jpg</Key> <LastModified>2010-02-17T22:09:57.457Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <DisplayName></DisplayName> </Owner> </Contents> </ListBucketResult>