Descripción general de la API de XML

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 y PUT.

• 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

Nota: Recomendamos que uses HTTPS cuando leas o escribas datos en Cloud Storage, de modo que tus datos se encriptan durante la transferencia. Cloud Storage encripta de forma automática tus datos antes de que se escriban en el disco. Para obtener más información, consulta Encriptación.

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

Importante: Si quieres entregar contenido a través de un navegador, ten en cuenta que la API de XML entrega contenido desde el mismo origen que el extremo de la solicitud. Si necesitas entregar contenido desde un origen único, considera usar la API de JSON o las descargas autenticadas del navegador.

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>