גיליונות אלקטרוניים יכולים לכלול כמה גיליונות, וכל גיליון יכול להכיל מספר שורות או עמודות. תא הוא מיקום בצומת של שורה ועמודה מסוימות, והוא עשוי להכיל ערך של נתונים. Google Sheets API מספק את המשאב spreadsheets.values
כדי לאפשר קריאה וכתיבה של ערכים.
בדף הזה מתוארים יסודות השימוש במשאב spreadsheets.values
. אם צריך להוסיף שורות או לעדכן את העיצוב ומאפיינים אחרים בגיליון, יש להשתמש ב-method spreadsheets.batchUpdate
שמתוארת במאמר עדכון גיליונות אלקטרוניים.
שיטות
המשאב spreadsheets.values
מספק את השיטות הבאות לקריאה ולכתיבה של ערכים, כל אחת למשימה מסוימת:
גישה לטווחים | קריאה | כתיבה |
---|---|---|
טווח יחיד | spreadsheets.values.get |
spreadsheets.values.update |
טווחים מרובים | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
הוספה | spreadsheets.values.append |
באופן כללי, מומלץ לשלב מספר קריאות או עדכונים עם השיטות 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. לדוגמה, '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 | ה. | |
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.