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