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

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

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

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

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

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

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

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

איך מסמך יכול להשתנות בין קריאות ל-method.

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

שמירה על עקביות המצב באמצעות WriteControl

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

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

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

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

צריך להביא בחשבון את הכרטיסיות

מסמך אחד יכול להכיל כמה כרטיסיות, שדורשות טיפול ספציפי בבקשות ה-API.

חשוב לזכור:

  1. כדי לאחזר את התוכן מכל הכרטיסיות במסמך, מגדירים את הפרמטר includeTabsContent לערך true בשיטה documents.get. כברירת מחדל, לא כל תוכן הכרטיסיות מוחזר.
  2. מציינים את מזהי הכרטיסיות שרוצים להחיל עליהן כל Request ב-method documents.batchUpdate. כל Request כולל דרך לציין את הכרטיסיות שעליהן העדכון יחול. כברירת מחדל, אם לא מציינים כרטיסייה, ברוב המקרים הקוד Request יחול על הכרטיסייה הראשונה במסמך. לפרטים נוספים, עיינו במסמכי העזרה של Request.