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