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

יש כמה עקרונות שצריך לפעול לפיהם כשמשתמשים ב-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.