این راهنما روش‌های اولیه درخواست و پاسخ را که 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.get برای بازیابی اسناد منتشر شده استفاده کنید. پس از انتشار، اسناد عمومی از قالب URL متفاوتی استفاده می کنند. تلاش برای استفاده از documentId جدید URL با روش documents.get یک پاسخ کد وضعیت HTTP 404 را برمی‌گرداند. هیچ روشی برای بازیابی documentId اصلی از URL منتشر شده وجود ندارد. برای حل این مشکل، می‌توانید از Drive API برای کپی کردن سند منتشر شده در یک سند مشترک استفاده کنید و به جای آن به این فایل دسترسی پیدا کنید. برای اطلاعات بیشتر، به عمومی کردن Google Docs، Sheets، Slides & Forms مراجعه کنید.
به روز رسانی دسته ای
متد documents.batchUpdate فهرستی از اشیاء request را می گیرد که هر کدام یک درخواست را برای انجام مشخص می کنند. به عنوان مثال، یک پاراگراف را فرمت کنید و سپس یک تصویر درون خطی اضافه کنید. هر درخواست قبل از اعمال تأیید می شود و درخواست ها مطابق ترتیبی که در درخواست دسته ای ظاهر می شوند پردازش می شوند.
همه درخواست‌ها در به‌روزرسانی دسته‌ای به صورت اتمی اعمال می‌شوند. یعنی اگر هر درخواستی معتبر نباشد، کل به‌روزرسانی ناموفق است و هیچ یک از تغییرات (بالقوه وابسته) اعمال نمی‌شود.
برخی از روش های documents.batchUpdate پاسخ هایی را با اطلاعات درخواست های اعمال شده ارائه می دهند. این روش ها بدنه پاسخی را که حاوی لیستی از اشیاء response است برمی گرداند. سایر درخواست‌ها نیازی به بازگرداندن اطلاعات ندارند و یک پاسخ خالی ظاهر می‌شوند. اشیاء در لیست پاسخ، همان ترتیب فهرست درخواست مربوطه را اشغال می کنند.
یک الگوی محبوب برای ایجاد درخواست های دسته ای به این صورت است:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
برای جزئیات کامل در مورد نحوه دسته‌بندی تماس‌های Docs API و مستندات مرجع documents.batchUpdate برای انواع درخواست و پاسخ، به بهترین شیوه‌های درخواست دسته‌ای مراجعه کنید.
عملیات به روز رسانی دسته ای
انواع مختلفی از درخواست های به روز رسانی دسته ای وجود دارد. در اینجا به تفکیک انواع درخواست ها ، دسته بندی شده در دسته های مختلف آمده است.