קריאה בסיסית

ב-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": [
        [...],
        [...]
      ]
    }
  ]
}