Method: documents.batchUpdate

החלת עדכון אחד או יותר במסמך.

כל request מאומת לפני היישום. אם בקשה כלשהי אינה חוקית, הבקשה כולה תיכשל ולא יושם שום דבר.

בבקשות מסוימות יש replies כדי לספק מידע על אופן היישום שלהן. בקשות אחרות לא צריכות להחזיר מידע. כל אחת מהן תחזיר תשובה ריקה. סדר התשובות תואם לסדר הבקשות.

לדוגמה, נניח שקוראים ל-batchUpdate עם ארבעה עדכונים, ורק השלישי מחזיר מידע. התשובה תכלול שתי תשובות ריקות, תשובה לבקשה השלישית ותשובה ריקה נוספת, בסדר הזה.

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

בקשת HTTP

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
documentId

string

המזהה של המסמך שצריך לעדכן.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
שדות
requests[]

object (Request)

רשימת העדכונים שיש להחיל על המסמך.
writeControl

object (WriteControl)

התפקיד הזה מאפשר לשלוט באופן הביצוע של בקשות לכתיבה.

גוף התשובה

הודעת תשובה מבקשת של documents.batchUpdate.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול נתונים במבנה הבא:

ייצוג JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
שדות
documentId

string

המזהה של המסמך שעליו הוחלו העדכונים.
replies[]

object (Response)

התשובה לעדכונים. המערכת ממפה 1:1 עם העדכונים, אבל יכול להיות שהתשובות לחלק מהבקשות יהיו ריקות.
writeControl

object (WriteControl)

בקרת הכתיבה המעודכנת אחרי החלת הבקשה.

היקפי ההרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

מידע נוסף זמין במדריך להרשאות.

WriteControl

התפקיד הזה מאפשר לשלוט באופן הביצוע של בקשות לכתיבה.

ייצוג JSON 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
שדות
שדה איחוד control. המדיניות הזו קובעת את הגרסה הקודמת של המסמך שצריך לכתוב בו, ואיך הבקשה צריכה להתנהג אם הגרסה הזו היא לא הגרסה הנוכחית של המסמך. אם לא צוין אף אחד מהשדות, העדכונים יוחלו על הגרסה האחרונה. control יכול להיות רק אחת מהאפשרויות הבאות:
requiredRevisionId

string

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

כשבתשובה מוחזר מזהה גרסה קודמת, הוא מציין את מזהה הגרסה הקודמת של המסמך לאחר החלת הבקשה.
targetRevisionId

string

היעד האופציונלי revision ID של המסמך שעליו חלה בקשת הכתיבה.

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

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