این راهنما مفاهیمی مانند روشهای اصلی تشکیلدهندهی API گوگل داکس، نحوهی دسترسی به یک سند و گردش کار هنگام ایجاد یک سند را معرفی میکند.
روشهای API
منبع documents متدهایی را ارائه میدهد که شما برای فراخوانی API اسناد Docs از آنها استفاده میکنید. متدهای زیر به شما امکان ایجاد، خواندن و بهروزرسانی اسناد Docs را میدهند:
- برای ایجاد یک سند از متد
documents.createاستفاده کنید. - از متد
documents.getبرای بازیابی محتویات یک سند مشخص شده استفاده کنید. - از متد
documents.batchUpdateبرای انجام خودکار مجموعهای از بهروزرسانیها روی یک سند مشخص استفاده کنید.
متدهای documents.get و documents.batchUpdate برای مشخص کردن سند هدف، به یک documentId به عنوان پارامتر نیاز دارند. متد documents.create نمونهای از سند ایجاد شده را برمیگرداند که میتوانید documentId از آن بخوانید. برای اطلاعات بیشتر در مورد درخواستها و متدهای پاسخ API مربوط به Docs، به Requests and responses مراجعه کنید.
شناسه سند
شناسه documentId شناسه منحصر به فرد سند است و میتواند از آدرس اینترنتی (URL) سند استخراج شود. این یک رشته خاص است که شامل حروف، اعداد و برخی کاراکترهای خاص است. شناسههای سند حتی اگر نام سند تغییر کند، ثابت هستند.
https://docs.google.com/document/d/DOCUMENT_ID/edit
عبارت منظم زیر میتواند برای استخراج documentId از URL گوگل داکس استفاده شود:
/document/d/([a-zA-Z0-9-_]+)
اگر با API گوگل درایو آشنا باشید، documentId معادل id در منبع files است.
مدیریت اسناد در گوگل درایو
فایلهای Docs در گوگل درایو، سرویس ذخیرهسازی ابری ما، ذخیره میشوند. اگرچه Docs API متدهای مستقل خود را دارد، اما اغلب لازم است از متدهای Google Drive API نیز برای تعامل با فایلهای Docs کاربر استفاده شود. به عنوان مثال، برای کپی کردن فایلهای Docs، از متد files.copy در Drive API استفاده کنید. برای اطلاعات بیشتر، به بخش کپی کردن یک سند موجود مراجعه کنید.
به طور پیشفرض، هنگام استفاده از API اسناد، یک سند جدید در پوشه ریشه کاربر در Drive ذخیره میشود. گزینههایی برای ذخیره فایل در پوشه Drive وجود دارد. برای اطلاعات بیشتر، به بخش «کار با پوشههای Google Drive» مراجعه کنید.
کار با فایلهای Docs
برای بازیابی یک سند از My Drive کاربر، اغلب لازم است ابتدا از متد files.list درایو برای بازیابی شناسه یک فایل استفاده شود. فراخوانی این متد بدون هیچ پارامتری، لیستی از تمام فایلها و پوشهها، شامل شناسهها، را برای کاربر برمیگرداند.
نوع MIME یک سند، نوع داده و قالب آن را نشان میدهد. قالب نوع MIME برای Docs، application/vnd.google-apps.document است. برای فهرستی از انواع MIME، به انواع MIME پشتیبانیشده توسط Google Workspace و Google Drive مراجعه کنید.
برای جستجو بر اساس نوع MIME فقط برای فایلهای Docs در My Drive، فیلتر رشته پرس و جوی زیر را اضافه کنید:
q: mimeType = 'application/vnd.google-apps.document'
برای اطلاعات بیشتر در مورد فیلترهای رشته پرس و جو، به جستجوی فایلها و پوشهها مراجعه کنید.
زمانی که documentId پیدا کردید، از متد documents.get برای بازیابی یک نمونه کامل از سند مشخص شده استفاده کنید. برای اطلاعات بیشتر، به بخش درخواستها و پاسخها مراجعه کنید.
برای صادر کردن محتوای بایت سند Google Workspace، از متد files.export درایو به همراه documentId فایل مورد نظر برای صادر کردن و نوع MIME صحیح برای صادر کردن استفاده کنید. برای اطلاعات بیشتر، به بخش «صادر کردن محتوای سند Google Workspace» مراجعه کنید.
مقایسه متدهای Get و List
جدول زیر تفاوتهای بین متدهای Drive و Docs و دادههایی که با هر کدام برگردانده میشوند را شرح میدهد:
| اپراتور | توضیحات | کاربرد |
|---|---|---|
drive.files.get | متادیتای یک فایل را بر اساس شناسه (ID) دریافت میکند. نمونهای از منبع files را برمیگرداند. | دریافت متادیتای یک فایل خاص. |
drive.files.list | فایلهای کاربر را دریافت میکند. لیستی از فایلها را برمیگرداند. | وقتی مطمئن نیستید کدام فایل را باید تغییر دهید، فهرستی از فایلهای کاربر را دریافت کنید. |
docs.documents.get | آخرین نسخه از سند مشخص شده، شامل تمام قالببندی و متن را دریافت میکند. نمونهای از منبع documents را برمیگرداند. | سند مربوط به یک شناسه سند خاص را دریافت کنید. |
گردش کار ایجاد سند
ایجاد و پر کردن یک سند جدید ساده است، زیرا هیچ محتوای موجودی برای نگرانی وجود ندارد و هیچ همکاری وجود ندارد که بتواند وضعیت سند را تغییر دهد. از نظر مفهومی، این کار همانطور که در نمودار توالی زیر نشان داده شده است، انجام میشود:
در شکل ۱، کاربری که با منبع documents تعامل دارد، جریان اطلاعات زیر را دارد:
- یک برنامه، متد
documents.createرا روی یک وب سرور فراخوانی میکند. - وب سرور یک پاسخ HTTP ارسال میکند که شامل نمونهای از سند ایجاد شده به عنوان منبع
documentsاست. - به صورت اختیاری، برنامه متد
documents.batchUpdateرا فراخوانی میکند تا به صورت خودکار مجموعهای از درخواستهای ویرایش را برای پر کردن سند با دادهها انجام دهد. - سرور وب یک پاسخ HTTP ارسال میکند. برخی از متدهای
documents.batchUpdateیک بدنه پاسخ حاوی اطلاعات مربوط به درخواستهای اعمال شده ارائه میدهند، در حالی که برخی دیگر یک پاسخ خالی را نمایش میدهند.
گردش کار بهروزرسانی اسناد
بهروزرسانی یک سند موجود پیچیدهتر است. قبل از اینکه بتوانید فراخوانیهای معناداری برای بهروزرسانی یک سند انجام دهید، باید وضعیت فعلی آن را بدانید: چه عناصری آن را تشکیل میدهند، چه محتوایی در آن عناصر وجود دارد و ترتیب عناصر درون سند چیست. نمودار توالی زیر نحوهی کار این روش را نشان میدهد:
در شکل ۲، کاربری که با منبع documents تعامل دارد، جریان اطلاعات زیر را دارد:
- یک برنامه، متد
documents.getرا روی یک وب سرور فراخوانی میکند وdocumentIdفایل مورد نظر را برای یافتن در اختیار دارد. - سرور وب یک پاسخ HTTP ارسال میکند که شامل نمونهای از سند مشخص شده به عنوان منبع
documentsاست. JSON برگردانده شده شامل محتوای سند، قالببندی و سایر ویژگیها است. - این برنامه JSON را تجزیه میکند تا کاربر بتواند تعیین کند که چه محتوا یا قالبی را بهروزرسانی کند.
- برنامه، متد
documents.batchUpdateرا فراخوانی میکند تا به صورت خودکار مجموعهای از درخواستهای ویرایش را برای بهروزرسانی سند انجام دهد. - سرور وب یک پاسخ HTTP ارسال میکند. برخی از متدهای
documents.batchUpdateیک بدنه پاسخ حاوی اطلاعات مربوط به درخواستهای اعمال شده ارائه میدهند، در حالی که برخی دیگر یک پاسخ خالی را نمایش میدهند.
این نمودار، گردشهای کاری که در آنها بهروزرسانیهای همزمان توسط سایر همکاران در یک سند انجام میشود را در نظر نمیگیرد. برای اطلاعات بیشتر، به بخش «بهترین شیوهها» با عنوان «برنامهریزی برای همکاری» مراجعه کنید.
مباحث مرتبط
- ساختار یک سند گوگل داکس
- درخواستها و پاسخها
- قوانین و رفتار ویرایش ساختاری
- بهترین شیوهها برای بهترین نتایج