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

هنگام استفاده از 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. شناسه (ID) تب (tab) های مورد نظر برای اعمال هر Request را در متد documents.batchUpdate مشخص کنید. هر Request شامل روشی برای مشخص کردن تب‌هایی است که به‌روزرسانی روی آنها اعمال می‌شود. به طور پیش‌فرض، اگر تبی مشخص نشده باشد، Request در بیشتر موارد روی اولین تب در سند اعمال می‌شود. برای جزئیات بیشتر به مستندات Request مراجعه کنید.