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