معرفی

Google Docs API به شما امکان می دهد اسناد را ایجاد و تغییر دهید.

برنامه‌ها می‌توانند با Docs API ادغام شوند تا اسناد صیقلی را هم از داده‌های کاربر و هم از داده‌های ارائه‌شده توسط سیستم ایجاد کنند. API به شما اجازه می دهد:

  • فرآیندها را خودکار کنید
  • ایجاد اسناد به صورت انبوه
  • فاکتورها یا قراردادها را ایجاد کنید

نمای کلی API

منبع اسناد روش هایی را ارائه می دهد که شما برای فراخوانی Docs API استفاده می کنید.

روش های API

روش‌های زیر به شما امکان می‌دهند اسناد Google Docs را ایجاد، بخوانید و به‌روزرسانی کنید:

  • برای ایجاد سند از document.create استفاده کنید.
  • برای بازیابی محتوای یک سند مشخص شده از document.get استفاده کنید.
  • از document.batchUpdate برای اجرای اتمی مجموعه ای از به روز رسانی ها در یک سند مشخص استفاده کنید.

متدهای get و batchUpdate به یک documentId (به زیر مراجعه کنید) به عنوان پارامتری برای تعیین سند هدف نیاز دارند. متد create نمونه ای از سند ایجاد شده را برمی گرداند که از آن می توانید شناسه را بخوانید.

به روز رسانی دسته ای

متد batchUpdate لیستی از اشیاء درخواست را می گیرد و مطابق همان ترتیبی که در درخواست دسته ای ظاهر می شوند به روز رسانی می کند. به روز رسانی در به روز رسانی دسته ای به صورت اتمی اعمال می شود. یعنی اگر هر درخواستی معتبر نباشد، کل به‌روزرسانی ناموفق است و هیچ یک از تغییرات (بالقوه وابسته) اعمال نمی‌شود.

متد batchUpdate لیستی از اشیاء پاسخ را برمی گرداند. اشیاء در این لیست همان ترتیب فهرست درخواست مربوطه را اشغال می کنند.

به بهترین شیوه‌های درخواست دسته‌ای برای نحوه دسته‌بندی تماس‌های API و مستندات مرجع batchUpdate برای انواع درخواست و پاسخ مراجعه کنید.

شناسه سند

شناسه‌های سند به یک سند اشاره می‌کنند و می‌توان آن‌ها را از URL استخراج کرد:

https://docs.google.com/document/d/documentId/edit

documentId یک رشته منحصر به فرد حاوی حروف، اعداد و برخی کاراکترهای خاص است. عبارت منظم زیر را می توان برای استخراج شناسه سند از URL سندنگار Google استفاده کرد:

/document/d/([a-zA-Z0-9-_]+)

اگر با Google Drive API آشنا هستید، documentId با شناسه منبع File مطابقت دارد.

مکان های درون یک سند: نمایه ها

وقتی محتوای یک سند را به‌روزرسانی می‌کنید، هر به‌روزرسانی در یک مکان یا در محدوده‌ای از سند انجام می‌شود. این مکان‌ها و محدوده‌ها با استفاده از شاخص‌ها مشخص می‌شوند که نشان دهنده یک افست در یک بخش سند حاوی است. برای کسب اطلاعات بیشتر در مورد نمایه‌ها و نحوه استفاده از آنها، به ساختار راهنمای مفهوم سند Google Docs مراجعه کنید.

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

ایجاد و پر کردن یک سند جدید ساده است، زیرا هیچ محتوایی برای نگرانی وجود ندارد و هیچ شریکی وجود ندارد که بتواند وضعیت سند را تغییر دهد. از نظر مفهومی، این کار همانطور که در نمودار توالی زیر نشان داده شده است:

گردش کار برای ایجاد و پر کردن یک سند جدید.

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

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

این نمودار جریان‌های کاری را در نظر نمی‌گیرد که در آن به‌روزرسانی‌های همزمان توسط سایر همکاران در همان سند انجام می‌شود. برای بحث در مورد این موضوع به طرح همکاری مراجعه کنید.