Criar e gerenciar planilhas

Este documento explica como criar e gerenciar planilhas no Google Planilhas usando a API Google Sheets.

Criar uma planilha

Para criar um arquivo no Planilhas, use o método create no recurso spreadsheets sem parâmetros.

Quando você cria o arquivo, o método retorna um recurso spreadsheets. O recurso retornado contém um spreadsheetId, um properties, uma lista de sheets e um spreadsheetUrl.

O exemplo de código a seguir mostra como criar uma planilha em branco com um título especificado.

Apps Script

sheets/api/spreadsheet_snippets.gs

Ver no 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 no 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 no 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 no 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 no 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 no 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 no GitHub

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

Organizar planilhas em pastas do Google Drive

Por padrão, a planilha criada é salva na pasta raiz do usuário no Google Drive.

Se você quiser salvar uma planilha em uma pasta específica do Drive, use estes métodos:

Depois que o arquivo de planilha for criado, mova-o para uma pasta específica usando o método update no recurso files da API Google Drive. Para mais informações, consulte Mover arquivos entre pastas.
Adicione uma planilha em branco a uma pasta usando o método create no recurso files da API Drive, especificando application/vnd.google-apps.spreadsheet como o mimeType. Para mais informações sobre como criar arquivos, consulte Criar um arquivo em uma pasta específica. Para mais informações sobre tipos MIME, consulte Tipos MIME compatíveis com o Google Workspace e o Google Drive.

Para qualquer uma das alternativas, é necessário adicionar os escopos da API Drive adequados para autorizar a chamada.

Se o app estiver usando uma conta de serviço, ela será a proprietária da planilha criada. Esse arquivo fica no armazenamento dedicado do Drive da conta de serviço. Os arquivos não aparecem em outras contas de armazenamento no Drive, a menos que sejam compartilhados explicitamente. Para mais informações, consulte Propriedade de arquivos.

Para mover ou criar um arquivo em uma pasta de drive compartilhado, consulte Implementar suporte a drives compartilhados.

Para saber mais sobre os limites de células e linhas no Google Planilhas, consulte Arquivos que você pode armazenar no Google Drive.

Receber uma planilha

Para receber uma planilha, use o método get no recurso spreadsheets com o parâmetro de caminho spreadsheetId.

O método retorna o arquivo como uma instância de um recurso spreadsheets. Por padrão, os dados da planilha não são retornados. O recurso retornado contém a estrutura e os metadados da planilha, incluindo as propriedades dela (como título, localidade e fuso horário) e algumas informações detalhadas da página (como formatação e intervalos protegidos).

Para incluir dados em um recurso spreadsheets, use estes dois métodos:

Especifique uma máscara de campo que liste os campos selecionados definindo o parâmetro de sistema fields.
Defina o parâmetro de consulta booleano includeGridData como true. Se uma máscara de campo for definida, o parâmetro includeGridData será ignorado.

Ao trabalhar com planilhas grandes, recomendamos consultar apenas os campos específicos de que você precisa. O método get retorna todos os dados associados à planilha. Portanto, consultas gerais para planilhas grandes podem ser lentas. Por exemplo, para ler o número 100 de uma célula, spreadsheets.get retorna o valor da célula mais metadados (como nome da fonte, tamanho etc.), resultando em payloads JSON grandes que são lentos para analisar. Em comparação, uma chamada semelhante para values.get retorna apenas o valor da célula específica, resultando em uma resposta muito mais leve e rápida.

Para mais informações sobre o recurso spreadsheets.values, incluindo spreadsheets.values.get e spreadsheets.values.batchGet, consulte os seguintes documentos:

Listar planilhas

A API Sheets não oferece um método para listar planilhas de usuários autenticados.

Para recuperar uma lista de planilhas, use o método list da API Drive no recurso files, especificando application/vnd.google-apps.spreadsheet como o 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"

Substitua ACCESS_TOKEN pelo token de acesso que concede acesso à API.

Para listar as planilhas de um usuário usando o método files.list, é necessário um escopo restrito da API Drive.

Confira algumas das próximas etapas:

Para atualizar uma planilha, consulte Atualizar planilhas.
Para trabalhar com ícones inteligentes, consulte Ícones inteligentes.
Para trabalhar com metadados do desenvolvedor, consulte Ler, gravar e pesquisar metadados.

Criar e gerenciar planilhas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Criar uma planilha

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Organizar planilhas em pastas do Google Drive

Receber uma planilha

Listar planilhas

HTTP

cURL

Temas relacionados

Criar e gerenciar planilhas