אם יש לכם אפליקציות קיימות שמבוססות על 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, הגיליונות בגיליון אלקטרוני מסוים נקראים 'גיליונות עבודה'. המונח הזה זהה למונח 'גיליונות' שמשמש ב-API בגרסה 4.
בממשקי ה-API, לעיתים קרובות צריך לציין מזהה של גיליון אלקטרוני שאתם עובדים איתו. בנוסף, לעיתים קרובות צריך לציין את המזהה של הגיליון האלקטרוני שרוצים לשנות. הערכים האלה מופיעים כחלק מכתובת ה-URL של נקודת הקצה ב-API, כפרמטרים של שאילתה או כחלק מגוף הבקשה. בדף הזה, ה-placeholder spreadsheetId מתייחס לגיליון האלקטרוני, וה-placeholder sheetId מתייחס למזהה הגיליון. כשמשתמשים בשיטות שמתוארות בדף הזה, צריך להזין את המזהים בפועל במיקומים האלה.
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
ב-Sheets API v3, הגדרות החשיפה מופיעות ישירות בנקודות הקצה (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 v4 יכול להחזיר מערך נתונים מלא, אבל הוא לא מגדיר קבוצות משנה קבועות כמו הגדרת הנראות basic ב-Sheets API v3.
השיטות באוסף 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:lastnameSheets API v3 מאפשר גם סינון של שורות ספציפיות באמצעות שאילתה מובנית (שמפנה לכותרות של עמודות):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 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 מתבצעת על ידי קריאה ל-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 של גיליון באמצעות ה-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=4Sheets 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 של קובץ אצווה. שולחים 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 שמכיל את הנתיב המלא למזהה התא. כל השדות האלה הם שדות חובה לכל רשומה.
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 מחזיר שגיאה.