Créer et gérer des feuilles de calcul

Ce document explique comment créer et gérer des feuilles de calcul dans Google Sheets à l'aide de l'API Google Sheets.

Créer une feuille de calcul

Pour créer un fichier dans Sheets, utilisez la méthode create sur la ressource spreadsheets sans aucun paramètre.

Lorsque vous créez le fichier, la méthode renvoie une ressource spreadsheets. La ressource renvoyée contient un spreadsheetId, un properties, une liste de sheets et un spreadsheetUrl.

L'exemple de code suivant montre comment créer une feuille de calcul vide avec un titre spécifié.

Apps Script

sheets/api/spreadsheet_snippets.gs
/**
 * 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
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
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
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
<?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
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
spreadsheet = {
  properties: {
    title: 'Sales Report'
  }
}
spreadsheet = service.create_spreadsheet(spreadsheet,
                                         fields: 'spreadsheetId')
puts "Spreadsheet ID: #{spreadsheet.spreadsheet_id}"

Organiser les feuilles de calcul dans des dossiers Google Drive

Par défaut, la feuille de calcul créée est enregistrée dans le dossier racine de l'utilisateur sur Google Drive.

Si vous souhaitez enregistrer une feuille de calcul dans un dossier Drive spécifique, utilisez l'une des méthodes suivantes :

Dans les deux cas, vous devrez ajouter les scopes de l'API Drive appropriés pour autoriser l'appel.

Si votre application utilise un compte de service, celui-ci est propriétaire de la feuille de calcul créée. Ce fichier réside ensuite dans l'espace de stockage Drive dédié au compte de service. Les fichiers n'apparaissent pas dans d'autres comptes de stockage Drive, sauf s'ils sont explicitement partagés. Pour en savoir plus, consultez Propriété des fichiers.

Pour déplacer ou créer un fichier dans un dossier de Drive partagé, consultez Implémenter la prise en charge des Drive partagés.

Pour en savoir plus sur les limites de cellules et de lignes dans Google Sheets, consultez Fichiers pouvant être stockés dans Google Drive.

Obtenir une feuille de calcul

Pour obtenir une feuille de calcul, utilisez la méthode get sur la ressource spreadsheets avec le paramètre de chemin d'accès spreadsheetId.

La méthode renvoie le fichier sous la forme d'une instance de ressource spreadsheets. Par défaut, les données de la feuille de calcul ne sont pas renvoyées. La ressource renvoyée contient la structure et les métadonnées de la feuille de calcul, y compris les propriétés de la feuille de calcul (telles que le titre, les paramètres régionaux et le fuseau horaire) et des informations détaillées sur la feuille (telles que la mise en forme et les plages protégées).

Pour inclure des données dans une ressource spreadsheets, utilisez les deux méthodes suivantes :

  • Spécifiez un masque de champ listant les champs sélectionnés en définissant le paramètre système fields.

  • Définissez le paramètre de requête booléen includeGridData sur true. Si un masque de champ est défini, le paramètre includeGridData est ignoré.

Lorsque vous travaillez avec de grandes feuilles de calcul, nous vous recommandons de n'interroger que les champs spécifiques dont vous avez besoin. La méthode get renvoie toutes les données associées à la feuille de calcul. Les requêtes générales pour les grandes feuilles de calcul peuvent donc être lentes. Par exemple, pour lire le nombre 100 à partir d'une cellule, spreadsheets.get renvoie la valeur de la cellule ainsi que des métadonnées (telles que le nom et la taille de la police, etc.). Cela génère des charges utiles JSON volumineuses qui sont lentes à analyser. En comparaison, un appel similaire à values.get ne renvoie que la valeur de la cellule spécifique, ce qui donne une réponse beaucoup plus légère et rapide.

Pour en savoir plus sur la ressource spreadsheets.values, y compris spreadsheets.values.get et spreadsheets.values.batchGet, consultez les documents suivants :

Lister les feuilles de calcul

L'API Sheets ne propose pas de méthode permettant de lister les feuilles de calcul pour les utilisateurs authentifiés.

Pour récupérer la liste des feuilles de calcul, vous pouvez utiliser la méthode list de l'API Drive sur la ressource files, en spécifiant application/vnd.google-apps.spreadsheet comme 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"

Remplacez ACCESS_TOKEN par le jeton d'accès qui autorise l'accès à l'API.

L'utilisation de la méthode files.list pour lister les feuilles de calcul d'un utilisateur nécessite un champ d'application restreint de l'API Drive.

Voici quelques étapes que vous pouvez suivre :