Creare e gestire fogli di lavoro

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

Crea un foglio di lavoro

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

Quando crei il file, il metodo restituisce una risorsa spreadsheets. La risorsa restituita contiene spreadsheetId, properties, un elenco di sheets e 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 specifica, utilizza questi metodi:

Dopo aver creato il file del foglio di lavoro, spostalo in una cartella specifica utilizzando il metodo update nella risorsa files dell'API Google Drive. Per ulteriori informazioni, vedi Spostare i file tra le cartelle.
Aggiungi un foglio di lavoro vuoto a una cartella utilizzando il metodo create sulla risorsa files dell'API Drive, specificando application/vnd.google-apps.spreadsheet come mimeType. Per ulteriori informazioni sulla creazione di file, vedi Creare un file in una cartella specifica. Per ulteriori informazioni sui tipi MIME, vedi Tipi MIME supportati per Google Workspace e Google Drive.

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

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

Per spostare o creare un file all'interno di una cartella del Drive condiviso, consulta Implementare il supporto del Drive condiviso.

Per scoprire di più sui limiti di celle e righe in Fogli Google, consulta File archiviabili su Google Drive.

Ottenere un foglio di lavoro

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

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 un elenco di maschere di campo con i campi selezionati impostando il fields parametro di sistema.
Imposta il parametro di query booleano includeGridData su true. Se viene 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 per i 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 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 specifico della cella, con una risposta molto più leggera e rapida.

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

Elenca 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 metodo list dell'API Drive sulla risorsa files, 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 con limitazioni.

Ecco alcuni passaggi successivi che puoi provare:

Per aggiornare un foglio di lavoro, vedi Aggiornare i fogli di lavoro.
Per lavorare con gli smart chip, consulta Smart chip.
Per lavorare con i metadati sviluppatore, consulta Leggere, scrivere e cercare metadati.

Creare e gestire fogli di lavoro Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Crea un foglio di lavoro

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Organizzare i fogli di lavoro nelle cartelle di Google Drive

Ottenere un foglio di lavoro

Elenca fogli di lavoro

HTTP

cURL

Argomenti correlati

Creare e gestire fogli di lavoro