این راهنما روش‌های اولیه درخواست و پاسخ را که Google Docs API را تشکیل می‌دهند و نحوه به‌روزرسانی یک سند به صورت دسته‌ای را معرفی می‌کند.
می‌توانید Google Docs API را با استفاده از یک درخواست HTTP یا با استفاده از فراخوانی روش در کتابخانه مشتری خاص زبان فراخوانی کنید. اینها به طور کلی معادل هستند.
Google Docs API یک پاسخ HTTP را برمی‌گرداند که عموماً شامل نتیجه فراخوانی درخواست است. هنگام استفاده از کتابخانه مشتری برای درخواست، پاسخ ها به روشی خاص زبان برگردانده می شوند.
روش های درخواست
Docs API از روش های زیر پشتیبانی می کند:
-
documents.create: یک سند Google Docs خالی ایجاد کنید. -
documents.get: یک نمونه کامل از سند مشخص شده را برگردانید. می‌توانید JSON برگشتی را برای استخراج محتوای سند، قالب‌بندی و سایر ویژگی‌ها تجزیه کنید. -
documents.batchUpdate: فهرستی از درخواست‌های ویرایش را برای اعمال اتمی روی سند ارسال کنید و فهرستی از نتایج را برگردانید.
روش های documents.get و documents.batchUpdate به یک documentId به عنوان پارامتر برای تعیین سند هدف نیاز دارند. متد documents.create نمونه ای از سند ایجاد شده را برمی گرداند که از آن می توانید documentId را بخوانید. برای اطلاعات بیشتر درباره documentId ، به شناسه سند مراجعه کنید.
به روز رسانی دسته ای
متد documents.batchUpdate فهرستی از اشیاء request را می گیرد که هر کدام یک درخواست را برای انجام مشخص می کنند. به عنوان مثال، یک پاراگراف را فرمت کنید و سپس یک تصویر درون خطی اضافه کنید. هر درخواست قبل از اعمال تأیید می شود و درخواست ها مطابق ترتیبی که در درخواست دسته ای ظاهر می شوند پردازش می شوند.
همه درخواست‌ها در به‌روزرسانی دسته‌ای به صورت اتمی اعمال می‌شوند. یعنی اگر هر درخواستی معتبر نباشد، کل به‌روزرسانی ناموفق است و هیچ یک از تغییرات (بالقوه وابسته) اعمال نمی‌شود.
برخی از روش های documents.batchUpdate پاسخ هایی را با اطلاعات درخواست های اعمال شده ارائه می دهند. این روش ها بدنه پاسخی را که حاوی لیستی از اشیاء response است برمی گرداند. سایر درخواست‌ها نیازی به بازگرداندن اطلاعات ندارند و یک پاسخ خالی ظاهر می‌شوند. اشیاء در لیست پاسخ، همان ترتیب فهرست درخواست مربوطه را اشغال می کنند.
یک الگوی محبوب برای ایجاد درخواست های دسته ای به این صورت است:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
برای جزئیات کامل در مورد نحوه دسته‌بندی تماس‌های Docs API و مستندات مرجع documents.batchUpdate برای انواع درخواست و پاسخ، به بهترین شیوه‌های درخواست دسته‌ای مراجعه کنید.
عملیات به روز رسانی دسته ای
انواع مختلفی از درخواست های به روز رسانی دسته ای وجود دارد. در اینجا به تفکیک انواع درخواست ها ، دسته بندی شده در دسته های مختلف آمده است.