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

هنگام استفاده از 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 ، به این مثال درخواست دسته ای مراجعه کنید.

برگه ها را در نظر بگیرید

یک سند واحد می‌تواند حاوی چندین برگه باشد که نیاز به رسیدگی خاصی در درخواست‌های API شما دارند.

در اینجا چیزی است که باید به خاطر بسپارید:

  1. پارامتر includeTabsContent را در متد documents.get روی true تنظیم کنید تا محتوا را از همه برگه های یک سند بازیابی کنید. به طور پیش فرض، همه محتویات برگه برگردانده نمی شوند.
  2. شناسه(های) برگه(ها) را برای اعمال هر Request در متد documents.batchUpdate مشخص کنید. هر Request شامل راهی برای مشخص کردن برگه هایی است که به روز رسانی را در آنها اعمال کنید. به‌طور پیش‌فرض، اگر یک برگه مشخص نشده باشد، در بیشتر موارد Request در اولین برگه سند اعمال می‌شود. برای جزئیات بیشتر به مستندات Request مراجعه کنید.