מעבר מ-Sheets API v3

אם יש לכם אפליקציות שמבוססות על Google Sheets API v3, תוכלו לעבור ל-Google Sheets API v4. גרסת ה-V4 מבוססת על JSON, יש לה ממשק קל יותר לשימוש והיא מוסיפה כמות משמעותית של פונקציונליות שלא אפשרית בגרסת ה-V3.

בדף הזה מוצג מיפוי בין הפקודות הישנות יותר של Sheets API v3 לבין הפעולות המקבילות להן ב-Sheets API v4. המיפוי מתמקד בעיקר באוסף spreadsheets.values, שמספק פונקציונליות של קריאה וכתיבה בתאים ישירים. האוסף גיליונות אלקטרוניים מטפל בהיבטים אחרים, כמו הוספת גיליונות או עדכון מאפיינים של גיליונות. שימו לב שמבני ה-JSON של API ב-v4 לא תואמים לאחור למבני ה-XML שבהם נעשה שימוש בגרסה 3.

מידע נוסף על המשאבים הזמינים ב-Sheets v4 API זמין בחומר העזר בנושא API.

סימון ותנאים

הממשק v3 API מתייחס לגיליונות בתוך גיליון אלקטרוני מסוים בתור "גיליונות עבודה". המונח הזה זהה למונח 'גיליונות' שבו משתמש v4 API.

לעיתים קרובות, ממשקי ה-API מחייבים לציין מזהה גיליון אלקטרוני של הגיליון האלקטרוני שאיתו עובדים. לעיתים קרובות נדרש גם המזהה של הגיליון שעבר מניפולציה. הערכים האלה מופיעים כחלק מכתובת ה-URL של נקודת הקצה ב-API, כפרמטרים של שאילתה או כחלק מגוף הבקשה. בדף הזה, ה-placeholders spreadsheetId ו-sheetId מתייחסים למזהי הגיליון האלקטרוני והגיליון, בהתאמה. כשמשתמשים בשיטות שמתוארות בדף הזה, מחליפים את המזהים בפועל במיקומים האלה.

v3 API גם מקצה מזהה לשורות שאוחזרו באמצעות פיד הרשימה שלו. המזהה הזה מיוצג בדף הזה על ידי ה-placeholder rowId.

אישור בקשות

כשהאפליקציה שלכם פועלת, היא מבקשת מהמשתמשים להעניק הרשאות מסוימות. היקפי ההרשאות שציינתם באפליקציה קובעים אילו הרשאות היא מבקשת.

v3 API

גרסה 3 של Sheets API פועלת עם היקף הרשאות אחד:

https://spreadsheets.google.com/feeds

שהוא כינוי

https://www.googleapis.com/auth/spreadsheets

אפשר להשתמש בכל אחד מהפורמטים של היקפי ההרשאות.

ממשק API של גרסה 4

ב-Sheets API v4 נעשה שימוש באחת או יותר מקבוצות ההיקף הבאות:

https://www.googleapis.com/auth/spreadsheets.readonly
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive

כדאי להשתמש בהיקפים לקריאה בלבד אם האפליקציה לא צריכה לערוך מאפייני גיליונות או מאפייני גיליון של המשתמש. אם לאפליקציה לא נדרשת גישה כללית ל-Drive, כדאי להשתמש בהיקפים של גיליונות אלקטרוניים במקום בהיקפים של Drive.

חשיפה

בגרסאות ישנות יותר של ה-API, המונח visibility מציין את הזמינות של גיליון אלקטרוני נתון.

v3 API

Sheets API v3 מבטא את החשיפה ישירות בנקודות הקצה שלו. הגיליון האלקטרוני public 'פורסם באינטרנט' ולכן ה-API יכול לגשת אליו ללא הרשאה, אבל בגיליון האלקטרוני private נדרש אימות. הנראות מצוינת בנקודת הקצה, אחרי המזהה של הגיליון האלקטרוני:

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

ממשק API של גרסה 4

בגרסה החדשה של Sheets API v4 אין הצהרת חשיפה מפורשת. קריאות ל-API מתבצעות באמצעות מזהים של גיליונות אלקטרוניים. אם לאפליקציה אין הרשאת גישה לגיליון האלקטרוני שצוין, תתקבל שגיאה. אחרת השיחה תמשיך.

היטל

ב-Sheets API v3 משתמשים במונח Projection כדי להתייחס לקבוצת הנתונים שמוחזרת בעקבות קריאה מסוימת ל-API – כולם או קבוצת משנה קבועה שמוגדרת ב-API. ב-Sheets API v4 אין היטל, אלא מאפשר יותר שליטה בנתונים שמוחזרים.

v3 API

ב-Sheets API v3 יש רק שתי הגדרות הקרנה אפשריות. ההיטל full יחזיר את כל המידע הזמין, ואילו basic יחזיר קבוצת משנה קטנה יותר וקבועה של הנתונים (בפידים של גיליונות עבודה, רשימות ותאים). בדומה להרשאות, צריך לציין את ההיטל בנקודת הקצה של ה-API (לאחר הגדרת החשיפה):

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

קבוצת המשנה הקטנה יותר של הנתונים בתחזית basic חשובה לייעול הקוד, אבל אי אפשר להתאים אותה אישית.

ממשק API של גרסה 4

Sheets API v4 יכול להחזיר קבוצת נתונים מלאה, אבל לא מגדיר קבוצות משנה קבועות שמקבילות להגדרת החשיפה של basic, Sheets API v3. השיטות באוסף הגיליון האלקטרוני מגבילות את כמות הנתונים שהן מחזירות באמצעות פרמטר של שאילתה שדות.

לדוגמה, השאילתה הבאה מחזירה רק את הכותרות של כל הגיליונות בגיליון אלקטרוני מסוים:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

יצירת גיליון אלקטרוני

v3 API

גרסה 3 של Sheets API לא מספקת אמצעי ליצירת גיליונות אלקטרוניים חדשים. במקום זאת, אפשר להשתמש ב-method Files.create של Drive API כדי ליצור קבצים חדשים של גיליונות אלקטרוניים. לשם כך, האפליקציה צריכה להצהיר על ההיקף https://www.googleapis.com/auth/drive.

ממשק API של גרסה 4

אפשר להשתמש ב-method Drive API Files.create גם עם Sheets API v4, אבל האפליקציה צריכה לספק את ההיקף https://www.googleapis.com/auth/drive.

במקום זאת, גרסת Sheets API v4 מספקת את ה-method spreadsheets.create, שיכולה גם להוסיף גיליונות, להגדיר את מאפייני הגיליון האלקטרוני והגיליון ולהוסיף טווחי תאים בעלי שם. לדוגמה, הקוד הבא יוצר גיליון אלקטרוני חדש ונותן לו את השם 'NewTitle':

POST https://sheets.googleapis.com/v4/spreadsheets
{
 "properties": {"title": "NewTitle"}
}

הצגת רשימה של גיליונות אלקטרוניים עבור המשתמש המאומת

v3 API

הפיד של Sheets API v3 מאפשר לאפליקציה לאחזר רשימה של כל הגיליונות האלקטרוניים שאפשר לגשת אליהם על ידי המשתמש המאומת. נקודת הקצה של הפיד בגיליון האלקטרוני היא:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

ממשק API של גרסה 4

Sheets API v4 לא מאפשר את הפעולה הספציפית הזו. מומלץ להעביר את האפליקציה כך שתשתמש בהיקף של drive.file בשילוב עם Google Picker לבחירת גיליון אלקטרוני.

במקרים שבהם יש צורך בהצגת גיליונות אלקטרוניים, אפשר לשכפל אותם באמצעות ה-method Files.list של Drive API באמצעות השאילתה mimeType:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

כדי להציג רשימה של כל הגיליונות האלקטרוניים של המשתמשים באמצעות השיטה files.list של Drive API, נדרש היקף מוגבל.

אחזור מטא-נתונים של גיליון

Sheets API v3 מספק פיד לגשת למטא-נתונים של הגיליון שכלולים בגיליון אלקטרוני נתון (הגישה לנתוני שורות ותאים מתבצעת דרך פיד נפרד). המטא-נתונים כוללים מידע כמו כותרות גיליונות ופרטי גדלים.

שיטת Sheets API v4 spreadsheets.get מספקת גישה למידע הזה ועוד הרבה יותר.

v3 API

אפשר לגשת אל הפיד של גיליון העבודה מנקודת הקצה הזו ב-API (באמצעות כותרת הרשאה מתאימה):

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

לתשובה לבקשה הזו יש מבנה דומה לזה, כאשר הנתונים של כל גיליון מכילים ב-<entry> נפרד:

<feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006"
    xmlns:gd="http://schemas.google.com/g/2005"
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <title type="text">Groceries R Us</title>
  <link rel="alternate" type="text/html"
      href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
  <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>fitz@example.com</email>
  </author>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
  <entry gd:etag='"YDwqeyI."'>
    <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
    <updated>2006-11-17T18:23:45.173Z</updated>
    <title type="text">Sheet1</title>
    <content type="text">Sheet1</content>
    <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
    <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
    <link rel="self" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
    <link rel="edit" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
    <gs:rowCount>100</gs:rowCount>
    <gs:colCount>20</gs:colCount>
  </entry>
</feed>

ממשק API של גרסה 4

אפשר להשתמש ב-method spreadsheets.get כדי להוסיף מאפייני גיליון ומטא-נתונים אחרים, הרבה יותר ממה שזמין ב-Sheets API v3. אם רוצים רק לקרוא את מאפייני הגיליון, צריך להגדיר את פרמטר השאילתה includeGridData לערך false כדי למנוע הכללה של נתוני התא בגיליון האלקטרוני:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

התשובה Spreadsheet מכילה מערך של Sheet אובייקטים. אפשר למצוא את כותרות הגיליונות ופרטי הגודל הספציפיים מתחת לרכיב SheetProperties של האובייקטים האלה. למשל:

{
  "spreadsheetId": spreadsheetId,
  "sheets": [
      {"properties": {
          "sheetId": sheetId,
          "title": "Sheet1",
          "index": 0,
          "gridProperties": {
              "rowCount": 100,
              "columnCount": 20,
              "frozenRowCount": 1,
              "frozenColumnCount": 0,
              "hideGridlines": false
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

הוספת גיליון לגיליון אלקטרוני

שני ממשקי ה-API מאפשרים להוסיף גיליונות חדשים לגיליון אלקטרוני קיים.

v3 API

באמצעות Sheets API v3, אפשר להוסיף גיליונות עבודה חדשים לגיליון אלקטרוני באמצעות בקשת ה-POST (המאומתת) הבאה. אפשר לציין את הגודל של הגיליון החדש:

POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <title>Expenses</title>
  <gs:rowCount>50</gs:rowCount>
  <gs:colCount>10</gs:colCount>
</entry>

ממשק API של גרסה 4

אפשר להוסיף גיליונות חדשים על ידי שליחת בקשת AddSheet ב-method spreadsheets.batchUpdate. כחלק מגוף הבקשה, אפשר לציין את מאפייני הגיליון לגיליון החדש. כל המאפיינים הם אופציונליים. כאן זו שגיאה בציון שם של גיליון קיים.

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

שינוי הכותרת והגודל של גיליון

Sheets API v3 מאפשר לעדכן את הכותרות והגודל של גיליונות. גם Sheets API v4 מאפשר זאת, אבל אפשר להשתמש בו גם כדי לעדכן מאפיינים אחרים של גיליון. שימו לב שהקטנת הגיליון עלולה לגרום למחיקת נתונים בתאים החתוכים ללא אזהרה.

v3 API

כדי לשנות את השם או הגודל של גיליון העבודה, קודם מאחזרים את הפיד של גיליון העבודה ומחפשים את הרשומה הרצויה של גיליון העבודה, שמכילה כתובת URL מסוג edit. מעדכנים את המטא-נתונים של גיליון העבודה ושולחים אותם בתור הגוף של בקשת PUT לכתובת ה-URL לעריכה. למשל:

PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
  <id>
    https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
  </id>
  <updated>2007-07-30T18:51:30.666Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
  <title type="text">Expenses</title>
  <content type="text">Expenses</content>
  <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
  <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
  <gs:rowCount>45</gs:rowCount>
  <gs:colCount>15</gs:colCount>
</entry>

ממשק API של גרסה 4

כדי לעדכן את הגודל, הכותרת ומאפייני הגיליון האחרים, שולחים בקשת updateSheetProperties ב-method spreadsheets.batchUpdate. גוף הבקשה של POST צריך לכלול את המאפיינים שרוצים לשנות, והפרמטר fields צריך לכלול את המאפיינים האלה באופן מפורש (אם רוצים לעדכן את כל המאפיינים, אפשר להשתמש ב-fields:"*" כקיצור של רשימת המאפיינים). לדוגמה, הקוד הבא מציין שהמאפיינים של כותרת הגיליון והגודל של הגיליון צריכים להתעדכן עם המזהה הנתון:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "updateSheetProperties": {
          "properties": {
            "sheetId": sheetId,
            "title": "Expenses",
            "gridProperties": {
              "rowCount": 45,
              "columnCount": 15,
            }
          },
          "fields": "title,gridProperties(rowCount,columnCount)"
     }
   }
  ],
}

כדי לאחזר את sheetId של גיליון, משתמשים בשיטה spreadsheets.get בגיליון האלקטרוני.

מחיקת גיליון

כל אחד מממשקי ה-API יכולים להסיר גיליונות מגיליון אלקטרוני נתון.

v3 API

כדי למחוק גיליון עבודה, מתחילים באחזור הפיד של גיליון העבודה, ואז שולחים בקשת DELETE בכתובת ה-URL של edit של רשומת היעד בגיליון העבודה.

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

ממשק API של גרסה 4

כדי למחוק גיליון, שולחים בקשת DeleteSheet במתודה spreadsheets.batchUpdate. גוף הבקשה POST צריך להכיל רק את הערך sheetId כדי שהגיליון יימחק. למשל:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

כדי לאחזר את sheetId של גיליון מסוים, משתמשים ב-method spreadsheets.get בגיליון האלקטרוני.

אחזור נתוני שורות

פיד השורות ברשימה הוא אחת משתי השיטות ב-Sheets API v3 כדי לגשת לנתונים בתוך תאים של גיליון אלקטרוני (השיטה השנייה היא פיד התאים). פיד השורות נועד לתמוך בפעולות נפוצות בגיליון אלקטרוני (קריאת שורה אחרי שורה, צירוף שורות ומיון), אבל הוא מניח הנחות מסוימות שלא מתאימות לביצוע משימות מסוימות. באופן ספציפי, פיד הרשימה מניח ששורות ריקות הן סגירת פיד, ושכותרות חובה מופיעות בשורה הראשונה של הגיליון.

לעומת זאת, ב-Sheets API v4 אין שימוש בשיטות גישה שהן ספציפיות לשורה. במקום זאת, מתבצעת גישה לנתונים של תאי גיליון על ידי התייחסות לטווחים הספציפיים הנדרשים באמצעות סימון A1. הטווחים יכולים להיות בלוקים של תאים, שורות שלמות, עמודות שלמות או גיליונות שלמים. ה-API יכול גם לגשת לקבוצות נפרדות של תאים.

v3 API

כדי לקבוע את כתובת ה-URL של פיד מבוסס-רשימה בגיליון עבודה נתון, מאחזרים את הפיד של גיליון העבודה ומחפשים את כתובת ה-URL של פיד הרשימה ברשומה הרלוונטית בגיליון העבודה.

כדי לאחזר פיד שמבוסס על רשימות, צריך לשלוח בקשת GET לכתובת ה-URL של פיד הרשימה, באמצעות כותרת ההרשאה המתאימה. למשל:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

התגובה לבקשה הזו מכילה, בין היתר, רשומות שתואמות לשורות ספציפיות. השמות שמופיעים בשורת הכותרת של הגיליון (החובה) מפנים לתאים ספציפיים. לדוגמה, כך מופיעה רשומה של שורה אחת:

<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
      term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>10</gsx:hours>
  <gsx:items>2</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

כברירת מחדל, השורות שמוחזרות בפיד הרשימה מוחזרות לפי סדר השורות. Sheets API v3 מספק פרמטרים של שאילתה כדי לשנות את הסדר הזה.

סדר הפוך:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

סידור לפי עמודה ספציפית:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

Sheets API v3 מאפשר גם לסנן שורות ספציפיות באמצעות שאילתה מובנית (הפניה באמצעות כותרות העמודות):

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

ממשק API של גרסה 4

ב-API של Sheets v4, אפשר לאחזר את השורות לפי טווח באמצעות ה-methods spreadsheets.values.get או spreadsheets.values.batchGet. לדוגמה, הדוגמה הבאה מחזירה את כל השורות ב-'Sheet1':

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

התגובה לבקשה הזו בנויה כך:

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

תאים ריקים בסוף לא נכללים בתשובה באחזור שורות, עמודות או גיליונות שלמים.

ל-Sheets API v4 אין ערכים מקבילים לפרמטרים של השאילתה בסדר השורה שסופקו על ידי Sheets API v3. הסדר ההפוך הוא טריוויאלי. פשוט מעבדים את מערך values שהוחזר בסדר הפוך. אין תמיכה בסידור לפי עמודות בקריאות, אבל אפשר למיין את הנתונים בגיליון (באמצעות בקשת SortRange) ואז לקרוא אותם.

בשלב הזה, ל-Sheets API v4 אין מקבילה ישירה לשאילתות המובנה של Sheets API v3. עם זאת, תוכלו לאחזר את הנתונים הרלוונטיים ולמיין אותם לפי הצורך באפליקציה.

הוספה של שורת נתונים חדשה

אפשר להוסיף שורה חדשה של נתונים לגיליון באמצעות כל אחד מממשקי ה-API האלה.

v3 API

כדי לקבוע את כתובת ה-URL של פיד מבוסס רשימה בגיליון עבודה נתון, מאחזרים את הפיד של גיליון העבודה ומחפשים את כתובת ה-URL של הפוסט ברשומה הרלוונטית בגיליון העבודה.

כדי להוסיף שורת נתונים, צריך לשלוח בקשת POST לכתובת ה-URL של הפוסט, באמצעות כותרת ההרשאה המתאימה. למשל:

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

גוף הבקשה של POST צריך להכיל רשומה של נתוני השורה שצריך להוסיף, עם תאים ספציפיים שכותרות העמודות שלהם מפנים אליהם:

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
  <gsx:hours>2</gsx:hours>
  <gsx:ipm>0.5</gsx:ipm>
  <gsx:items>60</gsx:items>
  <gsx:name>Elizabeth</gsx:name>
</entry>

שורות חדשות יתווספו לסוף הגיליון שצוין.

ממשק API של גרסה 4

ב-API של Sheets v4 אפשר לצרף שורות באמצעות ה-method spreadsheets.values.append. בדוגמה הבאה מופיעה שורה חדשה של נתונים מתחת לטבלה האחרונה ב-Sheet1 של גיליון אלקטרוני.

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

בנוסף, ב-Sheets API v4 אפשר גם לצרף תאים עם מאפיינים ועיצוב ספציפיים באמצעות בקשות AppendCells ב-spreadsheets.batchUpdate.

עריכת שורה עם נתונים חדשים

שני ממשקי ה-API מאפשרים לעדכן את נתוני השורות בערכים חדשים.

v3 API

כדי לערוך שורת נתונים, מאתרים את הרשומה של השורה שרוצים לעדכן בפיד הרשימה. מעדכנים את התוכן של הרשומה הזו לפי הצורך. חשוב לוודא שערך המזהה ברשומה שבה משתמשים זהה בדיוק למזהה של הרשומה הקיימת.

לאחר עדכון הרשומה, שולחים בקשת PUT עם הערך בגוף הבקשה לכתובת ה-URL edit שצוינה ברשומת השורה הזו, באמצעות כותרת ההרשאה המתאימה. למשל:

PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>20</gsx:hours>
  <gsx:items>4</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

ממשק API של גרסה 4

ב-Sheets API v4 אפשר לערוך שורה באמצעות סימון A1 של השורה שרוצים לערוך, ולשלוח בקשת spreadsheets.values.update כדי להחליף את השורה הזו. הטווח שצוין צריך להתייחס רק לתא הראשון בשורה. ה-API מסיק את התאים כך שצריך לעדכן על סמך הערכים שצוינו בבקשה. אם במקום זאת מציינים טווח של תאים מרובים, הערכים שאתם מציינים חייבים להתאים לטווח הזה. אם לא, ה-API יחזיר שגיאה.

גוף הבקשה והדוגמה הבאים מוסיף נתונים לשורה הרביעית של "Sheet1":

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

אפשר גם לעדכן נתוני שורות מה-method spreadsheet.values.batchUpdate. עדיף להשתמש בשיטה הזו אם מבצעים כמה עדכונים של שורות או תאים.

בנוסף, ב-Sheets API v4 אפשר גם לערוך את מאפייני התא ואת עיצוב התאים באמצעות בקשות UpdateCells או RepeatCell ב-spreadsheets.batchUpdate.

מחיקת שורה

שני ממשקי ה-API תומכים במחיקת שורות. שורה שנמחקה מוסרת מהגיליון האלקטרוני והשורות שמתחתיה מועברות למעלה.

v3 API

כדי למחוק שורה, קודם מאחזרים את השורה שרוצים למחוק מפיד הרשימה, ואז שולחים בקשת DELETE לכתובת ה-URL edit שצוינה ברשומה של השורה. זו אותה כתובת URL שמשמשת לעדכון השורה.

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

אם רוצים לוודא שלא מוחקים שורה ששונתה על ידי לקוח אחר מאז האחזור שלה, צריך לכלול כותרת HTTP if-Match שמכילה את ערך ה-ETag של השורה המקורית. אפשר לקבוע את ערך ה-ETag של השורה המקורית על ידי בחינת המאפיין gd:etag של הרכיב הרשומה.

כדי למחוק את השורה גם אם מישהו אחר עדכן אותה מאז שאחזרתם אותה, אתם צריכים להשתמש ב-If-Match: * ולא לכלול את ה-ETag. (במקרה זה, לא צריך לאחזר את השורה לפני המחיקה).

ממשק API של גרסה 4

מחיקת שורות ב-API v4 של Sheets מטופלת בקריאה ל-method spreadsheet.batchUpdate, באמצעות בקשת DeleteDimension. אפשר להשתמש בבקשה הזו גם להסרת עמודות, והמפתחים יכולים לבחור להסיר רק חלק משורה או עמודה. לדוגמה, בדוגמה הבאה מסירים את השורה השישית בגיליון עם המזהה הנתון (מדדי השורות מבוססים על אפס, כשאינדקס ההתחלה כולל את אינדקס ההתחלה ולא כולל אינדקס הסיום):

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

אפשר לאחזר את sheetId של גיליון באמצעות השיטה spreadsheet.get.

אחזור של נתוני תא

Sheets API v3 מספק פיד תאים לגישה בסיסית לכל הנתונים שמאוחסנים בגיליון אלקטרוני. לגישת קריאה, פיד התא יכול לספק את כל תוכן הגיליון או טווח של תאים בגיליון שמוגדר על ידי קבוצת פרמטרים של שאילתה, אבל רק כבלוק אחד – צריך לאחזר טווחים נפרדים בנפרד באמצעות בקשות GET נוספות.

Sheets API v4 יכול לאחזר כל קבוצה של נתוני תאים מגיליון (כולל מספר טווחים לא רציפים). Sheets API v3 יכול להחזיר רק תוכן של תאים כערכי קלט (כפי שהמשתמש היה מזין במקלדת) ו/או את הפלט של הנוסחה (אם הוא מספרי). ב-Sheets API v4 יש גישה מלאה לערכים, לנוסחאות, לעיצוב, להיפר-קישורים, לאימות נתונים ולמאפיינים אחרים.

v3 API

כדי לקבוע את כתובת ה-URL של פיד מבוסס-תא בגיליון עבודה נתון, בודקים את הפיד של גיליון העבודה ומחפשים את כתובת ה-URL של פיד התא ברשומה הרלוונטית בגיליון העבודה.

כדי לאחזר פיד מבוסס-תא, צריך לשלוח בקשת GET לכתובת ה-URL של פיד התא, באמצעות כותרת ההרשאה המתאימה. למשל:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

מתבצעת הפניה לתאים לפי מספר שורה ועמודה. אפשר לאחזר טווח ספציפי אחד באמצעות הפרמטרים של השאילתה max-row, min-row, max-col ו-min-col. לדוגמה, הדוגמה הבאה מאחזרת את כל התאים בעמודה 4 (D), החל משורה 2:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

ה-API של Sheets v3 מחזיר את הערך inputValue של התאים שאוחזרו – הערך שהמשתמש היה מקליד בממשק המשתמש של Google Sheets כדי לבצע שינויים בתא. inputValue יכול להיות ערך מילולי או נוסחה. לפעמים ה-API מחזיר גם numericValue. לדוגמה, כשנוסחה מובילה למספר. לדוגמה, תגובה עשויה לכלול רשומות תאים שדומות במבנה הבא:

<entry gd:etag='"ImB5CBYSRCp7"'>
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
  <updated>2006-11-17T18:27:32.543Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#cell"/>
  <title type="text">D4</title>
  <content type="text">5</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
  <gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
    numericValue="5.0">5</gs:cell>
</entry>

ממשק API של גרסה 4

מאחזרים נתוני תאים על ידי קריאה ל-method spreadsheets.values.get או spreadsheets.values.batchGet שמייצגים את הטווח או הטווחים הרצויים, בהתאמה. לדוגמה, הדוגמה הבאה מחזירה את התאים בעמודה D של "Sheet2", החל משורה 2, בסדר גודל העמודות הראשי, ומחזירה את הנוסחאות כפי שהוזנו (התאים הריקים חסרים):

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

המבנה של התגובה לבקשה הזו דומה ל:

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

עדיף להשתמש ב-spreadsheet.values.batchGet אם מתכוונים לאחזר טווחים מרובים של נתוני תאים. אם רוצים לגשת למאפייני תאים כמו עיצוב, צריך להשתמש ב-method spreadsheet.get.

עריכת תא

ב-Sheets API v3 אפשר לערוך את התוכן של התא, על ידי הנפקת פקודת PUT אל פיד התא, עם רשומת התא שהשתנתה כגוף הבקשה.

לעומת זאת, ב-Sheets API v4 יש שיטות לשינוי תוכן של תאים ב-spreadsheets.values.update וב-spreadsheets.values.batchUpdate.

v3 API

כדי לערוך את התוכן של תא אחד, קודם כל צריך למצוא את הערך של התא בפיד של התא. הרשומה מכילה כתובת URL לעריכה. מעדכנים את הרשומה כך שתשקף את התוכן שרוצים לכלול בתא, ואז שולחים בקשת PUT לכתובת ה-URL לעריכה, עם רשומת התא המעודכנת בתור גוף הבקשה. לדוגמה, העדכון הבא של תא D2 (R2C4) מכיל את הנוסחה SUM:

PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc


<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/>
  <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/>
</entry>

ממשק API של גרסה 4

אפשר לערוך תא יחיד ב-Sheets API v4 באמצעות ה-method spreadsheets.values.update. לשיטה הזו נדרש פרמטר שאילתה ValueInputOption, שמציין אם יש להתייחס לנתוני הקלט כאילו הם הוזנו בממשק המשתמש של Sheets (USER_ENTERED), או להשאיר את הנתונים ללא ניתוח ונלקחים כפי שהם (RAW). לדוגמה, התא D2 הבא מעדכן עם נוסחה:

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}

אם מבצעים עריכות של מספר תאים, צריך להשתמש ב-method spreadsheets.values.batchUpdate כדי לשלוח את הקבצים בבקשה אחת.

עריכה של מספר תאים באמצעות בקשה באצווה

שני ממשקי ה-API מאפשרים לבצע שינויים בתוכן של מספר תאים באמצעות בקשת אחת (באצווה). התאים שמפנים אליהם באמצעות בקשה באצווה לא חייבים להיות בטווח זהה.

במקרה שבו אחת או יותר מפעולות העריכה בתאים בקבוצה נכשלת, Sheets API v3 יאפשר לאחרים להצליח. עם זאת, Sheets API v4 יחזיר שגיאה אם אחד מהעדכונים באצווה נכשל, ולא תחיל אותם במקרה הזה.

v3 API

כדי לערוך כמה תאים, קודם מאחזרים פיד תאים של גיליון העבודה. הרשומה מכילה כתובת URL באצווה. שולחים בקשת POST לכתובת ה-URL הזו, יחד עם גוף בקשה שמתאר את התאים שרוצים לעדכן ואת התוכן של התא החדש. לגוף הבקשה ולגוף הבקשה POST יש מבנה שדומה לזה:

POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:batch="http://schemas.google.com/gdata/batch"
      xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
  <entry>
    <batch:id>request1</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
    <gs:cell row="2" col="4" inputValue="newData"/>
  </entry>
  ...
  <entry>
    <batch:id>request2</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
    <gs:cell row="5" col="2" inputValue="moreInfo"/>
  </entry>
</feed>

השדה batch:id צריך לזהות באופן ייחודי את הבקשה בתוך הקבוצה. השדה batch:operation צריך להיות update כדי לבצע שינויים בתאים. gs:cell מזהה את התא לפי מספר השורה והעמודה ומספק את הנתונים החדשים שצריך להוסיף אליו. השדה id מכיל את כתובת ה-URL המלאה של התא שצריך לעדכן. link חייב להיות מאפיין href שמכיל את הנתיב המלא למזהה התא. כל השדות האלה הם שדות חובה לכל רשומה.

ממשק API של גרסה 4

Sheets API v4 מאפשר עריכה בכמות גדולה של ערכי תאים באמצעות ה-method spreadsheets.values.batchUpdate.

כדי לערוך מספר תאים, שולחים בקשת POST עם שינויי הנתונים שצוינו בגוף הבקשה. למשל:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED"
  "data": [
       {"range": "D4",
        "majorDimension": "ROWS",
        "values": [["newData"]]
       },
       {"range": "B5",
        "majorDimension": "ROWS",
        "values": [["moreInfo"]]
       }
  ]
}

אם ציינתם תא אחד כטווח, כל הערכים שצוינו נכתבים לגיליון, החל מהתא הזה כקואורדינטה השמאלית העליונה. אם במקום זאת תציינו טווח של כמה תאים, הערכים שאתם צריכים צריכים להתאים לטווח הזה בדיוק. אחרת, ה-API מחזיר שגיאה.