Method: documents.batchUpdate

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

כל request מאומת לפני היישום. אם אחת מהבקשות לא תקפה, הבקשה כולה תיכשל ולא תתבצע אף פעולה.

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

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

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

בקשת HTTP

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

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