שיטות מומלצות להשגת התוצאות הטובות ביותר

יש כמה עקרונות שצריך לפעול לפיהם כשמשתמשים ב-Google Docs API. רשימת המדינות כוללת את:

  • עריכה לאחור לצורך יעילות
  • תוכנית לשיתוף פעולה
  • מוודאים עקביות למצב באמצעות השדה WriteControl

החלקים הבאים מסבירים את העקרונות האלה.

עריכה לאחור לצורך יעילות

בקריאה יחידה לשיטה documents.batchUpdate, מסדרים את הבקשות לפי סדר יורד במיקום האינדקס. כך לא צריך לחשב את השינויים באינדקס בגלל הוספות ומחיקות.

תוכנית לשיתוף פעולה

מצב המסמך ישתנה. בין קריאה ל-method אחת לאחרת, שותפי עריכה אחרים עשויים לעדכן את המסמך, כפי שמוצג בתרשים הבא:

איך מסמך יכול להתחלף בין קריאות לשיטה.

הדבר עלול לגרום לשגיאות אם האינדקסים שלכם שגויים. כאשר מספר משתמשים עורכים מסמך באמצעות ממשק המשתמש, Google Docs עושה זאת בשקיפות. עם זאת, כלקוח API, האפליקציה שלכם צריכה לנהל אותו. גם אם אתם לא מצפים לשיתוף פעולה בעבודה על המסמך, חשוב לתכנת את המסמך באופן מוגן ולוודא שמצב המסמך נשאר עקבי. כדי להבטיח עקביות, כדאי לעיין בקטע WriteControl.

יצירת עקביות במצב עם WriteControl

כשקוראים מסמך ומעדכנים אותו, אפשר לשלוט באופן הפעולה של אופן הטיפול בשינויים מתחרים באמצעות השדה WriteControl בשיטה documents.batchUpdate. WriteControl מספקת סמכות על האופן שבו מתבצעות בקשות כתיבה.

כך משתמשים בה:

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

לדוגמה, איך ליצור בקשה באצווה באמצעות WriteControl ראו את הדוגמה לבקשת אצווה.