Se usó la API de Cloud Translation para traducir esta página.
Switch to English

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:

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:

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>