קריאה בסיסית

Google Sheets API מאפשר לקרוא ערכים מתאים, טווחים, קבוצות של טווחים ושל גיליונות שלמים. הדוגמאות בדף הזה ממחישות כמה דוגמאות פעילות עם spreadsheets.values משאב. אפשר גם לקרוא את ערכי התאים באמצעות spreadsheets.get, אבל בדרך כלל spreadsheets.values.get או spreadsheets.values.batchGet הוא קל יותר.

הדוגמאות האלה מוצגות בצורה של בקשות HTTP ניטרלי. כדי ללמוד איך להטמיע קריאות בשפות שונות באמצעות ספריות הלקוח של ה-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	מנוע	400 ש"ח	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 Sheet1!A1:D5, מוצרים!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": [
        [...],
        [...]
      ]
    }
  ]
}