במדריך הזה נסביר על השיטות העיקריות של בקשות ותשובות שמרכיבות את 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 method כדי לאחזר מסמכים שפורסמו. אחרי הפרסום, מסמכים ציבוריים משתמשים בפורמט שונה של כתובת 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)
בשיטות מומלצות לשליחת בקשות מקובצות מוסבר איך לשלוח קריאות מקובצות ל-Docs API, ובמסמכי העיון של documents.batchUpdate מפורטים סוגי הבקשות והתגובות.
פעולות של עדכון בכמות גדולה
יש סוגים שונים של בקשות לעדכון אצווה. ריכזנו כאן את סוגי הבקשות בקטגוריות שונות.