بهترین روش ها برای بهترین نتایج

هنگام استفاده از Google Docs API چندین اصل وجود دارد که باید رعایت کنید. این شامل:

  • برای بهره وری به عقب ویرایش کنید
  • برای همکاری برنامه ریزی کنید
  • از سازگاری حالت با استفاده از فیلد WriteControl اطمینان حاصل کنید

بخش های بعدی این اصول را توضیح می دهند.

برای بهره وری به عقب ویرایش کنید

در طی یک تماس با روش documents.batchUpdate ، درخواست‌های خود را به ترتیب نزولی مکان فهرست سفارش دهید. این نیاز به محاسبه تغییرات شاخص به دلیل درج و حذف را حذف می کند.

برای همکاری برنامه ریزی کنید

انتظار داشته باشید که وضعیت سند تغییر کند. بین یک فراخوانی روش و دیگری، همکاران دیگر ممکن است سند را به روز کنند، همانطور که در نمودار زیر نشان داده شده است:

چگونه یک سند می تواند بین فراخوانی های متد تغییر کند.

اگر ایندکس های شما اشتباه باشد، این می تواند منجر به خطا شود. با چندین کاربر که یک سند را با استفاده از رابط کاربری ویرایش می‌کنند، Google Docs به طور شفاف از این موضوع مراقبت می‌کند. با این حال، به عنوان یک مشتری API، برنامه شما باید این را مدیریت کند. حتی اگر همکاری در سند را پیش‌بینی نمی‌کنید، مهم است که به صورت تدافعی برنامه‌ریزی کنید و مطمئن شوید که وضعیت سند ثابت می‌ماند. برای یک راه برای اطمینان از سازگاری، بخش WriteControl را بررسی کنید.

سازگاری حالت را با WriteControl ایجاد کنید

هنگامی که یک سند را می خوانید و سپس به روز می کنید، می توانید با استفاده از فیلد WriteControl در روش documents.batchUpdate ، رفتار تغییرات رقیب را کنترل کنید. WriteControl بر نحوه اجرای درخواست های نوشتن اختیار می دهد.

در اینجا نحوه استفاده از آن آمده است:

  1. سند را با استفاده از روش documents.get دریافت کنید و revisionId از منبع documents برگشتی ذخیره کنید.
  2. درخواست های به روز رسانی خود را بنویسید.
  3. شامل یک شی WriteControl اختیاری با یکی از دو گزینه:
    1. فیلد requiredRevisionId روی revisionId سندی که درخواست نوشتن روی آن اعمال می شود تنظیم می شود. اگر سند از زمان درخواست خواندن API اصلاح شده باشد، درخواست نوشتن پردازش نمی‌شود و یک خطا برمی‌گرداند.
    2. فیلد targetRevisionId روی revisionId سندی که درخواست نوشتن روی آن اعمال می شود تنظیم می شود. اگر سند از زمان درخواست خواندن API اصلاح شده باشد، تغییرات درخواست نوشتن در برابر تغییرات همکار اعمال می شود. نتیجه درخواست نوشتن، هم تغییرات درخواست نوشتن و هم تغییرات همکار را در یک ویرایش جدید از سند ترکیب می‌کند. سرور Docs مسئول ادغام محتوا است.

برای مثالی از نحوه ساخت یک درخواست دسته ای با استفاده از WriteControl ، به این مثال درخواست دسته ای مراجعه کنید.