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)

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

enum (CommentUpdateState)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של 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)

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

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

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

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