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

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

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

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

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

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

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

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

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

אם האינדקסים שגויים, יכולות להופיע שגיאות. אם כמה משתמשים עורכים מסמך באמצעות ממשק המשתמש, 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 אחראי למיזוג התוכן.

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

התחשבות בכרטיסיות

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

חשוב לזכור:

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