מעבר מ-Sheets API v3

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

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

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

סימון ותנאים

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

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

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

בקשות הרשאה

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

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

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

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

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

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

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

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

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

היטל

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

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

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

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

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

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

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

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

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

אפשר להשתמש בשיטה Files.create ב-Drive API גם עם 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 של גרסה 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי למחוק גיליון, יוצרים בקשת DeleteSheet ב-method 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 של גרסה 3

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

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

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

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

ב-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) ואז לקרוא אותם.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מחיקת שורה

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

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

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

מחיקת שורות עם 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 של גרסה 3

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

גרסה 3 של Sheets API מחזירה את הערך 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

מאחזרים נתוני תאים על ידי קריאה למתודה 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 של גרסה 3

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

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

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