Crea y administra hojas de cálculo

En este documento, se explica cómo crear y administrar hojas de cálculo en Hojas de cálculo de Google con la API de Google Sheets.

Crea una hoja de cálculo

Para crear un archivo en Hojas de cálculo, usa el método create en el recurso spreadsheets sin parámetros.

Cuando creas el archivo, el método devuelve un recurso spreadsheets. El recurso devuelto contiene un spreadsheetId, un properties, una lista de sheets y un spreadsheetUrl.

En el siguiente ejemplo de código, se muestra cómo crear una hoja de cálculo en blanco con un título especificado.

Apps Script

sheets/api/spreadsheet_snippets.gs

Ver en GitHub

/**
 * Creates a new sheet using the sheets advanced services
 * @param {string} title the name of the sheet to be created
 * @returns {string} the spreadsheet ID
 */
Snippets.prototype.create = (title) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.create() is more appropriate.
  try {
    const sheet = Sheets.newSpreadsheet();
    sheet.properties = Sheets.newSpreadsheetProperties();
    sheet.properties.title = title;
    const spreadsheet = Sheets.Spreadsheets.create(sheet);

    return spreadsheet.spreadsheetId;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/Create.java

Ver en GitHub

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.Spreadsheet;
import com.google.api.services.sheets.v4.model.SpreadsheetProperties;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;

/* Class to demonstrate the use of Spreadsheet Create API */
public class Create {
  /**
   * Create a new spreadsheet.
   *
   * @param title - the name of the sheet to be created.
   * @return newly created spreadsheet id
   * @throws IOException - if credentials file not found.
   */
  public static String createSpreadsheet(String title) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    // Create new spreadsheet with a title
    Spreadsheet spreadsheet = new Spreadsheet()
        .setProperties(new SpreadsheetProperties()
            .setTitle(title));
    spreadsheet = service.spreadsheets().create(spreadsheet)
        .setFields("spreadsheetId")
        .execute();
    // Prints the new spreadsheet id
    System.out.println("Spreadsheet ID: " + spreadsheet.getSpreadsheetId());
    return spreadsheet.getSpreadsheetId();
  }
}

JavaScript

sheets/snippets/sheets_create.js

Ver en GitHub

function create(title, callback) {
  try {
    gapi.client.sheets.spreadsheets.create({
      properties: {
        title: title,
      },
    }).then((response) => {
      if (callback) callback(response);
      console.log('Spreadsheet ID: ' + response.result.spreadsheetId);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_create.js

Ver en GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Creates a new Google Spreadsheet.
 * @param {string} title The title of the new spreadsheet.
 * @return {string} The ID of the created spreadsheet.
 */
async function create(title) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The resource body for creating a new spreadsheet.
  const resource = {
    properties: {
      title,
    },
  };

  // Create the new spreadsheet.
  const spreadsheet = await service.spreadsheets.create({
    resource,
    fields: 'spreadsheetId',
  });

  // Log the ID of the new spreadsheet.
  console.log(`Spreadsheet ID: ${spreadsheet.data.spreadsheetId}`);
  return spreadsheet.data.spreadsheetId;
}

PHP

sheets/snippets/src/SpreadsheetCreate.php

Ver en GitHub

<?php
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets\SpreadSheet;

/**
* create an empty spreadsheet
* 
*/

 function create($title)
    {   
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        try{

            $spreadsheet = new Google_Service_Sheets_Spreadsheet([
                'properties' => [
                    'title' => $title
                    ]
                ]);
                $spreadsheet = $service->spreadsheets->create($spreadsheet, [
                    'fields' => 'spreadsheetId'
                ]);
                printf("Spreadsheet ID: %s\n", $spreadsheet->spreadsheetId);
                return $spreadsheet->spreadsheetId;
        }
        catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
          }
    }

Python

sheets/snippets/sheets_create.py

Ver en GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def create(title):
  """
  Creates the Sheet the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)
    spreadsheet = {"properties": {"title": title}}
    spreadsheet = (
        service.spreadsheets()
        .create(body=spreadsheet, fields="spreadsheetId")
        .execute()
    )
    print(f"Spreadsheet ID: {(spreadsheet.get('spreadsheetId'))}")
    return spreadsheet.get("spreadsheetId")
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: title
  create("mysheet1")

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

Ver en GitHub

spreadsheet = {
  properties: {
    title: 'Sales Report'
  }
}
spreadsheet = service.create_spreadsheet(spreadsheet,
                                         fields: 'spreadsheetId')
puts "Spreadsheet ID: #{spreadsheet.spreadsheet_id}"

Organiza hojas de cálculo en carpetas de Google Drive

De forma predeterminada, la hoja de cálculo creada se guarda en la carpeta raíz del usuario en Google Drive.

Si quieres guardar una hoja de cálculo en una carpeta de Drive específica, usa estos métodos:

• Después de crear el archivo de hoja de cálculo, muévelo a una carpeta específica con el método update en el recurso files de la API de Google Drive. Para obtener más información, consulta Cómo mover archivos entre carpetas.

• Agrega una hoja de cálculo en blanco a una carpeta con el método create en el recurso files de la API de Drive, y especifica application/vnd.google-apps.spreadsheet como mimeType. Para obtener más información sobre cómo crear archivos, consulta Crea un archivo en una carpeta específica. Para obtener más información sobre los tipos de MIME, consulta Tipos de MIME compatibles con Google Workspace y Google Drive.

Para cualquiera de las alternativas, deberás agregar los alcances de la API de Drive adecuados para autorizar la llamada.

Si tu app usa una cuenta de servicio, esta será la propietaria de la hoja de cálculo creada. Luego, este archivo reside en el almacenamiento de Drive dedicado de la cuenta de servicio. Los archivos no aparecen en otras cuentas de almacenamiento de Drive, a menos que se compartan explícitamente. Para obtener más información, consulta Propiedad de los archivos.

Para mover o crear un archivo dentro de una carpeta de unidad compartida, consulta Implementa la compatibilidad con unidades compartidas.

Para obtener más información sobre los límites de celdas y filas en Hojas de cálculo de Google, consulta Archivos que se pueden almacenar en Google Drive.

Obtén una hoja de cálculo

Para obtener una hoja de cálculo, usa el método get en el recurso spreadsheets con el parámetro de ruta de acceso spreadsheetId.

El método devuelve el archivo como una instancia de un recurso spreadsheets. De forma predeterminada, no se devuelven los datos de la hoja de cálculo. El recurso que se devuelve contiene la estructura y los metadatos de la hoja de cálculo, incluidas las propiedades de la hoja de cálculo (como el título, la configuración regional y la zona horaria) y cierta información detallada de la hoja (como el formato y los rangos protegidos).

Para incluir datos en un recurso spreadsheets, usa estos dos métodos:

• Especifica una lista de máscara de campo con los campos seleccionados configurando el parámetro del sistema fields.

• Establece el parámetro de consulta booleano includeGridData en true. Si se establece una máscara de campo, se ignora el parámetro includeGridData.

Cuando trabajes con hojas de cálculo grandes, te recomendamos que solo consultes los campos específicos que necesites. El método get devuelve todos los datos asociados con la hoja de cálculo, por lo que las consultas generales para hojas de cálculo grandes pueden ser lentas. Por ejemplo, para leer el número 100 de una celda, spreadsheets.get devuelve el valor de la celda más los metadatos (como el nombre de la fuente, el tamaño, etcétera), lo que genera cargas útiles JSON grandes que son lentas de analizar. En comparación, una llamada similar a values.get solo devuelve el valor de la celda específica, lo que genera una respuesta mucho más ligera y rápida.

Para obtener más información sobre el recurso spreadsheets.values, incluidos spreadsheets.values.get y spreadsheets.values.batchGet, consulta los siguientes documentos:

• Leer y escribir valores de celdas
• Lectura básica

Mostrar lista de hojas de cálculo

La API de Sheets no ofrece un método para enumerar las hojas de cálculo de los usuarios autenticados.

Para recuperar una lista de hojas de cálculo, puedes usar el método list de la API de Drive en el recurso files, especificando application/vnd.google-apps.spreadsheet como mimeType:

HTTP

GET https://www.googleapis.com/drive/v3/files?q=mimeType='application/vnd.google-apps.spreadsheet'

cURL

curl -X GET "https://www.googleapis.com/drive/v3/files?q=mimeType='application/vnd.google-apps.spreadsheet'" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -H "Accept: application/json"

Reemplaza ACCESS_TOKEN por el token de acceso que otorga acceso a la API.

Para usar el método files.list para enumerar las hojas de cálculo de un usuario, se requiere un alcance de la API de Drive restringido.

Temas relacionados

Estos son algunos pasos que puedes seguir:

• Para actualizar una hoja de cálculo, consulta Actualiza hojas de cálculo.

• Para trabajar con chips inteligentes, consulta Chips inteligentes.

• Para trabajar con metadatos del desarrollador, consulta Cómo leer, escribir y buscar metadatos.