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