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