Method: documents.batchUpdate

یک یا چند به‌روزرسانی را روی سند اعمال می‌کند.

هر request قبل‌از اعمال شدن اعتبارسنجی می‌شود. اگر هر درخواستی نامعتبر باشد، کل درخواست ناموفق خواهد بود و هیچ‌چیزی اعمال نخواهد شد.

برخی‌از درخواست‌ها replies دارند تا اطلاعاتی درباره نحوه اعمال آن‌ها به شما ارائه دهند. درخواست‌های دیگر نیازی به برگرداندن اطلاعات ندارند؛ هریک از این درخواست‌ها پاسخ خالی برمی‌گردانند. ترتیب پاسخ‌ها با ترتیب درخواست‌ها مطابقت دارد.

برای مثال، فرض کنید batchUpdate را با چهار به‌روزرسانی فراخوانی می‌کنید و فقط به‌روزرسانی سوم اطلاعات را برمی‌گرداند. پاسخ به این ترتیب شامل دو پاسخ خالی، پاسخ به درخواست سوم، و یک پاسخ خالی دیگر خواهد بود.

ازآنجایی‌که ممکن است کاربران دیگر درحال ویرایش سند باشند، سند ممکن است دقیقاً تغییرات شما را منعکس نکند: تغییرات شما ممکن است نسبت‌به تغییرات مشارکت‌کننده تغییر کند. اگر مشارکت‌کننده‌ای وجود نداشته باشد، سند باید تغییرات شما را منعکس کند. درهرصورت، به‌روزرسانی‌های موجود در درخواست شما تضمین می‌شود که به‌صورت اتمی با هم اعمال شوند.

درخواست HTTP

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

نشانی وب از نحو ترانویسی 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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
فیلدها
documentId

string

شناسه سندی که به‌روزرسانی‌ها روی آن اعمال شده است.
replies[]

object (Response)

پاسخ به‌روزرسانی‌ها. این مورد با به‌روزرسانی‌ها مطابقت کامل دارد، اگرچه پاسخ به برخی‌از درخواست‌ها ممکن است خالی باشد.
writeControl

object (WriteControl)

کنترل نوشتن به‌روزشده پس‌از اعمال درخواست.
suggestionResponses[]

object (SuggestionResponse)

پیشنهادهایی که تحت تأثیر هر به‌روزرسانی قرار گرفته‌اند. این با به‌روزرسانی‌ها ۱ به ۱ مطابقت دارد.
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)

نحوه اعمال به‌روزرسانی‌های درخواست در سند.

اگر مشخص نشده باشد، به‌روزرسانی‌های درخواست به‌عنوان ویرایش‌های عادی اعمال خواهد شد.
نسخه بازبینی سند را برای نوشتن و نحوه عملکرد درخواست را درصورتی‌که آن نسخه بازبینی نسخه فعلی سند نباشد تعیین می‌کند. اگر هیچ‌کدام از فیلدها مشخص نشده باشد، به‌روزرسانی‌ها روی آخرین بازبینی اعمال می‌شود. فهرست زیر شامل فیلدهای متقابلاً انحصاری است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد:
requiredRevisionId

string

revision ID اختیاری سند که درخواست نوشتن برای آن اعمال می‌شود. اگر این آخرین نسخه اصلاح‌شده سند نباشد، درخواست پردازش نمی‌شود و خطای درخواست بد ۴۰۰ برمی‌گرداند.

وقتی شناسه بازبینی الزامی در پاسخ برگردانده می‌شود، نشان‌دهنده شناسه بازبینی سند پس‌از اعمال درخواست است.
targetRevisionId

string

هدف اختیاری revision ID سندی که درخواست نوشتن روی آن اعمال می‌شود.

اگر تغییرات مشارکت‌کننده پس‌از خوانده شدن سند بااستفاده از میانای برنامه‌سازی کاربردی رخ داده باشد، تغییرات تولیدشده توسط این درخواست نوشتن دربرابر تغییرات مشارکت‌کننده اعمال می‌شود. این کار منجر به ایجاد نسخه جدیدی از سند می‌شود که هم تغییرات مشارکت‌کننده و هم تغییرات درخواست را دربرمی‌گیرد و سرور «سندنگار» تغییرات متعارض را حل‌وفصل می‌کند. هنگام استفاده از شناسه نسخه هدف، می‌توان کارخواه API را به‌عنوان مشارکت‌کننده دیگری در سند درنظر گرفت.

شناسه ویرایش هدف فقط می‌تواند برای نوشتن در نسخه‌های اخیر سند استفاده شود. اگر نسخه هدف خیلی قدیمی‌تر از جدیدترین نسخه باشد، درخواست پردازش نمی‌شود و خطای درخواست نامعتبر ۴۰۰ برمی‌گرداند. پس‌از بازیابی جدیدترین نسخه سند، درخواست باید دوباره امتحان شود. معمولاً شناسه بازبینی تا چند دقیقه پس‌از خوانده شدن برای استفاده به‌عنوان بازبینی هدف معتبر باقی می‌ماند، اما برای اسنادی که مکرراً ویرایش می‌شوند، این بازه زمانی ممکن است کوتاه‌تر باشد.
پایان فیلدهای متقابلاً انحصاری.

WriteMode

تعیین می‌کند که به‌روزرسانی‌های درخواست چگونه باید روی سند اعمال شود.

شمارشی‌ها
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

وضعیت به‌روزرسانی‌های نظر در درخواست دسته‌ای.

شمارشی‌ها
COMMENT_UPDATE_STATE_UNSPECIFIED وضعیت به‌روزرسانی‌های نظر مشخص نیست.
NO_UPDATES_REQUESTED هیچ به‌روزرسانی نظری در درخواست دسته‌ای درخواست نشده است.
ALL_SAVED همه به‌روزرسانی‌های نظر درخواست‌شده در درخواست دسته‌ای اعمال شد.
ALL_FAILED_UNKNOWN_REASON همه به‌روزرسانی‌های نظر درخواستی ناموفق بود.