קריאה בסיסית

באמצעות 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	1.3.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": [
        [...],
        [...]
      ]
    }
  ]
}