سند

این راهنما مفاهیمی مانند روش‌های اصلی تشکیل دهنده 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. گردش کار برای ایجاد و پر کردن یک سند جدید.

در شکل 1، کاربر در حال تعامل با منبع documents دارای جریان اطلاعات زیر است:

  1. یک برنامه روش documents.create را در سرور وب فراخوانی می کند.
  2. وب سرور یک پاسخ HTTP را ارسال می کند که حاوی نمونه ای از سند ایجاد شده به عنوان منبع documents است.
  3. به صورت اختیاری، برنامه روش documents.batchUpdate را فراخوانی می کند تا مجموعه ای از درخواست های ویرایش را به صورت اتمی انجام دهد تا سند را با داده ها پر کند.
  4. وب سرور یک پاسخ HTTP ارسال می کند. برخی از روش‌های documents.batchUpdate یک بدنه پاسخ با اطلاعات درخواست‌های اعمال‌شده ارائه می‌کنند، در حالی که برخی دیگر یک پاسخ خالی را نشان می‌دهند.

گردش کار به روز رسانی سند

به روز رسانی یک سند موجود پیچیده تر است. قبل از اینکه بتوانید تماس‌های معنی‌داری برای به‌روزرسانی یک سند برقرار کنید، باید وضعیت فعلی آن را بدانید: چه عناصری آن را تشکیل می‌دهند، چه محتوایی در آن عناصر وجود دارد و ترتیب عناصر درون سند. نمودار توالی زیر نشان می دهد که چگونه این کار می کند:

گردش کار برای به روز رسانی یک سند.
شکل 2. گردش کار برای به روز رسانی یک سند.

در شکل 2، کاربر در حال تعامل با منبع documents دارای جریان اطلاعات زیر است:

  1. یک برنامه، متد documents.get در سرور وب فراخوانی می‌کند و documentId فایل را برای یافتن می‌کند.
  2. وب سرور یک پاسخ HTTP را ارسال می کند که حاوی نمونه ای از سند مشخص شده به عنوان منبع documents است. JSON برگشتی حاوی محتوای سند، قالب‌بندی و سایر ویژگی‌ها است.
  3. برنامه JSON را تجزیه می کند تا کاربر بتواند تعیین کند چه محتوا یا قالبی را به روز کند.
  4. این برنامه روش documents.batchUpdate را فراخوانی می کند تا مجموعه ای از درخواست های ویرایش را به صورت اتمی انجام دهد تا سند را به روز کند.
  5. وب سرور یک پاسخ HTTP ارسال می کند. برخی از روش‌های documents.batchUpdate یک بدنه پاسخ با اطلاعات درخواست‌های اعمال‌شده ارائه می‌کنند، در حالی که برخی دیگر یک پاسخ خالی را نشان می‌دهند.

این نمودار جریان‌های کاری را در نظر نمی‌گیرد که در آن به‌روزرسانی‌های همزمان توسط سایر همکاران در همان سند انجام می‌شود. برای اطلاعات بیشتر، به بخش بهترین شیوه ها برنامه ریزی برای همکاری مراجعه کنید.