این راهنما مفاهیمی مانند روشهای اصلی تشکیل دهنده Google Docs API، نحوه دسترسی به یک سند و گردش کار هنگام ایجاد یک سند را معرفی میکند.
روش های API
منبع documents
روش هایی را ارائه می دهد که شما برای فراخوانی Docs API استفاده می کنید. روشهای زیر به شما امکان میدهند اسناد Docs را ایجاد، بخوانید و بهروزرسانی کنید:
- برای ایجاد سند از روش
documents.create
استفاده کنید. - از روش
documents.get
برای بازیابی محتویات یک سند مشخص استفاده کنید. - از روش
documents.batchUpdate
برای اجرای اتمی مجموعه ای از به روز رسانی ها در یک سند مشخص استفاده کنید.
روش های documents.get
و documents.batchUpdate
به یک documentId
به عنوان پارامتر برای تعیین سند هدف نیاز دارند. متد documents.create
نمونه ای از سند ایجاد شده را برمی گرداند که از آن می توانید documentId
بخوانید. برای اطلاعات بیشتر درباره درخواستهای API Docs و روشهای پاسخ، به درخواستها و پاسخها مراجعه کنید.
شناسه سند
documentId
شناسه منحصربهفرد سند است و میتوان آن را از URL یک سند مشتق کرد. این یک رشته خاص است که شامل حروف، اعداد و برخی کاراکترهای خاص است. شناسههای سند پایدار هستند، حتی اگر نام سند تغییر کند.
https://docs.google.com/document/d/DOCUMENT_ID/edit
عبارت منظم زیر را می توان برای استخراج documentId
از URL سندنگار Google استفاده کرد:
/document/d/([a-zA-Z0-9-_]+)
اگر با Google Drive API آشنا هستید، documentId
با id
موجود در منبع files
مطابقت دارد.
اسناد را در Google Drive مدیریت کنید
فایلهای Docs در Google Drive، سرویس ذخیرهسازی مبتنی بر ابر ما ذخیره میشوند. در حالی که Docs API روشهای مستقل خود را دارد، اغلب لازم است از روشهای Google Drive API برای تعامل با فایلهای Docs کاربر نیز استفاده کنید. برای مثال، برای کپی کردن فایلهای Docs، از روش files.copy
Drive API استفاده کنید. برای اطلاعات بیشتر، کپی یک سند موجود را ببینید.
به طور پیش فرض، هنگام استفاده از Docs API یک سند جدید در پوشه اصلی کاربر در Drive ذخیره می شود. گزینه هایی برای ذخیره یک فایل در پوشه Drive وجود دارد. برای اطلاعات بیشتر، کار با پوشههای Google Drive را ببینید.
با فایل های Docs کار کنید
برای بازیابی یک سند از My Drive کاربر، اغلب لازم است ابتدا از روش Drive's 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، از روش Drive's files.export
با documentId
فایل برای صادر کردن و نوع صادرات MIME صحیح استفاده کنید. برای اطلاعات بیشتر، صادرات محتوای سند Google Workspace را ببینید.
روش های Get
and List
را با هم مقایسه کنید
جدول زیر تفاوتهای بین روشهای Drive و Docs و دادههایی را که با هرکدام برگردانده میشوند، توضیح میدهد:
اپراتور | توضیحات | استفاده |
---|---|---|
drive.files.get | فراداده یک فایل را با شناسه دریافت می کند. نمونه ای از منبع files را برمی گرداند. | متادیتا را برای یک فایل خاص دریافت کنید. |
drive.files.list | فایل های یک کاربر را دریافت می کند. لیستی از فایل ها را برمی گرداند. | زمانی که مطمئن نیستید کدام فایل را باید تغییر دهید، فهرستی از فایل های کاربر دریافت کنید. |
docs.documents.get | آخرین نسخه سند مشخص شده، شامل تمام قالببندیها و متن را دریافت میکند. نمونه ای از منبع documents را برمی گرداند. | سند را برای شناسه سند خاص دریافت کنید. |
گردش کار ایجاد سند
ایجاد و پر کردن یک سند جدید ساده است، زیرا هیچ محتوایی برای نگرانی وجود ندارد و هیچ شریکی وجود ندارد که بتواند وضعیت سند را تغییر دهد. از نظر مفهومی، این کار همانطور که در نمودار توالی زیر نشان داده شده است:
در شکل 1، کاربر در حال تعامل با منبع documents
دارای جریان اطلاعات زیر است:
- یک برنامه روش
documents.create
را در سرور وب فراخوانی می کند. - وب سرور یک پاسخ HTTP را ارسال می کند که حاوی نمونه ای از سند ایجاد شده به عنوان منبع
documents
است. - به صورت اختیاری، برنامه روش
documents.batchUpdate
را فراخوانی می کند تا مجموعه ای از درخواست های ویرایش را به صورت اتمی انجام دهد تا سند را با داده ها پر کند. - وب سرور یک پاسخ HTTP ارسال می کند. برخی از روشهای
documents.batchUpdate
یک بدنه پاسخ با اطلاعات درخواستهای اعمالشده ارائه میکنند، در حالی که برخی دیگر یک پاسخ خالی را نشان میدهند.
گردش کار به روز رسانی سند
به روز رسانی یک سند موجود پیچیده تر است. قبل از اینکه بتوانید تماسهای معنیداری برای بهروزرسانی یک سند برقرار کنید، باید وضعیت فعلی آن را بدانید: چه عناصری آن را تشکیل میدهند، چه محتوایی در آن عناصر وجود دارد و ترتیب عناصر درون سند. نمودار توالی زیر نشان می دهد که چگونه این کار می کند:
در شکل 2، کاربر در حال تعامل با منبع documents
دارای جریان اطلاعات زیر است:
- یک برنامه، متد
documents.get
در سرور وب فراخوانی میکند وdocumentId
فایل را برای یافتن میکند. - وب سرور یک پاسخ HTTP را ارسال می کند که حاوی نمونه ای از سند مشخص شده به عنوان منبع
documents
است. JSON برگشتی حاوی محتوای سند، قالببندی و سایر ویژگیها است. - برنامه JSON را تجزیه می کند تا کاربر بتواند تعیین کند چه محتوا یا قالبی را به روز کند.
- این برنامه روش
documents.batchUpdate
را فراخوانی می کند تا مجموعه ای از درخواست های ویرایش را به صورت اتمی انجام دهد تا سند را به روز کند. - وب سرور یک پاسخ HTTP ارسال می کند. برخی از روشهای
documents.batchUpdate
یک بدنه پاسخ با اطلاعات درخواستهای اعمالشده ارائه میکنند، در حالی که برخی دیگر یک پاسخ خالی را نشان میدهند.
این نمودار جریانهای کاری را در نظر نمیگیرد که در آن بهروزرسانیهای همزمان توسط سایر همکاران در همان سند انجام میشود. برای اطلاعات بیشتر، به بخش بهترین شیوه ها برنامه ریزی برای همکاری مراجعه کنید.
موضوعات مرتبط
- ساختار یک سند Google Docs
- درخواست ها و پاسخ ها
- قوانین و رفتار ویرایش ساختاری
- بهترین روش ها برای بهترین نتایج