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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
שדות
documentId

string

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

object (Response)

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

object (WriteControl)

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

object (SuggestionResponse)

ההצעות שהושפעו מכל עדכון. העדכונים האלה תואמים לעדכונים של Chrome.

commentUpdateState

enum (CommentUpdateState)

האם עדכוני התגובות הוחלו בבקשה באצווה.

היקפי הרשאות

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

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

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

WriteControl

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

ייצוג JSON 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
שדות
writeMode

enum (WriteMode)

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

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

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

string

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

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

string

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

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

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

WriteMode

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

טיפוסים בני מנייה (enum)
WRITE_MODE_UNSPECIFIED לא צוין מצב כתיבה. ברירת המחדל היא ההתנהגות של EDIT.
EDIT החלת כל העדכונים כעריכות רגילות.
SUGGEST החלת כל העדכונים כהצעות.

SuggestionResponse

ההצעות שהושפעו מעדכון מסוים.

ייצוג JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
שדות
createdSuggestionIds[]

string

מזהי ההצעות שנוצרו במהלך העדכון.
updatedSummarySuggestionIds[]

string

המזהים של ההצעות שהסיכומים שלהן עודכנו במהלך העדכון.
deletedSuggestionIds[]

string

המזהים של ההצעות שנמחקו במהלך העדכון.
acceptedSuggestionIds[]

string

מזהי ההצעות שאושרו במהלך העדכון.
rejectedSuggestionIds[]

string

המזהים של ההצעות שנדחו במהלך העדכון.

CommentUpdateState

הסטטוס של עדכוני התגובות בבקשה באצווה.

טיפוסים בני מנייה (enum)
COMMENT_UPDATE_STATE_UNSPECIFIED לא מצוין סטטוס העדכונים של התגובות.
NO_UPDATES_REQUESTED לא נשלחו בקשות לעדכון תגובות בבקשת האצווה.
ALL_SAVED כל העדכונים שביקשתם לתגובות בוצעו בבקשת האצווה.
ALL_FAILED_UNKNOWN_REASON כל העדכונים המבוקשים של התגובות נכשלו.