במדריך הזה נסביר על השיטות העיקריות של בקשות ותגובות שמרכיבות את Google Docs API, ואיך אפשר לעדכן מסמך באצוות.
אפשר להפעיל את Google Docs API באמצעות בקשת HTTP, או באמצעות הפעלת שיטה בספריית לקוח ספציפית לשפה. הן שוות בערך.
Google Docs API מחזיר תגובת HTTP, שבדרך כלל כוללת את התוצאה של הפעלת הבקשה. כשמשתמשים בספריית לקוח כדי לשלוח בקשות, התשובות מוחזרות באופן ספציפי לשפה.
שיטות בקשה
Docs API תומך בשיטות הבאות:
documents.create: יצירת מסמך ריק ב-Google Docs.
documents.get: מחזירה מופע מלא של המסמך שצוין. אפשר לנתח את ה-JSON שמוחזר כדי לחלץ את תוכן המסמך, העיצוב ותכונות אחרות.
documents.batchUpdate: שליחת רשימה של בקשות עריכה להחלה אטומית על המסמך, והחזרת רשימה של תוצאות.
השיטות documents.get ו-documents.batchUpdate דורשות documentId כפרמטר כדי לציין את מסמך היעד. השיטה documents.create מחזירה מופע של המסמך שנוצר, שממנו אפשר לקרוא את documentId. מידע נוסף על documentId זמין במאמר מזהה מסמך.
שימו לב שאי אפשר להשתמש בשיטה documents.get כדי לאחזר מסמכים שפורסמו. אחרי שמפרסמים מסמכים ציבוריים, הם מקבלים פורמט שונה של כתובת URL. ניסיונות להשתמש בכתובת ה-URL החדשה documentId עם השיטה documents.get מחזירים תגובה עם קוד סטטוס HTTP 404. אין דרכים לאחזר את documentId המקורי מכתובת ה-URL שפורסמה. כדי לעקוף את הבעיה, אפשר להשתמש ב-Drive API כדי להעתיק את המסמך שפורסם למסמך משותף, ואז לגשת לקובץ הזה במקום. מידע נוסף זמין במאמר בנושא הגדרת קבצים כגלויים לכולם ב-Google Docs, Sheets, Slides ו-Forms.
עדכונים באצווה
ה-method documents.batchUpdate מקבלת רשימה של אובייקטים מסוג request, שכל אחד מהם מציין בקשה יחידה לביצוע. לדוגמה, מעצבים פסקה ואז מוסיפים תמונה בתוך השורה. כל בקשה עוברת אימות לפני שהיא מוחלת, והבקשות מעובדות לפי הסדר שבו הן מופיעות בבקשה באצווה.
כל הבקשות בעדכון אצווה מוחלות באופן אטומי. כלומר, אם בקשה כלשהי לא תקינה, העדכון כולו לא יצליח ואף אחד מהשינויים (שיכול להיות שהם תלויים זה בזה) לא יחול.
חלק מהשיטות של documents.batchUpdate מספקות תשובות עם מידע על הבקשות שהוגשו. השיטות האלה מחזירות response
body
שמכיל רשימה של אובייקטים מסוג response.
בבקשות אחרות לא צריך להחזיר מידע, והתשובה תהיה ריקה. האובייקטים ברשימת התשובות תופסים את אותו סדר אינדקס כמו הבקשה המתאימה.
דפוס נפוץ ליצירת בקשות באצווה נראה כך:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
בשיטות מומלצות לשליחת בקשות מקובצות יש פרטים מלאים על אופן קיבוץ הקריאות ל-Docs API, ובמסמכי העיון של documents.batchUpdate יש מידע על סוגי הבקשות והתגובות.
פעולות של עדכון בכמות גדולה
יש סוגים שונים של בקשות לעדכון אצווה. לפניכם פירוט של סוגי הבקשות, שמחולקות לקטגוריות שונות.