Creare e gestire fogli di lavoro

Questo documento spiega come creare e gestire i fogli di lavoro in Fogli Google utilizzando l'API Google Sheets.

Crea un foglio di lavoro

Per creare un file in Fogli, utilizza il create metodo sulla spreadsheets risorsa senza parametri.

Quando crei il file, il metodo restituisce una risorsa spreadsheets. La risorsa restituita contiene un spreadsheetId, properties, un elenco di sheets e un spreadsheetUrl.

Il seguente esempio di codice mostra come creare un foglio di lavoro vuoto con un titolo specificato.

Apps Script

sheets/api/spreadsheet_snippets.gs

Visualizza su 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

Visualizza su 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

Visualizza su 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

Visualizza su 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

Visualizza su 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

Visualizza su 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

Visualizza su GitHub

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

Organizzare i fogli di lavoro nelle cartelle di Google Drive

Per impostazione predefinita, il foglio di lavoro creato viene salvato nella cartella principale dell'utente su Google Drive.

Se vuoi salvare un foglio di lavoro in una cartella di Drive specificata, utilizza questi metodi:

• Dopo aver creato il file del foglio di lavoro, spostalo in una cartella specifica utilizzando il update metodo sulla files risorsa dell'API Google Drive. Per saperne di più, consulta Spostare i file tra le cartelle.

• Aggiungi un foglio di lavoro vuoto a una cartella utilizzando il create metodo sulla files risorsa dell'API Drive, specificando application/vnd.google-apps.spreadsheet come mimeType. Per saperne di più sulla creazione di file, consulta Creare un file in una cartella specifica. Per saperne di più sui tipi MIME, consulta Tipi MIME supportati per Google Workspace e Google Drive.

Per entrambe le alternative, dovrai aggiungere gli ambiti dell'API Drive appropriati per autorizzare la chiamata.

Se la tua app utilizza un account di servizio, quest'ultimo è il proprietario del foglio di lavoro creato. Questo file si trova nello spazio di archiviazione di Drive dedicato dell'account di servizio. I file non vengono visualizzati in altri account di spazio di archiviazione di Drive, a meno che non siano condivisi esplicitamente. Per saperne di più, consulta Proprietà dei file.

Per spostare o creare un file in una cartella di un Drive condiviso, consulta Implementare il supporto per i Drive condivisi.

Per saperne di più sui limiti di celle e righe in Fogli Google, consulta File che puoi archiviare in Google Drive.

Trova un foglio di lavoro

Per trovare un foglio di lavoro, utilizza il get metodo sulla spreadsheets risorsa con il spreadsheetId parametro del percorso.

Il metodo restituisce il file come istanza di una risorsa spreadsheets. Per impostazione predefinita, i dati all'interno del foglio di lavoro non vengono restituiti. La risorsa restituita contiene la struttura e i metadati del foglio di lavoro, incluse le proprietà del foglio di lavoro (come titolo, impostazioni internazionali e fuso orario) e alcune informazioni dettagliate sul foglio (come formattazione e intervalli protetti).

Per includere i dati in una risorsa spreadsheets, utilizza questi due metodi:

• Specifica una maschera di campo che elenca i campi selezionati impostando il fields parametro di sistema.

• Imposta il parametro di query booleano includeGridData su true. Se è impostata una maschera di campo, il parametro includeGridData viene ignorato.

Quando lavori con fogli di lavoro di grandi dimensioni, ti consigliamo di eseguire query solo sui campi specifici del foglio di lavoro di cui hai bisogno. Il metodo get restituisce tutti i dati associati al foglio di lavoro, pertanto le query generali per i fogli di lavoro di grandi dimensioni possono essere lente. Ad esempio, per leggere il numero 100 da una cella, spreadsheets.get restituisce il valore della cella più i metadati (come nome del carattere, dimensione e così via), generando payload JSON di grandi dimensioni che sono lenti da analizzare. Al contrario, una chiamata simile a values.get restituisce solo il valore della cella specifica, con una risposta molto più leggera e veloce.

Per saperne di più sulla risorsa spreadsheets.values, inclusi spreadsheets.values.get e spreadsheets.values.batchGet, consulta i seguenti documenti:

• Leggere e scrivere i valori delle celle
• Lettura di base

Elenca i fogli di lavoro

L'API Sheets non offre un metodo per elencare i fogli di lavoro per gli utenti autenticati.

Per recuperare un elenco di fogli di lavoro, puoi utilizzare il list metodo dell'API Drive sulla files risorsa, specificando application/vnd.google-apps.spreadsheet come 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"

Sostituisci ACCESS_TOKEN con il token di accesso che concede l'accesso all'API.

L'utilizzo del metodo files.list per elencare i fogli di lavoro di un utente richiede un ambito dell'API Drive limitato.

Argomenti correlati

Di seguito sono riportati alcuni possibili passaggi successivi:

• Per aggiornare un foglio di lavoro, consulta Aggiornare i fogli di lavoro.

• Per lavorare con gli smart chip, consulta Smart chips.

• Per lavorare con i metadati degli sviluppatori, consulta Leggere, scrivere e cercare metadati.