تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح الخدمات المتقدّمة في "برمجة التطبيقات" للمطوّرين المتمرّسين إمكانية الربط ببعض واجهات Google API العامة من خلال إعدادات أقلّ من استخدام واجهات HTTP.
الخدمات المتقدّمة هي في الأساس أغلفة بسيطة حول واجهات Google APIs. وتعمل هذه الإضافات بشكل مشابه للخدمات المضمّنة في "برمجة تطبيقات Google"، فهي توفّر مثلاً ميزة الإكمال التلقائي، وتتولّى "برمجة تطبيقات Google" عملية منح الأذونات تلقائيًا.
ومع ذلك، يجب تفعيل إحدى الخدمات المتقدّمة قبل أن تتمكّن من استخدامها في نص برمجي.
للاطّلاع على واجهات Google API المتاحة كخدمات متقدّمة، ابحث عن قسم
خدمات Google المتقدّمة في
المراجع. إذا كنت تريد استخدام إحدى واجهات Google API غير المتاحة كخدمة متقدّمة، ما عليك سوى الربط بها كما تفعل مع أي واجهة برمجة تطبيقات خارجية أخرى.
الخدمات المتقدّمة أو HTTP؟
ترتبط كل خدمة من خدمات Google المتقدّمة بواجهة برمجة تطبيقات عامة من Google.
في "برمجة التطبيقات"، يمكنك الوصول إلى واجهات برمجة التطبيقات هذه من خلال الخدمات المتقدّمة أو ببساطة عن طريق تقديم طلبات واجهة برمجة التطبيقات مباشرةً باستخدام UrlFetch.
في حال استخدام طريقة الخدمة المتقدّمة، تتولّى "برمجة التطبيقات" عملية
التفويض وتوفّر ميزة
الإكمال التلقائي. ومع ذلك، يجب
تفعيل الخدمة المتقدّمة قبل أن تتمكّن من استخدامها. بالإضافة إلى ذلك، لا توفّر بعض الخدمات المتقدّمة سوى مجموعة فرعية من الوظائف المتاحة في واجهة برمجة التطبيقات.
في حال استخدام طريقة UrlFetch للوصول إلى واجهة برمجة التطبيقات مباشرةً، ستتعامل مع واجهة Google API على أنّها واجهة برمجة تطبيقات خارجية. باستخدام هذه الطريقة، يمكن الاستفادة من جميع جوانب واجهة برمجة التطبيقات. ومع ذلك، يتطلّب ذلك أن تتولّى بنفسك عملية تفويض الوصول إلى واجهة برمجة التطبيقات. يجب أيضًا إنشاء أي عناوين مطلوبة وتحليل الردود من واجهة برمجة التطبيقات.
بشكل عام، من الأسهل استخدام خدمة متقدّمة حيثما أمكن ذلك، ولا تستخدم طريقة UrlFetch إلا عندما لا توفّر الخدمة المتقدّمة الوظيفة التي تحتاج إليها.
المتطلبات
قبل استخدام خدمة متقدّمة، يجب استيفاء المتطلبات التالية:
يجب التأكّد من تفعيل واجهة برمجة التطبيقات المتوافقة مع الخدمة المتقدّمة
في مشروع Cloud Platform (GCP)
الذي يستخدمه النص البرمجي.
إذا كان مشروع النص البرمجي يستخدم مشروع GCP تلقائيًا تم إنشاؤه في 8 أبريل 2019 أو بعده، يتم تفعيل واجهة برمجة التطبيقات تلقائيًا بعد تفعيل الخدمة المتقدّمة وحفظ مشروع النص البرمجي. إذا لم تكن قد وافقت على بنود خدمة Google Cloud وGoogle APIs، قد يُطلب منك الموافقة عليها أيضًا.
لاستخدام إحدى خدمات Google المتقدّمة، اتّبِع التعليمات التالية:
افتح مشروع Apps Script.
على يمين الشاشة، انقر على أداة التعديلcode.
على يمين الصفحة، انقر على إضافة خدمةadd بجانب الخدمات.
اختَر إحدى خدمات Google المتقدّمة وانقر على إضافة.
بعد تفعيل خدمة متقدّمة، ستتوفّر في ميزة الإكمال التلقائي.
كيفية تحديد تواقيع الطرق
تستخدم الخدمات المتقدّمة بشكل عام الكائنات وأسماء الطرق والمعلَمات نفسها التي تستخدمها واجهات برمجة التطبيقات العامة المقابلة، على الرغم من أنّه يتم ترجمة تواقيع الطرق لاستخدامها في Apps Script. تقدّم وظيفة الإكمال التلقائي في محرّر النصوص البرمجية عادةً معلومات كافية للبدء، ولكن توضّح القواعد أدناه كيف تنشئ "برمجة تطبيقات Google" توقيع طريقة من واجهة برمجة تطبيقات عامة من Google.
يمكن أن تقبل الطلبات المقدَّمة إلى واجهات Google API أنواعًا مختلفة من البيانات، بما في ذلك مَعلمات المسار ومَعلمات طلب البحث ونص الطلب و/أو مرفق تحميل الوسائط. يمكن لبعض الخدمات المتقدّمة أيضًا قبول عناوين طلبات HTTP معيّنة (على سبيل المثال، خدمة "تقويم Google" المتقدّمة).
يحتوي توقيع الطريقة المقابل في Google Apps Script على الوسيطات التالية:
مَعلمات اختيارية، على شكل كائن JavaScript يربط أسماء المَعلمات بالقيم
عناوين طلب HTTP، ككائن JavaScript يربط أسماء العناوين بقيمها
إذا لم تتضمّن الطريقة أي عناصر في فئة معيّنة، يتم حذف هذا الجزء من التوقيع.
هناك بعض الاستثناءات الخاصة التي يجب الانتباه إليها:
بالنسبة إلى الطرق التي تقبل تحميل الوسائط، يتم ضبط المَعلمة uploadType تلقائيًا.
إنّ الطرق التي تحمل الاسم delete في Google API تحمل الاسم remove في "برمجة تطبيقات Google"،
لأنّ delete هي كلمة محجوزة في JavaScript.
إذا تم ضبط إحدى الخدمات المتقدّمة لقبول عناوين طلبات HTTP، وقمت بضبط عنصر JavaScript لعناوين الطلبات، عليك أيضًا ضبط عنصر JavaScript للمعلمات الاختيارية (على عنصر فارغ إذا كنت لا تستخدم معلمات اختيارية).
التوافق مع الخدمات المتقدّمة
الخدمات المتقدّمة هي مجرد أغلفة بسيطة تتيح استخدام واجهات برمجة التطبيقات من Google ضمن "برمجة تطبيقات Google". وبالتالي، فإنّ أي مشكلة تواجهها أثناء استخدامها تكون عادةً مشكلة في واجهة برمجة التطبيقات الأساسية، وليس في Apps Script نفسها.
إذا واجهت مشكلة أثناء استخدام إحدى الخدمات المتقدّمة، يجب الإبلاغ عنها باتّباع تعليمات الدعم الخاصة بواجهة برمجة التطبيقات الأساسية. تتوفّر روابط تؤدي إلى تعليمات الدعم هذه في كل دليل خاص بالخدمات المتقدّمة في قسم المراجع في Apps Script.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
