קריאה בסיסית

‫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

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