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

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

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

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

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

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

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

1. پروژه Apps Script را باز کنید.
2. در سمت چپ، روی code ویرایشگر کلیک کنید.
3. در سمت چپ، کنار سرویس‌ها ، روی add سرویس کلیک کنید.
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 خاصی را بپذیرند (به عنوان مثال، سرویس پیشرفته تقویم ).

امضای متد مربوطه در Google 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 را مدیریت کنید.

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

مقایسه کد

نمونه‌های کد، تفاوت پیچیدگی بین ایجاد یک رویداد تقویم با استفاده از سرویس پیشرفته در مقابل استفاده از 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);

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

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

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

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