בגיליון אלקטרוני יכולים להיות כמה גיליונות, ובכל גיליון יש מספר שורות או עמודות שרוצים. תא הוא מיקום במקטע של שורה ועמודה מסוימים, והוא עשוי להכיל ערך נתונים. Google Sheets API מספק את המשאב spreadsheets.values
שמאפשר קריאה וכתיבה של ערכים.
בדף הזה מתוארים יסודות השימוש במשאב spreadsheets.values
. כדי להוסיף שורות או לעדכן את העיצוב ומאפיינים אחרים בגיליון, צריך להשתמש בשיטה spreadsheets.batchUpdate
שמתוארת במאמר עדכון גיליונות אלקטרוניים.
שיטות
המשאב spreadsheets.values
מספק את השיטות הבאות לקריאה ולכתיבה של ערכים, כל אחת למשימה ספציפית:
גישה לטווח | קריאה | כתיבה |
---|---|---|
טווח יחיד | spreadsheets.values.get |
spreadsheets.values.update |
טווחים מרובים | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
צירוף | spreadsheets.values.append |
באופן כללי, כדאי לשלב מספר קריאות או עדכונים עם ה-methods batchGet
ו-batchUpdate
(בהתאמה), כדי לשפר את היעילות.
תוכלו למצוא דוגמאות לכל אחת מהשיטות האלה בדפי הדוגמאות קריאה בסיסית וכתיבה בסיסית. כדי לראות את כל הדוגמאות, היכנסו לדף הסקירה הכללית של הדוגמאות.
נקראה
כדי לקרוא ערכי נתונים בגיליון, צריך את מזהה הגיליון האלקטרוני ואת סימון A1 של הטווח. ציון הטווח בלי מזהה הגיליון (A1:B2
) פירושו שהבקשה תתבצע בגיליון הראשון בגיליון האלקטרוני. למידע נוסף על מזהים של גיליונות אלקטרוניים ועל סימון A1, ראו סקירה כללית על Google Sheets API.
יש כמה פרמטרים אופציונליים של שאילתה ששולטים בפורמט הפלט:
פרמטר עיצוב | ערך ברירת מחדל |
---|---|
majorDimension |
שורה |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
הערה: משתמשים ב-dateTimeRenderOption
רק אם valueRenderOption
הוא לא FORMATTED_VALUE
.
אין הגבלה מפורשת על כמות הנתונים שמוחזרים. השגיאות לא מחזירות נתונים. אין שורות ועמודות ריקות.
השיטות של אחזור ביחיד ובאצווה מתוארות בהמשך. במאמר קריאה בסיסית תוכלו לראות דוגמאות של פעולות קריאה בסיסיות.
קריאה של טווח יחיד
כדי לקרוא טווח יחיד של ערכים בגיליון אלקטרוני, צריך להשתמש בבקשת spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
התגובה לבקשה הזו מוחזרת כאובייקט ValueRange
.
קריאה של טווחים מרובים
כדי לקרוא מספר טווחי ערכים לא רציפים מגיליון אלקטרוני, משתמשים בבקשה spreadsheets.values.batchGet
שמאפשרת לציין מספר טווחים לאחזור:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
התגובה לבקשה הזו מוחזרת כאובייקט BatchGetValuesResponse
שמכיל את האובייקט spreadsheetId
ורשימה של ValueRange
האובייקטים.
כתיבה
כדי לכתוב בגיליון צריך את המזהה של הגיליון האלקטרוני, את טווח התאים בסימון A1 ואת הנתונים שרוצים לכתוב בגוף הבקשה המתאים. למידע נוסף על מזהים של גיליונות אלקטרוניים ועל סימון A1, ראו סקירה כללית על Google Sheets API.
העדכונים דורשים פרמטר ValueInputOption
תקין.
בעדכונים בודדים, זהו פרמטר השאילתה הנדרש. בעדכונים בכמות גדולה, הפרמטר הזה נדרש בגוף הבקשה. ValueInputOption
קובע איך לפרש את נתוני הקלט ואם לנתח את מחרוזות הקלט או לא, כפי שמתואר בטבלה הבאה:
ValueInputOption |
תיאור |
---|---|
RAW |
הקלט לא מנותח ומוכנס כמחרוזת. לדוגמה, הקלט '=1+2' ממקם את המחרוזת, ולא את הנוסחה '=1+2' בתא. (ערכים שאינם מחרוזות, כמו ערכים בוליאניים או מספרים, תמיד יטופלו כ-RAW ). |
USER_ENTERED |
המערכת מנתחת את הקלט בדיוק כמו שהוא הוזן בממשק המשתמש של Sheets. לדוגמה, 'Mar 1 2016' הופך לתאריך ו-'=1+2' הופך לנוסחה. ניתן גם להסיק את הפורמטים, כך ש-"$100.15" הופך למספר עם פורמט מטבע. |
בהמשך מתוארות השיטות לעדכון יחיד ואצווה. במאמר כתיבה בסיסית תוכלו לראות דוגמאות של פעולות כתיבה בסיסיות.
כתיבה לטווח יחיד
כדי לכתוב נתונים בטווח אחד, משתמשים בבקשת spreadsheets.values.update
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
הגוף של בקשת העדכון חייב להיות אובייקט ValueRange
, אבל שדה החובה היחיד הוא values
. אם מציינים את range
, הערך שלו חייב להיות זהה לטווח שבכתובת ה-URL. בשדה ValueRange
אפשר לציין את majorDimension
באופן אופציונלי.
כברירת מחדל, נעשה שימוש ב-ROWS
. אם מציינים את COLUMNS
, כל מערך פנימי נכתב לעמודה ולא לשורה.
כשמעדכנים נתונים, המערכת תדלג על ערכים שאין בהם נתונים. כדי לנקות נתונים צריך להשתמש במחרוזת ריקה ("").
כתיבת טווחים מרובים
אם רוצים לכתוב מספר טווחים לא רציפים, אפשר להשתמש בבקשת spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
הגוף של הבקשה לעדכון באצווה צריך להיות אובייקט BatchUpdateValuesRequest
, שמכיל ValueInputOption
ורשימה של ValueRange
אובייקטים (אחד לכל טווח כתוב). כל אובייקט ValueRange
מציין נתוני range
, majorDimension
ונתוני קלט משלו.
צירוף ערכים
כדי לצרף נתונים אחרי טבלת נתונים בגיליון, צריך להשתמש בבקשת spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
הגוף של בקשת העדכון חייב להיות אובייקט ValueRange
, אבל שדה החובה היחיד הוא values
. אם מציינים את range
, הערך שלו חייב להיות זהה לטווח שבכתובת ה-URL. בשדה ValueRange
אפשר לציין את majorDimension
באופן אופציונלי.
כברירת מחדל, נעשה שימוש ב-ROWS
. אם מציינים את COLUMNS
, כל מערך פנימי נכתב לעמודה ולא לשורה.
טווח הקלט משמש לחיפוש נתונים קיימים ולמציאת 'טבלה' בטווח הזה. הערכים מתווספים לשורה הבאה בטבלה, החל מהעמודה הראשונה בטבלה. לדוגמה, נבחן את Sheet1
שנראה כך:
A | B | C | D | E | |
1 | x | שנה | z | ||
2 | x | שנה | z | ||
3 | |||||
4 | x | שנה | |||
5 | שנה | z | |||
6 | x | שנה | z | ||
7 |
בגיליון יש 2 טבלאות: A1:C2
ו-B4:D6
. הערכים שמצורפים יתחילו ב-B7
לכל ערכי הקלט הבאים של range
:
Sheet1
, כי היא תבדוק את כל הנתונים בגיליון ותקבע שהטבלה ב-B4:D6
היא הטבלה האחרונה.B4
אוC5:D5
, כי שניהם מופיעים בטבלהB4:D6
.B2:D4
, כי הטבלה האחרונה בטווח היא הטבלהB4:D6
(למרות שהיא מכילה גם את הטבלהA1:C2
).A3:G10
, כי הטבלה האחרונה בטווח היא הטבלהB4:D6
(למרות שמתחילה לפני ומסתיימת אחריה).
ערכי הקלט הבאים של range
לא יתחילו לכתוב ב-B7
:
A1
יתחיל לכתוב ב-A3
, כי זה בטבלהA1:C2
.E4
מתחיל לכתוב ב-E4
כי הוא לא נמצא באף טבלה. (A4
גם יתחיל לכתוב בכתובתA4
מאותן סיבות).
בנוסף, אפשר לבחור אם רוצים להחליף נתונים קיימים אחרי טבלה או להוסיף שורות חדשות לנתונים החדשים. כברירת מחדל, הקלט מחליף נתונים אחרי הטבלה. כדי לכתוב את הנתונים החדשים בשורות חדשות, משתמשים ב-InsertDataOption
ומציינים insertDataOption=INSERT_ROWS
.
מידע נוסף על מגבלות על תאים ושורות ב-Sheets זמין במאמר קבצים שאפשר לאחסן ב-Google Drive.