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