יש כמה עקרונות שמומלץ לפעול לפיהם כשמשתמשים ב-Google Docs API. האפשרויות הן:
- עריכה אחורה כדי לשפר את היעילות
- תוכנית לשיתוף פעולה
- שמירה על עקביות של המצב באמצעות השדה
WriteControl
העקרונות האלה מוסברים בחלקים הבאים.
עריכה אחורה כדי לשפר את היעילות
בקריאה יחידה ל-method documents.batchUpdate
, מסדרים את הבקשות בסדר יורד של מיקום האינדקס. כך לא צריך לחשב את השינויים באינדקס כתוצאה מהוספות ומחיקות.
תוכנית לשיתוף פעולה
יש לצפות שמצב המסמך ישתנה. בין הפעלת שיטה אחת לאחרת, שותפי עריכה אחרים עשויים לעדכן את המסמך, כפי שמוצג בתרשים הבא:
אם האינדקסים שלכם שגויים, עלולות להתקבל שגיאות. כאשר משתמשים רבים עורכים מסמך באמצעות ממשק המשתמש, Google Docs עושה זאת בשקיפות. עם זאת, כלקוח API, האפליקציה שלכם חייבת לנהל זאת. גם אם אתם לא מצפים לשיתוף פעולה במסמך, חשוב לתכנת באופן הגנתי ולוודא שמצב המסמך יישאר עקבי. אחת הדרכים לשמור על עקביות,
עיינו בקטע WriteControl
.
קביעת עקביות של מצב באמצעות WriteControl
כשקוראים מסמך ומעדכנים אותו, אפשר לשלוט בהתנהגות של אופן הטיפול בשינויים מתחרים באמצעות השדה WriteControl
ב-method documents.batchUpdate
. WriteControl
מספק הרשאה לגבי אופן הביצוע של בקשות לכתיבה.
כך משתמשים בו:
- מקבלים את המסמך באמצעות השיטה
documents.get
ושומרים אתrevisionId
מהמשאבdocuments
שמוחזר. - כותבים את בקשות העדכון.
- מוסיפים אובייקט
WriteControl
אופציונלי עם אחת משתי אפשרויות:- השדה
requiredRevisionId
מוגדר לערךrevisionId
של המסמך שעליו חלה בקשת הכתיבה. אם המסמך עבר שינוי מאז בקשת הקריאה של ה-API, בקשת הכתיבה לא מעובדת ומחזירה שגיאה. - השדה
targetRevisionId
מוגדר לערךrevisionId
של המסמך שבקשת הכתיבה חלה עליו. אם המסמך השתנה מאז בקשת הקריאה של ה-API, השינויים בבקשת הכתיבה יחולו על השינויים של שותף העריכה. התוצאה של בקשת הכתיבה משלבת גם את השינויים בבקשת הכתיבה וגם את השינויים של שותף העריכה בגרסה חדשה של המסמך. שרת Docs אחראי למיזוג התוכן.
- השדה
בדוגמה הזו לבקשת אצווה מופיעות דוגמה לבניית בקשה באצווה באמצעות WriteControl
.