גיליונות אלקטרוניים יכולים להכיל מספר גיליונות אלקטרוניים, וכל גיליון מכיל מספר בלתי מוגבל של שורות.
או עמודות. תא הוא מיקום
בין שורה מסוימת לעמודה מסוימת, והוא עשוי להכיל ערך נתונים.
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 |
באופן כללי, כדאי לשלב כמה קריאות או עדכונים עם
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
, כל מערך פנימי
שנכתב בעמודה ולא בשורה.
כשמעדכנים נתונים, המערכת תדלג על ערכים שאין בהם נתונים. כדי לנקות נתונים, יש להזין string ("").
כתיבת טווחים מרובים
אם רוצים לכתוב מספר טווחים לא רציפים, אפשר להשתמש
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 | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | 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