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