יצירה וניהול של גיליונות אלקטרוניים

במאמר הזה מוסבר איך ליצור ולנהל גיליונות אלקטרוניים ב-Google Sheets באמצעות Google Sheets API.

יצירת גיליון אלקטרוני

כדי ליצור קובץ ב-Sheets, משתמשים ב-method‏ create במשאב spreadsheets ללא פרמטרים.

כשיוצרים את הקובץ, השיטה מחזירה משאב spreadsheets. המשאב שמוחזר מכיל spreadsheetId, properties, רשימה של sheets ו-spreadsheetUrl.

בדוגמת הקוד הבאה מוצג איך ליצור גיליון אלקטרוני ריק עם שם שצוין.

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-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

הצגת הקוד ב-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

הצגת הקוד ב-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

הצגת הקוד ב-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

הצגת הקוד ב-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

הצגת הקוד ב-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

הצגת הקוד ב-GitHub

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

ארגון גיליונות אלקטרוניים בתיקיות ב-Google Drive

כברירת מחדל, הגיליון האלקטרוני שנוצר נשמר בתיקיית הבסיס של המשתמש ב-Google Drive.

כדי לשמור גיליון אלקטרוני בתיקייה ספציפית ב-Drive, אפשר להשתמש בשיטות הבאות:

• אחרי שיוצרים את קובץ הגיליון האלקטרוני, מעבירים אותו לתיקייה ספציפית באמצעות השיטה update במשאב files של Google Drive API. מידע נוסף זמין במאמר בנושא העברת קבצים בין תיקיות.

• מוסיפים גיליון אלקטרוני ריק לתיקייה באמצעות ה-method‏ create במשאב files של Drive API, ומציינים את application/vnd.google-apps.spreadsheet כ-mimeType. מידע נוסף על יצירת קבצים זמין במאמר יצירת קובץ בתיקייה ספציפית. מידע נוסף על סוגי MIME זמין במאמר סוגי MIME שנתמכים ב-Google Workspace וב-Google Drive.

בכל אחת מהחלופות, תצטרכו להוסיף את היקפי ההרשאות המתאימים של Drive API כדי לאשר את השיחה.

אם האפליקציה משתמשת בחשבון שירות, חשבון השירות הוא הבעלים של הגיליון האלקטרוני שנוצר. הקובץ הזה מאוחסן באחסון הייעודי ב-Drive של חשבון השירות. קבצים לא מופיעים בחשבונות אחסון אחרים ב-Drive, אלא אם הם שותפו באופן מפורש. מידע נוסף זמין במאמר בנושא בעלות על קבצים.

כדי להעביר או ליצור קובץ בתיקייה באחסון השיתופי, אפשר לעיין במאמר הטמעה של תמיכה באחסון שיתופי.

מידע נוסף על מגבלות התאים והשורות ב-Google Sheets זמין במאמר קבצים שאפשר לאחסן ב-Google Drive.

קבלת גיליון אלקטרוני

כדי לקבל גיליון אלקטרוני, משתמשים בשיטה get במשאב spreadsheets עם פרמטר הנתיב spreadsheetId.

השיטה מחזירה את הקובץ כמופע של משאב spreadsheets. כברירת מחדל, הנתונים בגיליון האלקטרוני לא מוחזרים. המשאב שמוחזר מכיל את המבנה והמטא-נתונים של הגיליון האלקטרוני, כולל מאפייני הגיליון האלקטרוני (כמו כותרת, מיקום ואזור זמן) ומידע מפורט על הגיליון (כמו עיצוב וטווחים מוגנים).

כדי לכלול נתונים במשאב spreadsheets, אפשר להשתמש באחת משתי השיטות הבאות:

• מגדירים פרמטר מערכת fields כדי לציין מסכת שדות עם רשימה של השדות שבחרתם.

• מגדירים את הפרמטר הבוליאני includeGridData של השאילתה לערך true. אם מוגדרת מסכת שדות, המערכת מתעלמת מהפרמטר includeGridData.

כשעובדים עם גיליונות אלקטרוניים גדולים, מומלץ לשלוח שאילתה רק לגבי השדות הספציפיים בגיליון האלקטרוני שאתם צריכים. השיטה get מחזירה את כל הנתונים שמשויכים לגיליון האלקטרוני, ולכן שאילתות כלליות לגיליונות אלקטרוניים גדולים יכולות להיות איטיות. לדוגמה, כדי לקרוא את המספר 100 מתא, הפונקציה spreadsheets.get מחזירה את ערך התא בתוספת מטא-נתונים (כמו שם הגופן, הגודל וכו'), וכתוצאה מכך מתקבלים מטען ייעודי (payload) גדול של JSON שפירושו אורך זמן רב יותר של ניתוח. לעומת זאת, קריאה דומה לפונקציה values.get מחזירה רק את הערך הספציפי של התא, ולכן התגובה קלה ומהירה יותר.

מידע נוסף על המשאב spreadsheets.values, כולל spreadsheets.values.get ו-spreadsheets.values.batchGet, זמין במסמכים הבאים:

• קריאה וכתיבה של ערכי תאים
• קריאה בסיסית

הצגת רשימה של גיליונות אלקטרוניים

‫Sheets API לא מציע שיטה ליצירת רשימה של גיליונות אלקטרוניים עבור משתמשים מאומתים.

כדי לאחזר רשימה של גיליונות אלקטרוניים, אפשר להשתמש בשיטה list של Drive API במשאב files, ולציין את application/vnd.google-apps.spreadsheet כ-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"

מחליפים את ACCESS_TOKEN באסימון הגישה שמעניק גישה ל-API.

כדי להשתמש ב-method‏ files.list כדי ליצור רשימה של גיליונות אלקטרוניים של משתמש, צריך להשתמש בהיקף מוגבל של Drive API.

נושאים קשורים

הנה כמה פעולות שאפשר לנסות:

• כדי לעדכן גיליון אלקטרוני, אפשר לעיין במאמר בנושא עדכון גיליונות אלקטרוניים.

• מידע נוסף על צ'יפים חכמים זמין במאמר צ'יפים חכמים.

• מידע נוסף על עבודה עם מטא-נתונים של מפתחים זמין במאמר קריאה, כתיבה וחיפוש של מטא-נתונים.