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)
  },
  "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

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

کنترل نوشتن

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

نمایش JSON 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
فیلدها
writeMode

enum ( WriteMode )

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

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

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

string

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

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

targetRevisionId

string

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

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

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

حالت نوشتن

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

انوم‌ها
WRITE_MODE_UNSPECIFIED حالت نوشتن مشخص نشده است. پیش‌فرض روی حالت EDIT است.
EDIT تمام به‌روزرسانی‌ها را مانند ویرایش‌های عادی اعمال کنید.
SUGGEST تمام به‌روزرسانی‌ها را به عنوان پیشنهاد اعمال کنید.

پیشنهاد و پاسخ

پیشنهادهایی که تحت تأثیر یک به‌روزرسانی خاص قرار گرفته‌اند.

نمایش JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
فیلدها
createdSuggestionIds[]

string

شناسه‌های پیشنهادهایی که در طول به‌روزرسانی ایجاد شده‌اند.

updatedSummarySuggestionIds[]

string

شناسه‌های پیشنهادهایی که خلاصه‌های آنها در طول به‌روزرسانی به‌روزرسانی شده است.

deletedSuggestionIds[]

string

شناسه‌های پیشنهادهایی که در طول به‌روزرسانی حذف شده‌اند.

acceptedSuggestionIds[]

string

شناسه‌های پیشنهادهایی که در طول به‌روزرسانی پذیرفته شده‌اند.

rejectedSuggestionIds[]

string

شناسه‌های پیشنهادهایی که در طول به‌روزرسانی رد شده‌اند.

وضعیت به‌روزرسانی دیدگاه

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

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