מעבר מ-Sheets API v3

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

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

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

הערות ומונחים

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

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

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

אישור בקשות

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

‫v3 API

‫Sheets API v3 פועל עם היקף הרשאות יחיד:

https://spreadsheets.google.com/feeds

שהוא כינוי ל-

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

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

‫v4 API

‫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

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

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

‫v4 API

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

היטל

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

‫v3 API

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

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

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

‫v4 API

‫Sheets API גרסה 4 יכול להחזיר מערך נתונים מלא, אבל הוא לא מגדיר קבוצות משנה קבועות שדומות להגדרת הנראות basic ב-Sheets API גרסה 3. השיטות באוסף spreadsheet מגבילות את כמות הנתונים שהן מחזירות באמצעות פרמטר השאילתה fields.

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

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

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

‫v3 API

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

‫v4 API

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

כחלופה שוות ערך, Sheets API v4 מספק שיטה 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

v4 API

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

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

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

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

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

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

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

‫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>

v4 API

אפשר להשתמש במתודה 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>

‫v4 API

אפשר להוסיף גיליונות חדשים על ידי שליחת בקשת AddSheet בשיטה 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>

‫v4 API

כדי לעדכן את הגודל, השם ומאפיינים אחרים של הגיליון, צריך לשלוח בקשת updateSheetProperties בשיטה 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 של גיליון, משתמשים ב-method ‏spreadsheets.get של הגיליון האלקטרוני.

מחיקת גיליון

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

‫v3 API

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

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

‫v4 API

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

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

כדי לאחזר את sheetId של גיליון ספציפי, משתמשים בשיטה 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

‫v4 API

באמצעות Sheets API v4, אפשר לאחזר שורות לפי טווח באמצעות המתודות 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>

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

‫v4 API

בעזרת Sheets API v4, אפשר להוסיף שורות באמצעות המתודה 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>

‫v4 API

בעזרת 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"]]
}

אפשר גם לעדכן נתונים בשורות באמצעות השיטה 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. (במקרה כזה, לא צריך לאחזר את השורה לפני שמוחקים אותה).

v4 API

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

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

אפשר לאחזר את sheetId של גיליון באמצעות ה-method‏ 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

‫Sheets API 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>

‫v4 API

כדי לאחזר נתונים מתאים, קוראים לשיטה 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 אם רוצים לאחזר כמה טווחים של נתוני תאים. אם רוצים לגשת למאפיינים של תאים, כמו עיצוב, צריך להשתמש בשיטה 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>

‫v4 API

אפשר לערוך תא בודד ב-Sheets API v4 באמצעות המתודה 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)"]]}

אם אתם מבצעים כמה עריכות של תאים, כדאי להשתמש בשיטה spreadsheets.values.batchUpdate כדי להנפיק אותן בבקשה אחת.

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

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

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

‫v3 API

כדי לערוך כמה תאים, קודם צריך לאחזר פיד תאים של גליון העבודה. הערך מכיל כתובת URL של קובץ אצווה. שולחים בקשה לכתובת ה-URL הזו, עם גוף בקשה שמתאר את התאים שרוצים לעדכן ואת התוכן החדש של התאים.POST המבנה של הבקשה 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 שמכיל את הנתיב המלא למזהה התא. כל השדות האלה הם שדות חובה לכל רשומה.

‫v4 API

‫Sheets API v4 מספק עריכה של ערכי תאים בקבוצות באמצעות השיטה 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 מחזיר שגיאה.