خدمات پیشرفته گوگل

سرویس‌های پیشرفته در Apps Script به توسعه‌دهندگان باتجربه این امکان را می‌دهد که با تنظیمات کمتری نسبت به استفاده از رابط‌های HTTP خود، به برخی از APIهای عمومی Google متصل شوند. سرویس‌های پیشرفته اساساً پوشش‌های نازکی در اطراف آن APIهای Google هستند. آنها بسیار شبیه به سرویس های داخلی Apps Script کار می کنند - برای مثال، آنها تکمیل خودکار را ارائه می دهند، و Apps Script به طور خودکار جریان مجوز را کنترل می کند. با این حال، قبل از اینکه بتوانید از آن در یک اسکریپت استفاده کنید، باید یک سرویس پیشرفته را فعال کنید .

برای مشاهده اینکه کدام APIهای Google به عنوان سرویس های پیشرفته در دسترس هستند، بخش خدمات پیشرفته Google را در مرجع جستجو کنید. اگر می‌خواهید از Google API استفاده کنید که به عنوان یک سرویس پیشرفته در دسترس نیست، کافی است مانند هر API خارجی دیگری به آن متصل شوید.

خدمات پیشرفته یا HTTP؟

هر یک از خدمات پیشرفته Google با یک API عمومی Google مرتبط است. در Apps Script، می‌توانید از طریق سرویس‌های پیشرفته یا با ایجاد مستقیم درخواست‌های API با استفاده از UrlFetch به این APIها دسترسی داشته باشید.

اگر از روش سرویس پیشرفته استفاده می‌کنید ، Apps Script جریان مجوز را مدیریت می‌کند و پشتیبانی تکمیل خودکار را ارائه می‌دهد. با این حال، قبل از استفاده از سرویس پیشرفته، باید آن را فعال کنید . علاوه بر این، برخی از خدمات پیشرفته تنها زیر مجموعه ای از عملکردهای موجود در API را ارائه می دهند.

اگر از روش UrlFetch برای دسترسی مستقیم به API استفاده می کنید ، اساساً Google API را به عنوان یک API خارجی در نظر می گیرید. با این روش می توان از تمام جنبه های API استفاده کرد. با این حال، شما باید مجوز API را خودتان مدیریت کنید. شما همچنین باید هر هدر مورد نیاز را بسازید و پاسخ های API را تجزیه کنید.

به طور کلی، در صورت امکان، استفاده از یک سرویس پیشرفته آسان‌تر است و تنها زمانی از روش UrlFetch استفاده کنید که سرویس پیشرفته عملکرد مورد نیاز شما را ارائه ندهد.

الزامات

قبل از اینکه بتوانید از یک سرویس پیشرفته استفاده کنید، باید شرایط زیر را رعایت کنید:

  1. شما باید سرویس پیشرفته را در پروژه اسکریپت خود فعال کنید .

  2. باید مطمئن شوید که API مربوط به سرویس پیشرفته در پروژه Cloud Platform (GCP) که اسکریپت شما استفاده می کند، فعال است.

    اگر پروژه اسکریپت شما از یک پروژه پیش‌فرض GCP استفاده می‌کند که در تاریخ 8 آوریل 2019 یا بعد از آن ایجاد شده است، پس از فعال کردن سرویس پیشرفته و ذخیره پروژه اسکریپت، API به طور خودکار فعال می‌شود. اگر قبلاً این کار را نکرده‌اید، ممکن است از شما خواسته شود که با شرایط خدمات Google Cloud و Google APIs موافقت کنید.

    اگر پروژه اسکریپت شما از یک پروژه استاندارد GCP یا یک پروژه GCP پیش فرض قدیمی استفاده می کند، باید API مربوط به سرویس پیشرفته را در پروژه GCP به صورت دستی فعال کنید . برای انجام این تغییر باید به پروژه GCP دسترسی ویرایش داشته باشید.

برای اطلاعات بیشتر به پروژه های Cloud Platform مراجعه کنید.

خدمات پیشرفته را فعال کنید

برای استفاده از سرویس پیشرفته گوگل، این دستورالعمل ها را دنبال کنید:

  1. پروژه Apps Script را باز کنید.
  2. در سمت چپ، روی ویرایشگر کلیک کنید.
  3. در سمت چپ، در کنار خدمات ، روی افزودن سرویس کلیک کنید.
  4. یک سرویس پیشرفته Google را انتخاب کنید و روی افزودن کلیک کنید.

پس از فعال کردن یک سرویس پیشرفته، به صورت تکمیل خودکار در دسترس است.

نحوه تعیین امضای روش

سرویس‌های پیشرفته معمولاً از همان اشیاء، نام روش‌ها و پارامترهای APIهای عمومی مربوطه استفاده می‌کنند، اگرچه امضاهای روش برای استفاده در Apps Script ترجمه می‌شوند. عملکرد تکمیل خودکار ویرایشگر اسکریپت معمولاً اطلاعات کافی را برای شروع ارائه می دهد، اما قوانین زیر توضیح می دهد که چگونه Apps Script یک امضای متد را از یک API عمومی Google ایجاد می کند.

درخواست‌ها به APIهای Google می‌توانند انواع مختلفی از داده‌ها را بپذیرند، از جمله پارامترهای مسیر، پارامترهای جستجو، بدنه درخواست و/یا پیوست بارگذاری رسانه. برخی از سرویس های پیشرفته همچنین می توانند سرصفحه های درخواست HTTP خاص را بپذیرند (به عنوان مثال، سرویس پیشرفته تقویم ).

امضای متد مربوطه در Google Apps Script دارای آرگومان های زیر است:

  1. بدنه درخواست (معمولا یک منبع)، به عنوان یک شی جاوا اسکریپت.
  2. مسیر یا پارامترهای مورد نیاز، به عنوان آرگومان های جداگانه.
  3. پیوست بارگذاری رسانه، به عنوان آرگومان Blob .
  4. پارامترهای اختیاری، به عنوان یک شی جاوا اسکریپت نگاشت نام پارامترها به مقادیر.
  5. هدرهای درخواست HTTP، به عنوان یک شی جاوا اسکریپت نگاشت نام سرصفحه به مقادیر سرصفحه.

اگر متد هیچ موردی در یک دسته بندی خاص نداشته باشد، آن قسمت از امضا حذف می شود.

استثناهای خاصی وجود دارد که باید از آنها آگاه بود:

  • برای روش هایی که آپلود رسانه را می پذیرند، پارامتر uploadType به طور خودکار تنظیم می شود.
  • روش‌هایی delete در API Google نام‌گذاری شده‌اند remove در Apps Script نامیده می‌شوند، زیرا delete یک کلمه رزرو شده در جاوا اسکریپت است.
  • اگر یک سرویس پیشرفته برای پذیرش هدرهای درخواست HTTP پیکربندی شده است، و شما یک شیء جاوا اسکریپت هدر درخواست تنظیم کرده اید، باید پارامترهای اختیاری شی جاوا اسکریپت را نیز تنظیم کنید (اگر از پارامترهای اختیاری استفاده نمی کنید، به یک شی خالی).

پشتیبانی از خدمات پیشرفته

سرویس‌های پیشرفته فقط بسته‌بندی‌های نازکی هستند که استفاده از APIهای Google را در Apps Script امکان‌پذیر می‌سازند. به این ترتیب، هر مشکلی که در هنگام استفاده از آنها با آن مواجه می‌شوید، معمولاً مربوط به API اصلی است، نه با خود Apps Script.

اگر هنگام استفاده از یک سرویس پیشرفته با مشکلی مواجه شدید، باید با استفاده از دستورالعمل‌های پشتیبانی API زیربنایی، آن را گزارش کنید. پیوندهای این دستورالعمل‌های پشتیبانی در هر راهنمای خدمات پیشرفته در بخش Apps Script Reference ارائه شده است.