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 )

پاسخ به‌روزرسانی‌ها. این به صورت ۱:۱ با به‌روزرسانی‌ها نگاشت می‌شود، اگرچه پاسخ به برخی درخواست‌ها ممکن است خالی باشد.

writeControl

object ( WriteControl )

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

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

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

برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.

کنترل نوشتن

کنترل نحوه اجرای درخواست‌های نوشتن را فراهم می‌کند.

نمایش 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 فیلد Union. ویرایش سند مورد نظر برای نوشتن و نحوه رفتار درخواست را در صورتی که آن ویرایش، ویرایش فعلی سند نباشد، تعیین می‌کند. اگر هیچ‌کدام از فیلدها مشخص نشده باشند، به‌روزرسانی‌ها روی آخرین ویرایش اعمال می‌شوند. control فقط می‌تواند یکی از موارد زیر باشد:
requiredRevisionId

string

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

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

targetRevisionId

string

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

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

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