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