رابط برنامهنویسی کاربردی (API) اسلایدهای گوگل به شما امکان میدهد ارائههای اسلایدهای گوگل را ایجاد و اصلاح کنید.
برنامهها میتوانند با API اسلایدهای گوگل ادغام شوند تا به طور خودکار از دادههای ارائه شده توسط کاربر و سیستم، اسلایدهای زیبایی ایجاد کنند. به عنوان مثال، میتوانید از اطلاعات مشتری از یک پایگاه داده استفاده کنید و آنها را با قالبهای از پیش طراحی شده و گزینههای پیکربندی انتخاب شده ترکیب کنید تا ارائههای نهایی را در کسری از زمان لازم برای ایجاد دستی آنها ایجاد کنید.
نمای کلی API
مجموعه ارائهها (presentations) متدهایی را ارائه میدهد که به شما امکان میدهند عناصر درون ارائه را دریافت و بهروزرسانی کنید.
احتمالاً بیشتر کار شما با API اسلایدها، ایجاد و بهروزرسانی ارائهها خواهد بود. شما این کار را با استفاده از متد batchUpdate انجام خواهید داد؛ این متد لیستی از اشیاء Request را دریافت میکند که به شما امکان میدهد کارهایی مانند موارد زیر را انجام دهید:
- ایجاد اسلایدها
- عناصری مانند شکلها یا جداول را به اسلایدها اضافه کنید
- درج، تغییر و حذف متن
- اعمال تبدیلها به عناصر
- تغییر ترتیب اسلایدها
برای جزئیات بیشتر به بخش بهروزرسانیهای دستهای مراجعه کنید. برای مشاهدهی یک مثال ساده و کامل از نحوهی استفاده از API، به راهنماهای شروع به کار مراجعه کنید.
ساختار یک ارائه
یک ارائه در رابط برنامهنویسی کاربردی اسلایدها (Slides API) از صفحاتی تشکیل شده است که شامل عناصر صفحه هستند.
شناسه یک ارائه را میتوان از URL استخراج کرد:
https://docs.google.com/presentation/d/presentationId/edit
شناسه ارائه رشتهای است که شامل حروف، اعداد و برخی کاراکترهای خاص است. عبارت منظم زیر میتواند برای استخراج شناسه ارائه از URL گوگل شیت استفاده شود:
/presentation/d/([a-zA-Z0-9-_]+)
اگر با رابط برنامهنویسی کاربردی درایو (Drive API) آشنا باشید، presentationId معادل شناسه (ID) منبع فایل (File ) است.
صفحات و عناصر صفحه توسط شناسههای شیء شناسایی میشوند.
صفحات
اسلایدهای گوگل انواع صفحات زیر را دارد:
| کارشناسی ارشد | اسلاید مسترها، سبکهای متن، پسزمینه و عناصر صفحه پیشفرض را که در تمام اسلایدهایی که از این اسلاید مستر استفاده میکنند، ظاهر میشوند، تعریف میکنند. عناصر صفحهای که باید در تمام اسلایدها ظاهر شوند، باید به اسلاید مستر اضافه شوند. اکثر ارائهها یک اسلاید مستر دارند، اما برخی ممکن است چندین اسلاید مستر داشته باشند یا اصلاً نداشته باشند. |
| طرحبندیها | طرحبندیها به عنوان الگویی برای نحوه چیدمان عناصر صفحه به طور پیشفرض در اسلایدها با استفاده از یک طرحبندی عمل میکنند. هر طرحبندی با یک طرح اصلی مرتبط است. |
| اسلایدها | این صفحات شامل محتوایی هستند که شما به مخاطبان خود ارائه میدهید. اکثر اسلایدها بر اساس یک صفحه اصلی (master) و یک طرحبندی (layout) هستند. میتوانید هنگام ایجاد هر اسلاید، طرحبندی مورد نظر خود را برای آن اسلاید مشخص کنید. |
| یادداشتها | این صفحات حاوی محتوای مربوط به جزوات ارائه، از جمله شکلی که حاوی یادداشتهای گوینده اسلاید است، میباشند. هر اسلاید دارای یک صفحه یادداشت مربوطه است. فقط متن موجود در شکل یادداشتهای گوینده را میتوان با رابط برنامهنویسی کاربردی اسلایدها تغییر داد. |
| یادداشتهای استادان | یادداشتهای اصلی، سبکهای متن پیشفرض و عناصر صفحه را برای همه صفحات یادداشت تعریف میکنند. یادداشتهای اصلی در API اسلایدها فقط قابل خواندن هستند. |
عناصر صفحه
عناصر صفحه، اجزای بصری هستند که در صفحات قرار میگیرند. این API انواع مختلفی از عناصر صفحه را ارائه میدهد:
| گروه | مجموعهای از عناصر صفحه که به عنوان یک واحد مجزا در نظر گرفته میشوند. آنها را میتوان با هم جابجا، مقیاسبندی و چرخاند. |
| شکل | یک شیء بصری ساده، مانند مستطیل، بیضی و کادرهای متنی. شکلها میتوانند حاوی متن باشند، بنابراین رایجترین عناصر صفحه برای ساخت اسلایدها هستند. |
| تصویر | گرافیکی که به اسلایدها وارد شده است. |
| ویدئو | ویدیویی که به اسلایدها وارد شده است. |
| خط | یک خط، منحنی یا رابط بصری. |
| میز | شبکهای از محتوا. |
| وردآرت | یک عنصر متنی بصری که بیشتر شبیه یک شکل رفتار میکند. |
| چارتهای ورقی | نموداری که از Google Sheets به اسلایدها وارد شده است. |
بهروزرسانیهای دستهای
متد batchUpdate به شما امکان میدهد جنبههای زیادی از یک ارائه را بهروزرسانی کنید. تغییرات در یک دسته گروهبندی میشوند، به طوری که اگر یک درخواست با شکست مواجه شود، هیچ یک از تغییرات دیگر (که به طور بالقوه وابسته هستند) نوشته نمیشوند.
متد batchUpdate با گرفتن یک یا چند شیء Request کار میکند که هر کدام نوع درخواستی را برای اجرا مشخص میکنند. انواع مختلفی از درخواستها وجود دارد. در اینجا به تفکیک انواع درخواستها، که در دستههای مختلف گروهبندی شدهاند، آمده است.
متد batchUpdate یک بدنه پاسخ برمیگرداند که شامل یک پاسخ برای هر درخواست است. هر پاسخ، اندیس مشابه درخواست مربوطه را اشغال میکند؛ برای درخواستهایی که پاسخ قابل استفادهای ندارند، پاسخ در آن اندیس خالی خواهد بود. درخواستهای مختلف Create معمولاً دارای پاسخ هستند، به طوری که شما شناسه شیء تازه اضافه شده را میدانید.
کار با شناسههای اشیاء
یک ارائه در رابط برنامهنویسی کاربردی اسلایدها (Slides API) از صفحات و عناصر صفحه تشکیل شده است. این اشیاء شامل یک رشته شناسه شیء هستند که در یک ارائه منحصر به فرد است.
تعیین شناسههای شیء در هنگام ایجاد
هنگام ایجاد صفحات یا عناصر صفحه با استفاده از متد batchUpdate ، میتوانید به صورت اختیاری یک شناسه شیء برای شیء جدید مشخص کنید. این به شما امکان میدهد یک شیء ایجاد کنید و آن را در همان درخواست batchUpdate تغییر دهید، که تعداد فراخوانیها به API اسلایدها را به حداقل میرساند و ...
استفاده از سهمیه
در بیشتر موارد توصیه میکنیم یک شناسه شیء تصادفی ایجاد کنید. برای مثال، اگر از جاوا استفاده میکنید، java.util.UUID.randomUUID().toString() باید به خوبی کار کند.
وقتی برنامه شما میخواهد اشیاء را برای مدت زمان طولانیتری ردیابی کند، به شناسه شیء تکیه نکنید، زیرا ممکن است تغییر کند. برای جزئیات بیشتر به بخش زیر مراجعه کنید.
پیگیری اشیاء بدون استفاده از شناسه شیء
وقتی یک درخواست API اسلایدها ارسال میکنید، شناسه شیء معمولاً حفظ میشود. (هرگونه استثنا در مستندات مرجع روش ذکر شده است.) تهیه یک کپی از کل ارائه با Drive API نیز شناسههای شیء را حفظ میکند.
با این حال، شما نمیتوانید به تغییر شناسه شیء پس از تغییر یک ارائه در رابط کاربری اسلایدها (Slides UI) اعتماد کنید. به عنوان مثال، اگر کسی از رابط کاربری اسلایدها برای کپی کردن و چسباندن یک عنصر صفحه استفاده کند و سپس عنصر اصلی را حذف کند، عنصر صفحه اکنون یک شناسه منحصر به فرد جدید خواهد داشت و شناسهای که قبلاً از طریق API ارائه دادهاید از بین خواهد رفت. در نتیجه، توصیه نمیکنیم شناسههای شیء را در فضای ذخیرهسازی برنامه خود ذخیره کنید. در عوض، باید اشیاء موجود در ارائه را با استفاده از محتوای متن یا متن جایگزین آن پیدا کنید.
ارائههای تازه ایجاد شده معمولاً از مجموعهای ثابت از شناسهها برای اسلایدها، مسترها و کادرهای متنی پیشفرض استفاده میکنند. این شناسهها با گذشت زمان ممکن است تغییر کنند، بنابراین توصیه نمیکنیم که به این ویژگی تکیه کنید. در عوض، عناصری را که میخواهید تغییر دهید با استفاده از شیء ارائهای که توسط فراخوانیهای create() یا get() برگردانده میشود، پیدا کنید.