Method: documents.batchUpdate

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

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

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

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

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

בקשת HTTP

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

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

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

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