קריאה בסיסית

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