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