ב-Google Sheets API אפשר לקרוא ערכים מתאים, מטווחים, מקבוצות של טווחים ומגיליונות שלמים. בדוגמאות שבדף הזה אפשר לראות כמה פעולות קריאה נפוצות באמצעות המשאב spreadsheets.values
. אפשר גם לקרוא את ערכי התאים באמצעות השיטה spreadsheets.get
, אבל בדרך כלל קל יותר לקרוא את spreadsheets.values.get
או spreadsheets.values.batchGet
.
הדוגמאות האלה מוצגות בצורת בקשות HTTP כשהשפה היא ניטרלית. במאמר קריאה וכתיבה של ערכי תאים מוסבר איך להטמיע קריאות בשפות שונות באמצעות ספריות הלקוח של Google API.
בדוגמאות האלה, ה-placeholder SPREADSHEET_ID מציין איפה צריך לספק את המזהה של הגיליון האלקטרוני, שאותו אפשר למצוא בכתובת ה-URL של הגיליון האלקטרוני. הטווחים שמהם צריך לקרוא מצוינים באמצעות סימון A1 בכתובת ה-URL של הבקשה. טווח לדוגמה הוא Sheet1!A1:D5.
נתוני מקור
בדוגמאות האלה, נניח שהגיליון האלקטרוני שאתם קוראים כולל את נתוני המקור הבאים בגיליון הראשון ("גיליון1"). המחרוזות בשורה הראשונה הן תוויות של העמודות הנפרדות. כדי לראות דוגמאות לקריאה מגיליונות אחרים בגיליון האלקטרוני, ראו סימון A1.
A | B | C | D | |
1 | פריט | עלות | מלאי | תאריך משלוח |
2 | גלגל ענק | 82.00 ש"ח | 4 | 01.03.2016 |
3 | דלת | 60 ש"ח | 2 | 15.03.2016 |
4 | מנוע | 100$ | 1 | 20.03.2016 |
5 | סה"כ | 543.0 ש"ח | 7 | 20.03.2016 |
קריאה של טווח יחיד
דוגמת הקוד הבאה של spreadsheets.values.get
מראה איך לקרוא את הערכים מהטווח Sheet1!A1:D5 ומחזירה אותם בתשובה. אין שורות ועמודות ריקות.
פרוטוקול הבקשה מוצג כאן.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
התגובה מורכבת מאובייקט ValueRange
שמתאר את ערכי הטווח. השדה majorDimension
מציין שהמערכים הם רשימות של ערכים שמסודרים לפי שורות.
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "3/1/2016"], ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "30/20/2016"], ["Totals", "$135.5", "7", "3/20/2016"] ], }
קריאה של טווח יחיד המקובץ לפי עמודה
דוגמת הקוד הבאה של spreadsheets.values.get
מראה איך לקרוא את הערכים מהטווח Sheet1!A1:D3 ומחזירה אותם בתשובה, אבל בקיבוץ לפי עמודה. אין שורות ועמודות ריקות.
פרוטוקול הבקשה מוצג כאן.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
התגובה מורכבת מאובייקט ValueRange
שמתאר את ערכי הטווח. השדה majorDimension
מציין שהמערכים הם רשימות של ערכים שמסודרים לפי עמודות.
{ "range": "Sheet1!A1:D3", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door"], ["Cost", "$20.50", "$15"], ["Stocked", "4", "2"], ["Ship Date", "3/1/2016", "3/15/2016"] ], }
קריאה של טווח יחיד עם אפשרויות עיבוד
דוגמת הקוד הבאה של spreadsheets.values.get
מראה איך לקרוא את הערכים מהטווח Sheet1!A1:D5 ומחזירה אותם בתשובה, אבל משתמשת באפשרויות רינדור כדי לנהל את האופן שבו המידע מוחזר. ההגדרה ValueRenderOption
של FORMULA
מציינת שצריך להחזיר נוסחאות במקום הערך שחושב, וההגדרה DateTimeRenderOption
של SERIAL_NUMBER
מציינת שהתאריכים מוחזרים בתור מספרים.
אפשר גם להגדיר הגדרות אחרות. אין שורות ועמודות ריקות.
פרוטוקול הבקשה מוצג כאן.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5? valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER
התגובה מורכבת מאובייקט ValueRange
שמתאר את ערכי הטווח. השדה majorDimension
מציין שהמערכים הם רשימות של ערכים שמסודרים לפי שורות.
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "42430"], ["Door", "$15", "2", "42444"], ["Engine", "$100", "1", "42449"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
קריאה של טווחים מרובים
דוגמת הקוד הבאה של spreadsheets.values.batchGet
מראה איך לקרוא ערכים מהטווחים Sheet1!B:B ו-Sheet1!D:D ומחזירה אותם בתשובה. ההגדרה ValueRenderOption
של UNFORMATTED_VALUE
מציינת שהערכים מחושבים, אבל לא בפורמט של התשובה. אין שורות ועמודות ריקות.
פרוטוקול הבקשה מוצג כאן.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
התגובה לקריאה ל-method הזו מורכבת מאובייקט עם מזהה הגיליון האלקטרוני וממערך של אובייקטים ValueRange
שתואמים לכל טווח מבוקש, המפורטים לפי הסדר שבו התקבלו הבקשה. השדה majorDimension
מציין שהמערכים הם רשימות של ערכים שמסודרים לפי עמודות. למשל:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!B1:B1000", "majorDimension": "COLUMNS", "values": [ ["Cost",20.5,15,100,135.5] ] }, { "range": "Sheet1!D1:D1000", "majorDimension": "COLUMNS", "values": [ ["Ship Date",42430,42444,42449,42449] ]s } ] }
קריאה של טווחים מרובים בגיליונות מרובים
דוגמת הקוד הבאה של spreadsheets.values.batchGet
מראה איך לקרוא ערכים מטווחים בגיליונות ב-Sheets!A1:D5,
Products!D1:D100 וב-Sales!E4:F6, ומחזירה אותם בתשובה. ההגדרה ValueRenderOption
של UNFORMATTED_VALUE
מציינת שהערכים מחושבים, אבל לא בפורמט של התשובה. אין שורות ועמודות ריקות.
פרוטוקול הבקשה מוצג כאן.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
התגובה לקריאה ל-method הזו מורכבת מאובייקט עם מזהה הגיליון האלקטרוני וממערך של אובייקטים ValueRange
שתואמים לכל טווח מבוקש, המפורטים לפי הסדר שבו התקבלו הבקשה. השדה majorDimension
מציין שהמערכים הם רשימות של ערכים שמסודרים לפי עמודות. למשל:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!A1:D5", "majorDimension": "COLUMNS", "values": [ [...], [...] ] }, { "range": "Products!D1:D100", "majorDimension": "COLUMNS", "values": [ [...] ] }, { "range": "Sales!E4:F6", "majorDimension": "COLUMNS", "values": [ [...], [...] ] } ] }