קריאה בסיסית

‫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	גלגל ענק	$20.50	4	01/03/2016
3	דלת	60 ש"ח	2	15/03/2016
4	מנוע	400 ש"ח	1	20/03/2016
5	סה"כ	$135.5	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

התשובה לקריאה הזו של השיטה מורכבת מאובייקט עם מזהה הגיליון האלקטרוני וממערך של אובייקטים 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 מוצג אופן הקריאה של ערכים מטווחים בגיליונות 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

התשובה לקריאה הזו של השיטה מורכבת מאובייקט עם מזהה הגיליון האלקטרוני וממערך של אובייקטים 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": [
        [...],
        [...]
      ]
    }
  ]
}