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

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

فعال کردن سرویس‌های پیشرفته

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

مرحله ۱: فعال کردن سرویس پیشرفته

یک سرویس پیشرفته را با استفاده از ویرایشگر Apps Script یا با ویرایش مانیفست فعال کنید.

روش الف: استفاده از ویرایشگر

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

روش ب: استفاده از مانیفست

سرویس‌های پیشرفته را با ویرایش فایل مانیفست فعال کنید. برای مثال، برای فعال کردن سرویس پیشرفته گوگل درایو، فیلد enabledAdvancedServices را به شیء dependencies اضافه کنید:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

مرحله ۲: فعال کردن API گوگل کلود (فقط پروژه‌های استاندارد گوگل کلود)

اگر از یک پروژه پیش‌فرض Google Cloud (که به طور خودکار توسط Apps Script ایجاد شده است) استفاده می‌کنید، از این مرحله صرف نظر کنید. API هنگام اضافه کردن سرویس در مرحله 1 به طور خودکار فعال می‌شود.

اگر از یک پروژه استاندارد گوگل کلود استفاده می‌کنید، API مربوط به سرویس پیشرفته را به صورت دستی فعال کنید. برای فعال کردن دستی API:

1. پروژه ابری مرتبط با اسکریپت خود را در کنسول **گوگل کلود** باز کنید.

2. در بالای کنسول، روی نوار جستجو کلیک کنید و بخشی از نام API (مثلاً «تقویم») را تایپ کنید، سپس وقتی نام را دیدید، روی آن کلیک کنید.

3. روی فعال کردن API کلیک کنید.

4. کنسول گوگل کلود را ببندید و به ویرایشگر اسکریپت برگردید.

نحوه تعیین امضاهای متد

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

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

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

1. بدنه درخواست (معمولاً یک منبع)، به عنوان یک شیء جاوا اسکریپت.
2. مسیر یا پارامترهای مورد نیاز، به عنوان آرگومان‌های جداگانه. اگر متد به چندین پارامتر مسیر نیاز داشته باشد، آنها به ترتیبی که در URL نقطه پایانی API فهرست شده‌اند، ظاهر می‌شوند.
3. پیوست آپلود رسانه، به عنوان آرگومان Blob .
4. پارامترهای اختیاری (معمولاً پارامترهای پرس و جو)، به عنوان یک شیء جاوا اسکریپت که نام پارامترها را به مقادیر نگاشت می‌کند.
5. هدرهای درخواست HTTP، به عنوان یک شیء جاوا اسکریپت که نام‌های هدر را به مقادیر هدر نگاشت می‌کند.

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

از این استثنائات آگاه باشید:

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

مثال: تقویم.رویدادها.درج

برای ایجاد یک رویداد تقویم :

مستندات API تقویم گوگل، ساختار درخواست HTTP مربوطه را نشان می‌دهد:

• فعل HTTP : POST
• آدرس اینترنتی درخواست : https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

• بدنه درخواست : یک منبع رویداد .

• پارامترهای پرس و جو : sendUpdates ، supportsAttachments و غیره

در Apps Script، امضای متد با مرتب‌سازی مجدد این ورودی‌ها تعیین می‌شود:

1. بدنه : منبع رویداد (شیء جاوا اسکریپت).
2. مسیر : calendarId (رشته).
3. پارامترهای اختیاری : پارامترهای پرس و جو (شیء جاوا اسکریپت).

فراخوانی متد حاصل به این شکل خواهد بود:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

سرویس‌های پیشرفته یا HTTP؟

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

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

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

جدول زیر این دو روش را با هم مقایسه می‌کند:

ویژگی	خدمات پیشرفته	دریافت آدرس اینترنتی (HTTP)
مجوز	به صورت خودکار مدیریت می‌شود	جابجایی دستی مورد نیاز است
تکمیل خودکار	موجود است	موجود نیست
دامنه عملکرد	ممکن است زیرمجموعه‌ای از API باشد	دسترسی کامل به تمام ویژگی‌های API
پیچیدگی	آسان‌تر	پیچیده‌تر (نیازمند ساخت هدرها و تجزیه پاسخ‌ها)

مقایسه کد

نمونه‌های کد، تفاوت پیچیدگی بین ایجاد یک رویداد تقویم با استفاده از سرویس پیشرفته در مقابل استفاده از UrlFetchApp را نشان می‌دهند.

خدمات پیشرفته:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

دریافت آدرس اینترنتی (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

برای متد UrlFetchApp ، به صورت دستی محدوده‌های OAuth مورد نیاز را در فایل manifest اسکریپت مشخص کنید.

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

پشتیبانی از سرویس‌های پیشرفته

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

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