דף זה תורגם על ידי Cloud Translation API.

מעבר מ-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.

סימנים ומונחים

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

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

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

הרשאה לבקשות

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

API v3

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

https://spreadsheets.google.com/feeds

שהוא כינוי ל-

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

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

API v4

ב-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, המונח חשיפה מתייחס לזמינות של גיליון אלקטרוני נתון.

API v3

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

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

API v4

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

היטל

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

API v3

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

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

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

API v4

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

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

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

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

API v3

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

API v4

אפשר להשתמש גם ב-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"}
}

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

API v3

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

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

API v4

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

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

API v3

אפשר לגשת אל פיד הגיליון האלקטרוני מנקודת הקצה הזו ל-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 v4

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

API v3

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

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

API v3

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

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

API v3

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

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

API v4

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

API v3

כדי לקבוע את כתובת ה-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 v4

באמצעות 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.

API v3

כדי לקבוע את כתובת ה-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 v4

באמצעות 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 מאפשרים לעדכן את נתוני השורות בערכים חדשים.

API v3

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

אחרי העדכון של הרשומה, שולחים בקשת 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 v4

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

API v3

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

מחיקת שורות באמצעות Sheets API v4 מתבצעת באמצעות קריאה ל-method‏ 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 של גיליון באמצעות השיטה spreadsheet.get.

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

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

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

API v3

כדי לקבוע את כתובת ה-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>

API v4

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

API v3

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

אפשר לערוך תא יחיד ב-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)"]]}

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

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

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

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

API v3

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

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 מחזיר שגיאה.