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

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

התחשבות ברווחים מפרסום בכרטיסיות

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

חשוב לזכור:

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