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

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