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.
נתוני מקור
לצורך הדוגמאות האלה, נניח שהגיליון האלקטרוני שנקרא כולל את נתוני המקור הבאים בגיליון הראשון שלו (Sheet1). המחרוזות בשורה הראשונה הן תוויות של העמודות הנפרדות. לצפייה בדוגמאות של קריאה מגיליונות אחרים בגיליון האלקטרוני, קראו את הקטע סימון A1.
A | B | C | D | |
1 | פריט | עלות | מלא | תאריך משלוח |
2 | גלגל ענק | 82 ש"ח | 4 | 01.03.2016 |
3 | דלת | 60 ש"ח | 2 | 15.03.2016 |
4 | מנוע | 400 ש"ח | 1 | 20.03.2016 |
5 | סה"כ | 520 ש"ח | 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 Sheet1!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": [ [...], [...] ] } ] }