אם יש לך אפליקציות קיימות שמבוססות על Google Sheets API v3, אפשר לעבור אל Google Sheets API גרסה 4. גרסת V4 מבוססת על JSON, וקלה יותר לשימוש ולהוסיף כמות משמעותית של פונקציונליות שאינה אפשרית בגרסה 3.
בדף הזה מוצג מיפוי בין הפקודות הישנות יותר של Sheets API v3 לבין פעולות מקבילות ב-Sheets API v4. המיפוי מתמקד בעיקר spreadsheets.values אוסף נתונים, שמספק פונקציונליות של קריאה וכתיבה בתאים ישירים. ההיבטים האחרים, כמו הוספת גיליונות או עדכון מאפייני גיליון, מטופלים על ידי באוסף הגיליונות האלקטרוניים. לתשומת ליבכם: מבני ה-JSON של ממשק ה-API בגרסה 4 לא תואמים לאחור עם מבני XML שנמצאים בשימוש בגרסה 3.
למידע נוסף על המשאבים הזמינים ב-Sheets v4 API, אפשר לעיין ב הפניית API.
סימון ותנאים
הממשק v3 API מתייחס לגיליונות בתוך גיליון אלקטרוני מסוים בתור "גיליונות עבודה". המונח הזה זהה למונח "גיליונות" שבהם משתמש הגרסה 4 API.
לעיתים קרובות, ממשקי ה-API מחייבים לציין מזהה גיליון אלקטרוני של הגיליון האלקטרוני שאיתו אתם עובדים. לעיתים קרובות הם מחייבים גם את המזהה של הגיליון שעבר שינוי ועיבוד. הערכים האלה מופיעים כחלק מנקודת הקצה ל-API כתובת URL, כפרמטרים של שאילתה או כחלק מגוף הבקשה. בדף הזה ה-placeholders spreadsheetId ו-sheetId להתייחס למזהי הגיליון האלקטרוני והגיליון, בהתאמה. כשמשתמשים בשיטות שמתואר בדף הזה, מחליפים את המזהים בפועל במיקומים האלה.
v3 API גם מקצה מזהה לשורות שאוחזרו באמצעות list feed; מיוצגת בדף הזה באמצעות ה-placeholder rowId.
אישור בקשות
כשהאפליקציה פועלת, היא מבקשת מהמשתמשים להעניק הרשאות מסוימות. את היקפים שתגדירו באפליקציה שלכם, יקבעו אילו הרשאות האפליקציה תבקש.
v3 API
גרסה 3 של Sheets API פועלת עם היקף הרשאות אחד:
https://spreadsheets.google.com/feeds
שהוא כינוי
https://www.googleapis.com/auth/spreadsheets
אפשר להשתמש בכל אחד מהפורמטים של היקפי ההרשאות.
ממשק API של גרסה 4
ב-Sheets API v4 נעשה שימוש באחת או יותר מקבוצות ההיקף הבאות:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
יש להשתמש בהיקפי הרשאות לקריאה בלבד אם האפליקציה לא צריכה לערוך במאפייני הגיליון או הגיליון של המשתמש. שימוש בהיקפים של גיליונות אלקטרוניים במקום בהיקפים של גיליונות אלקטרוניים היקף ההרשאות של Drive, אם האפליקציה לא צריכה גישה כללית ל-Drive.
חשיפה
בגרסאות ישנות יותר של ה-API, המונח visibility מתייחס הזמינות של גיליון אלקטרוני נתון.
v3 API
Sheets API v3 מבטא את החשיפה ישירות בנקודות הקצה שלו. public
הגיליון האלקטרוני "פורסם באינטרנט" ולכן אפשר לגשת אליו
API ללא הרשאה, ואילו גיליון אלקטרוני של private דורש
אימות. הנראות מצוינת בנקודת הקצה לאחר
מזהה גיליון אלקטרוני:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
ממשק API של גרסה 4
בגרסה החדשה של Sheets API v4 אין הצהרת חשיפה מפורשת. קריאות ל-API מתבצעות באמצעות מזהים של גיליונות אלקטרוניים. אם האפליקציה לא הרשאה לגשת לגיליון האלקטרוני שצוין, תוחזר שגיאה. אחרת השיחה ממשיכה.
היטל
המונח תחזית (projection) משמש את Sheets API v3 כדי להתייחס למערך הנתונים שמוחזרת באמצעות קריאה נתונה ל-API – כל התוכן או קבוצת משנה קבועה שהם מוגדרים ב-API. ב-Sheets API v4 אין שימוש בפורמט הקרנה; במקום זאת, מאפשר שליטה רבה יותר על הנתונים שמוחזרים.
v3 API
ב-Sheets API v3 יש רק שתי הגדרות הקרנה אפשריות. full
התחזית מחזירה את כל המידע הזמין, ואילו basic מחזירה
קבוצת משנה קטנה וקבועה של נתונים (לפידים של גיליונות עבודה, רשימות ותאים).
בדומה להרשאות, חובה לציין את ההיטל בנקודת הקצה ל-API
(לאחר הגדרת החשיפה):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
קבוצת המשנה הקטנה יותר של הנתונים, שמספקת תחזית basic, היא בעלת ערך
לשיפור היעילות של הקוד, אבל אי אפשר להתאים אותו אישית.
ממשק API של גרסה 4
Sheets API v4 יכול להחזיר קבוצת נתונים מלאה, אבל לא מוגדר לו ערך קבוע
קבוצות משנה מקבילות להגדרת החשיפה של basic שב-Sheets API v3.
שיטות בגיליון האלקטרוני
מגבילים את כמות הנתונים שהם מחזירים באמצעות
פרמטר של שאילתה שדות.
לדוגמה, השאילתה הבאה מחזירה רק את הכותרות של כל בגיליון אלקטרוני מסוים:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
יצירת גיליון אלקטרוני
v3 API
Sheets API v3 לא מספק אמצעי ליצירת גיליונות אלקטרוניים חדשים.
במקום זאת, השתמשו ב-Drive API Files.create.
יכול לשמש ליצירת קבצים חדשים של גיליונות אלקטרוניים. לשם כך נדרשת
להצהרה על ההיקף של https://www.googleapis.com/auth/drive.
ממשק API של גרסה 4
באמצעות ה-method 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"}
}הצגת רשימה של גיליונות אלקטרוניים עבור המשתמש המאומת
v3 API
פיד v3 של Sheets API מאפשר לאפליקציה לאחזר רשימה של כל גיליונות אלקטרוניים שאליהם המשתמש המאומת יכול לגשת. הפיד של הגיליון האלקטרוני נקודת הקצה היא:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
ממשק API של גרסה 4
Sheets API v4 לא מאפשר את הפעולה הספציפית הזו. ההמלצות שלנו העברה של האפליקציה לשימוש בהיקף של drive.file בשילוב עם הכלי לבחירת Google Sheets לבחירת גיליון אלקטרוני.
במקרים שבהם יש צורך בהצגת גיליונות אלקטרוניים, אפשר לשכפל אותם.
באמצעות המתודה 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 שמאפשרת גישה למידע הזה ועוד הרבה יותר.
v3 API
אפשר לגשת אל הפיד של גיליון העבודה מנקודת הקצה הזו ב-API (באמצעות כותרת ההרשאה המתאימה):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
לתגובה לבקשה הזו יש מבנה דומה לזה, עם
הנתונים של כל גיליון הכלולים ב-<entry> נפרד:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
ממשק API של גרסה 4
השדה spreadsheets.get
כדי לקבל מאפייני גיליון ומטא-נתונים אחרים,
יותר ממה שזמין ב-Sheets API v3. אם
אתם רוצים לקרוא את מאפייני הגיליון, מגדירים את השאילתה includeGridData
ל-false כדי למנוע הכללה של נתוני התא בגיליון האלקטרוני:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Spreadsheet
התשובה מכילה מערך של Sheet
אובייקטים; תוכלו למצוא את כותרות הגיליון ואת הפרטים על הגודל באופן ספציפי.
מתחת ל-SheetProperties
של האובייקטים האלה. לדוגמה:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}הוספת גיליון לגיליון אלקטרוני
שני ממשקי ה-API מאפשרים להוסיף גיליונות חדשים לגיליון אלקטרוני קיים.
v3 API
Sheets API v3 יכול להוסיף גיליונות עבודה חדשים לגיליון אלקטרוני על ידי יצירת
עוקב אחר בקשת POST (מאומתת). אפשר לציין את הגודל של
גיליון חדש:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
ממשק API של גרסה 4
כדי להוסיף גיליונות חדשים, צריך ליצור AddSheet בקשה ב-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 גרסה 4 מאפשרת גם את הפעולה הזו, אבל אפשר להשתמש בה גם כדי לעדכן מאפיינים אחרים של גיליון. לתשומת ליבכם: הקטנת הגיליון עלולה לגרום לכך שהנתונים בתאים שנחתכו נמחקה ללא אזהרה.
v3 API
כדי לשנות את הכותרת או הגודל של גיליון עבודה, התחל באחזור
לפיד של גיליון עבודה וגם
למצוא את הרשומה הרצויה בגיליון העבודה, שמכילה כתובת URL מסוג edit.
עדכון המטא-נתונים של גיליון העבודה ושליחתם בגוף בקשת PUT
לכתובת ה-URL לעריכה. לדוגמה:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
ממשק API של גרסה 4
כדי לעדכן את הגודל, הכותרת ומאפייני הגיליון האחרים, יוצרים
updateSheetProperties
בבקשה
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
כדי למחוק גיליון עבודה, תחילה באחזור
worksheet feed, ואז
שולחים בקשת DELETE בכתובת ה-URL של edit של רשומת היעד בגיליון העבודה.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
ממשק API של גרסה 4
כדי למחוק גיליון, מזינים
DeleteSheet
בבקשה
spreadsheets.batchUpdate
. גוף הבקשה של POST צריך להכיל רק את ה-sheetId של
של הגיליון למחיקה. לדוגמה:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
כדי לאחזר את sheetId של גיליון ספציפי, משתמשים בפונקציה גיליון אלקטרוני 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
בנוסף, גרסה 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 (מיון).
ואז לקרוא אותה.
בשלב הזה, ל-Sheets API v4 אין מקבילה ישירה לשאילתות המובנה של Sheets API v3. עם זאת, אפשר לאחזר את הנתונים הרלוונטיים למיין אותו לפי הצורך באפליקציה.
הוספה של שורת נתונים חדשה
אפשר להוסיף שורה חדשה של נתונים לגיליון באמצעות כל אחד מממשקי ה-API האלה.
v3 API
כדי למצוא את כתובת ה-URL של פיד מבוסס-רשימה עבור גיליון עבודה נתון, מאחזרים הפיד של גיליון העבודה מוצאים את כתובת ה-URL של הפוסט ברשומה הרלוונטית בגיליון העבודה.
כדי להוסיף שורת נתונים, צריך לשלוח בקשת POST לכתובת ה-URL של הפוסט:
באמצעות כותרת הרשאה מתאימה. לדוגמה:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
גוף הבקשה של POST צריך להכיל רשומה של נתוני השורה כדי
להוסיף, כאשר תאים ספציפיים מפנים לכותרות של עמודות:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
שורות חדשות יתווספו לסוף הגיליון שצוין.
ממשק API של גרסה 4
ב-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>
ממשק 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 method; יעיל יותר להשתמש בשיטה הזאת אם של שורות או עדכונים בתא.
בנוסף, Sheets API v4 מאפשר גם לערוך את מאפייני התא עיצוב של תאים באמצעות UpdateCells או RepeatCell בזמן spreadsheets.batchUpdate.
מחיקת שורה
שני ממשקי ה-API תומכים במחיקת שורות. שורה שנמחקה תוסר והשורות שמתחתיו נדחפות למעלה.
v3 API
כדי למחוק שורה, קודם מאחזרים את השורה שרוצים למחוק
list feed,
ואז שולחים בקשת 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 מטופלת על ידי spreadsheet.batchUpdate קריאה ל-method, באמצעות DeleteDimension בקשה. הבקשה הזו יכולה לשמש גם להסרת עמודות, ומפתחים ולבחור להסיר רק חלק משורה או עמודה. לדוגמה, לאחר מכן מסירה את השורה השישית בגיליון עם המזהה הנתון (מדדי השורה לא מבוססים על אפס, כשאינדקס ההתחלה כולל את ה-startIndex ולא כולל אינדקס הסיום):
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>
ממשק 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 שיטות לשינוי תוכן של תא.
v3 API
כדי לערוך את התוכן של תא יחיד, קודם צריך לחפש את הערך של התא
פיד סלולרי.
הרשומה מכילה כתובת URL לעריכה. צריך לעדכן את הרשומה כך שתשקף את התוכן
שרוצים לכלול בתא, ואז שולחים בקשת PUT לכתובת ה-URL לעריכה
עם רשומת התא המעודכנת בתור גוף הבקשה. לדוגמה,
מתבצע עדכון של תא D2 (R2C4) כך שיכלול את הנוסחה SUM:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
ממשק API של גרסה 4
ב-Sheets API v4 אפשר לערוך תא יחיד באמצעות
spreadsheets.values.update
. ל-method הזה נדרש פרמטר השאילתה 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 שמכיל את הנתיב המלא אל
המזהה של התא. כל השדות האלה הם שדות חובה לכל רשומה.
ממשק 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 מחזיר שגיאה.