با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
سرویس‌های پیشرفته در 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 استفاده کنید که سرویس پیشرفته عملکرد مورد نیاز شما را ارائه ندهد.
الزامات
قبل از اینکه بتوانید از یک سرویس پیشرفته استفاده کنید، باید شرایط زیر را رعایت کنید:
باید مطمئن شوید که API مربوط به سرویس پیشرفته در پروژه Cloud Platform (GCP) که اسکریپت شما استفاده می کند، فعال است.
اگر پروژه اسکریپت شما از یک پروژه پیش‌فرض GCP استفاده می‌کند که در تاریخ 8 آوریل 2019 یا بعد از آن ایجاد شده است، پس از فعال کردن سرویس پیشرفته و ذخیره پروژه اسکریپت، API به طور خودکار فعال می‌شود. اگر قبلاً این کار را نکرده‌اید، ممکن است از شما خواسته شود که با شرایط خدمات Google Cloud و Google APIs موافقت کنید.
برای استفاده از سرویس پیشرفته گوگل، این دستورالعمل ها را دنبال کنید:
پروژه Apps Script را باز کنید.
در سمت چپ، روی codeویرایشگر کلیک کنید.
در سمت چپ، در کنار خدمات ، روی افزودن addسرویس کلیک کنید.
یک سرویس پیشرفته Google را انتخاب کنید و روی افزودن کلیک کنید.
پس از فعال کردن یک سرویس پیشرفته، به صورت تکمیل خودکار در دسترس است.
نحوه تعیین امضای روش
سرویس‌های پیشرفته معمولاً از همان اشیاء، نام روش‌ها و پارامترهای APIهای عمومی مربوطه استفاده می‌کنند، اگرچه امضاهای روش برای استفاده در Apps Script ترجمه می‌شوند. عملکرد تکمیل خودکار ویرایشگر اسکریپت معمولاً اطلاعات کافی را برای شروع ارائه می دهد، اما قوانین زیر توضیح می دهد که چگونه Apps Script یک امضای متد را از یک API عمومی Google ایجاد می کند.
درخواست‌ها به APIهای Google می‌توانند انواع مختلفی از داده‌ها را بپذیرند، از جمله پارامترهای مسیر، پارامترهای جستجو، بدنه درخواست و/یا پیوست بارگذاری رسانه. برخی از سرویس های پیشرفته همچنین می توانند سرصفحه های درخواست HTTP خاص را بپذیرند (به عنوان مثال، سرویس پیشرفته تقویم ).
امضای متد مربوطه در Google Apps Script دارای آرگومان های زیر است:
بدنه درخواست (معمولا یک منبع)، به عنوان یک شی جاوا اسکریپت.
مسیر یا پارامترهای مورد نیاز، به عنوان آرگومان های جداگانه.
پارامترهای اختیاری، به عنوان یک شی جاوا اسکریپت نگاشت نام پارامترها به مقادیر.
هدرهای درخواست HTTP، به عنوان یک شی جاوا اسکریپت نگاشت نام سرصفحه به مقادیر سرصفحه.
اگر متد هیچ موردی در یک دسته بندی خاص نداشته باشد، آن قسمت از امضا حذف می شود.
استثناهای خاصی وجود دارد که باید از آنها آگاه بود:
برای روش هایی که آپلود رسانه را می پذیرند، پارامتر uploadType به طور خودکار تنظیم می شود.
روش‌هایی که در API Google نام‌گذاری deleteremove در Apps Script نامیده می‌شوند، زیرا delete یک کلمه رزرو شده در جاوا اسکریپت است.
اگر یک سرویس پیشرفته برای پذیرش هدرهای درخواست HTTP پیکربندی شده است، و شما یک شیء جاوا اسکریپت هدر درخواست تنظیم کرده اید، باید پارامترهای اختیاری شی جاوا اسکریپت را نیز تنظیم کنید (اگر از پارامترهای اختیاری استفاده نمی کنید، به یک شی خالی).
پشتیبانی از خدمات پیشرفته
سرویس‌های پیشرفته فقط بسته‌بندی‌های نازکی هستند که استفاده از APIهای Google را در Apps Script امکان‌پذیر می‌سازند. به این ترتیب، هر مشکلی که در هنگام استفاده از آنها با آن مواجه می‌شوید، معمولاً مربوط به API اصلی است، نه با خود Apps Script.
اگر هنگام استفاده از یک سرویس پیشرفته با مشکلی مواجه شدید، باید با استفاده از دستورالعمل‌های پشتیبانی API زیربنایی، آن را گزارش کنید. پیوندهای این دستورالعمل‌های پشتیبانی در هر راهنمای خدمات پیشرفته در بخش Apps Script Reference ارائه شده است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eApps Script's advanced services simplify connections to Google APIs, offering features like autocomplete and automatic authorization handling.\u003c/p\u003e\n"],["\u003cp\u003eChoose between advanced services or the \u003ccode\u003eUrlFetch\u003c/code\u003e method for API access, weighing the convenience of advanced services against the flexibility of \u003ccode\u003eUrlFetch\u003c/code\u003e for full API functionality.\u003c/p\u003e\n"],["\u003cp\u003eEnable advanced services in your script project and potentially the corresponding API in your Google Cloud Platform project for access.\u003c/p\u003e\n"],["\u003cp\u003eMethod signatures in Apps Script for advanced services are generally derived from the structure of corresponding public Google APIs.\u003c/p\u003e\n"],["\u003cp\u003eRefer to the support resources for the specific underlying API when facing issues with advanced services, as they act as wrappers for those APIs.\u003c/p\u003e\n"]]],[],null,["# Advanced Google services\n\nThe advanced services in Apps Script let experienced developers connect to\ncertain public Google APIs with less set-up than using their HTTP interfaces.\nAdvanced services are essentially thin wrappers around those Google APIs. They\nwork much like Apps Script's\n[built-in services](/apps-script/guides/services)---for example, they offer\nautocomplete, and Apps Script handles the\n[authorization flow](/apps-script/guides/services/authorization) automatically.\nHowever, you must [enable an advanced service](#enable_advanced_services) before\nyou can use it in a script.\n\nTo see which Google APIs are available as advanced services, look for the\n**Advanced Google Services** section in the\n[Reference](/apps-script/reference). If you want to use a Google API that\nisn't available as an advanced service, just connect to it like any other\n[external API](/apps-script/guides/services/external).\n\nAdvanced services or HTTP?\n--------------------------\n\nEach of the advanced Google services is associated with a public Google API.\nIn Apps Script, you can access these APIs via advanced services or by simply\nmaking the API requests directly using\n[`UrlFetch`](/apps-script/reference/url-fetch).\n\n**If you use the advanced service method** , Apps Script handles the\n[authorization flow](/apps-script/guides/services/authorization) and offers\nautocomplete support. However, you must\n[enable the advanced service](#enable_advanced_services) before you can use\nit. In addition, some advanced services only provide a subset of the\nfunctionality available in the API.\n\n**If you use the `UrlFetch` method to access the API directly** , you are\nessentially treating the Google API as an\n[external API](/apps-script/guides/services/external). With this method, all\naspects of the API can be used. However, it requires you to handle the API\nauthorization yourself. You must also construct any needed headers and parse\nthe API responses.\n\nIn general it's easiest to use an advanced service where possible and only\nuse the `UrlFetch` method when the advanced service doesn't provide the\nfunctionality you need.\n\nRequirements\n------------\n\nBefore you can use an advanced service, you must satisfy the following\nrequirements:\n\n1. You must [enable the advanced service](/apps-script/guides/services/advanced#enable_advanced_services) in your script project.\n2. You must make sure the API corresponding to the advanced service is enabled\n in the [Cloud Platform (GCP) project](/apps-script/guides/cloud-platform-projects)\n your script uses.\n\n If your script project uses a [default GCP project](/apps-script/guides/cloud-platform-projects#default_cloud_platform_projects)\n created on or after April 8, 2019, the API is enabled automatically\n after you enable the advanced service and save the script project. If you\n have not done so already, you may also be\n asked to agree to the [Google Cloud](https://cloud.google.com/terms/)\n and [Google APIs](/terms) Terms of Service as well.\n\n If your script project uses a\n [standard GCP project](/apps-script/guides/cloud-platform-projects#standard_cloud_platform_projects)\n or an older default GCP project,\n you must [enable the advanced service's corresponding API](/apps-script/guides/cloud-platform-projects#enabling_an_api_in_a_standard_gcp_project)\n in the GCP project manually. You must have edit access to the GCP project\n to make this change.\n\nSee [Cloud Platform projects](/apps-script/guides/cloud-platform-projects)\nfor more information.\n\nEnable advanced services\n------------------------\n\nTo use an advanced Google service, follow these instructions:\n\n1. Open the Apps Script project.\n2. At the left, click **Editor** code.\n3. At the left, next to **Services** , click **Add a service** add.\n4. Select an advanced Google service and click **Add**.\n\n| **Note:** If you're using a [standard GCP project](/apps-script/guides/cloud-platform-projects#standard_cloud_platform_projects) (or an older default GCP project that was created prior to April 8, 2019), you must also manually enable the API corresponding to the advanced service. Enable the API by doing the following:\n|\n| 1. Open the GCP project associated with your script in the [**Google Cloud console**](https://console.developers.google.com/apis/dashboard).\n| 2. At the top of the console, click into the search bar and type part of the name of the API (for example, \"Calendar\"), then click the name once you see it.\n| 3. On the next screen, click **Enable API**.\n| 4. Close the Google Cloud console and return to the script editor. Click **OK** in the dialog.\n\nAfter you enable an advanced service, it's available in autocomplete.\n\nHow method signatures are determined\n------------------------------------\n\nAdvanced services generally use the same objects, method names, and parameters\nas the corresponding public APIs, although method signatures are translated for\nuse in Apps Script. The script editor's\n[autocomplete function](/apps-script/guides/services#using_autocomplete)\nusually provides enough information to get started, but the rules below explain\nhow Apps Script generates a method signature from a public Google API.\n\nRequests to Google APIs can accept a variety of different types of data,\nincluding path parameters, query parameters, a request body, and/or a media\nupload attachment. Some advanced services can also accept specific HTTP request\nheaders (for example, the\n[Calendar advanced service](/apps-script/advanced/calendar)).\n\nThe corresponding method signature in Google Apps Script has the following\narguments:\n\n1. The request body (usually a resource), as a JavaScript object.\n2. Path or required parameters, as individual arguments.\n3. The media upload attachment, as a [`Blob`](/apps-script/reference/base/blob) argument.\n4. Optional parameters, as a JavaScript object mapping parameter names to values.\n5. HTTP request headers, as a JavaScript object mapping header names to header values.\n\nIf the method doesn't have any items in a given category, that part of the\nsignature is omitted.\n\nThere are some special exceptions to be aware of:\n\n- For methods that accept a media upload, the parameter `uploadType` is set automatically.\n- Methods named `delete` in the Google API are named `remove` in Apps Script, since `delete` is a reserved word in JavaScript.\n- If an advanced service is configured to accept HTTP request headers, and you set a request headers JavaScript object, then you must also set the optional parameters JavaScript object (to an empty object if you aren't using optional parameters).\n\nSupport for advanced services\n-----------------------------\n\nAdvanced services are just thin wrappers that enables the use of a Google\nAPIs within Apps Script. As such, any issue encountered while using them is\nusually an issue with the underlying API, not with Apps Script itself.\n\nIf you encounter a problem while using an advanced service, it should be\nreported using the support instructions for the underlying API. Links to these\nsupport instructions are provided in each advanced service guide in the\nApps Script [Reference](/apps-script/reference) section."]]
