توفّر واجهة برمجة التطبيقات Google Apps Script طريقة scripts.run
تنفّذ عن بُعد دالة محدّدة في Apps Script. يمكنك استخدام هذه الطريقة في تطبيق لإجراء المكالمات لتشغيل دالة في أحد مشاريع النصوص البرمجية عن بُعد وتلقّي ردّ.
المتطلّبات
يجب استيفاء المتطلبات التالية قبل أن يتمكّن تطبيق اتصال من استخدام طريقة scripts.run
. يجب:
انشر مشروع البرنامج النصي كواجهة برمجة تطبيقات قابلة للتنفيذ. يمكنك نشر المشاريع وإلغاء نشرها وإعادة نشرها حسب الحاجة.
قدِّم رمز OAuth مميزًا بنطاق مناسب للتنفيذ. يجب أن يغطي رمز OAuth المميز جميع النطاقات التي يستخدمها النص البرمجي، وليس فقط النطاقات التي تستخدمها الدالة التي تم استدعاؤها. يمكنك الاطّلاع على القائمة الكاملة لنطاقات التفويض في مرجع الطريقة.
تأكَّد من أنّ النص البرمجي وبرنامج OAuth2 العميل الذي يستدعي النص البرمجي يشتركان في مشروع Google Cloud مشترك. يجب أن يكون مشروع Google Cloud مشروعًا عاديًا على Google Cloud، فالمشاريع التلقائية التي يتم إنشاؤها لمشاريع "برمجة التطبيقات" غير كافية. يمكنك استخدام مشروع جديد عادي على السحابة الإلكترونية أو مشروع حالي.
فعِّل Google Apps Script API في مشروع Cloud.
طريقة scripts.run
تتطلّب طريقة scripts.run
المعلومات الأساسية التالية لتنفيذها:
- معرّف مشروع البرنامج النصي
- اسم الدالة المطلوب تنفيذها.
- قائمة المَعلمات التي تتطلّبها الدالة (إن وُجدت)
يمكنك ضبط النص البرمجي اختياريًا ليتم تنفيذه في وضع التطوير. يتم تنفيذ هذا الوضع باستخدام أحدث نسخة محفوظة من مشروع النص البرمجي، وليس أحدث نسخة تم نشرها. يمكنك إجراء ذلك من خلال ضبط قيمة devMode
المنطقية في نص الطلب على true
. لا يمكن سوى لمالك النص البرمجي تنفيذه في وضع التطوير.
التعامل مع أنواع بيانات المَعلمات
يتضمّن استخدام طريقة scripts.run
في Apps Script API عادةً إرسال بيانات إلى Apps Script كمعلَمات للدالة واسترجاع البيانات كقيم معروضة للدالة. يمكن لواجهة برمجة التطبيقات تلقّي قيم ذات أنواع أساسية وعرضها فقط، مثل السلاسل والمصفوفات والكائنات والأرقام والقيم المنطقية. وهي تشبه الأنواع الأساسية في JavaScript. لا يمكن لواجهة برمجة التطبيقات تمرير كائنات "برمجة التطبيقات" الأكثر تعقيدًا، مثل المستند أو ورقة، إلى مشروع النص البرمجي أو منه.
عندما يكون تطبيق الاتصال مكتوبًا بلغة ذات كتابة قوية، مثل Java، يتم تمرير المَعلمات كقائمة أو مصفوفة من الكائنات العامة التي تتوافق مع هذه الأنواع الأساسية. في كثير من الحالات، يمكنك تطبيق عمليات تحويل بسيطة للأنواع تلقائيًا. على سبيل المثال، يمكن منح دالة تقبل مَعلمة رقمية كائن Java Double
أو Integer
أو Long
كمَعلمة بدون معالجة إضافية.
عندما تعرض واجهة برمجة التطبيقات استجابة الدالة، غالبًا ما تحتاج إلى تحويل القيمة المعروضة إلى النوع الصحيح قبل أن تتمكّن من استخدامها. في ما يلي بعض الأمثلة المستندة إلى Java:
- تصل الأرقام التي تعرضها واجهة برمجة التطبيقات لتطبيق Java على شكل عناصر
java.math.BigDecimal
، وقد تحتاج إلى تحويلها إلى أنواعDoubles
أوint
حسب الحاجة. إذا عرضت دالة Apps Script مصفوفة من السلاسل، سيحوّل تطبيق Java الرد إلى عنصر
List<String>
:List<String> mylist = (List<String>)(op.getResponse().get("result"));
إذا كنت تريد عرض مصفوفة من
Bytes
، قد يكون من الملائم ترميز المصفوفة كسلسلة base64 ضمن دالة "برمجة تطبيقات Google" وعرض هذه السلسلة بدلاً من ذلك:return Utilities.base64Encode(myByteArray); // returns a String.
توضّح عيّنات الرموز البرمجية أدناه طرقًا لتفسير استجابة واجهة برمجة التطبيقات.
الإجراء العام
في ما يلي وصف للإجراء العام لاستخدام واجهة برمجة التطبيقات Apps Script API لتنفيذ دوال Apps Script:
الخطوة 1: إعداد مشروع Cloud المشترك
يجب أن يشترك النص البرمجي والتطبيق الذي يستدعيه في مشروع Cloud نفسه. يمكن أن يكون مشروع Cloud هذا مشروعًا حاليًا أو مشروعًا جديدًا تم إنشاؤه لهذا الغرض. بعد إنشاء مشروع Cloud، عليك تبديل مشروع النص البرمجي لاستخدامه.
الخطوة 2: نشر النص البرمجي كملف API قابل للتنفيذ
- افتح مشروع Apps Script الذي يتضمّن الدوال التي تريد استخدامها.
- في أعلى يسار الصفحة، انقر على نشر > عملية نشر جديدة.
- في مربّع الحوار الذي يظهر، انقر على "تفعيل أنواع النشر"
> ملف تنفيذي لواجهة برمجة التطبيقات.
- في القائمة المنسدلة "مَن يمكنه الوصول"، اختَر المستخدمين المسموح لهم باستدعاء وظائف البرنامج النصي باستخدام واجهة برمجة التطبيقات Apps Script API.
- انقر على نشر.
الخطوة 3: ضبط تطبيق الاتصال
يجب أن يفعّل التطبيق الذي يجري الاتصال واجهة Apps Script API وأن ينشئ بيانات اعتماد OAuth قبل أن يتمكّن من استخدامها. يجب أن يكون لديك إذن الوصول إلى مشروع السحابة الإلكترونية لتنفيذ هذا الإجراء.
- اضبط مشروع Cloud الذي يستخدمه تطبيق الاتصال والنص البرمجي. يمكنك إجراء ذلك من خلال اتّباع الخطوات التالية:
- افتح مشروع النص وانقر على نظرة عامة
على يمين الصفحة.
- ضمن نطاقات OAuth للمشروع، سجِّل جميع النطاقات التي يتطلّبها النص البرمجي.
في رمز تطبيق الاتصال، أنشئ رمز دخول OAuth للبرنامج النصي لاستدعاء واجهة برمجة التطبيقات. هذا ليس رمزًا مميزًا تستخدمه واجهة برمجة التطبيقات نفسها، بل هو رمز يتطلبه النص البرمجي عند تنفيذه. يجب إنشاؤه باستخدام معرّف العميل الخاص بمشروع Cloud ونطاقات النص البرمجي التي سجّلتها.
يمكن أن تساعد مكتبات برامج Google بشكل كبير في إنشاء هذا الرمز المميز والتعامل مع OAuth للتطبيق، وعادةً ما تتيح لك بدلاً من ذلك إنشاء عنصر "بيانات اعتماد" أعلى مستوى باستخدام نطاقات النص البرمجي. راجِع التشغيل السريع لواجهة برمجة التطبيقات "برمجة التطبيقات" للاطّلاع على أمثلة حول كيفية إنشاء عنصر بيانات اعتماد من قائمة بالنطاقات.
الخطوة 4: إرسال طلب script.run
بعد إعداد تطبيق الاتصال، يمكنك إجراء مكالمات scripts.run
. تتضمّن كل عملية استدعاء لواجهة برمجة التطبيقات الخطوات التالية:
- أنشئ طلب بيانات من واجهة برمجة التطبيقات باستخدام رقم تعريف النص البرمجي واسم الدالة وأي معلَمات مطلوبة.
- أرسِل طلب
scripts.run
وأدرِج رمز OAuth المميز للنص البرمجي الذي أنشأته في العنوان (في حال استخدام طلبPOST
أساسي)، أو استخدِم عنصر بيانات اعتماد أنشأته باستخدام نطاقات النص البرمجي. - السماح للنص البرمجي بإنهاء التنفيذ يُسمح للنصوص البرمجية باستخدام مدة تنفيذ تصل إلى ست دقائق، لذا يجب أن يسمح تطبيقك بذلك.
- عند الانتهاء، قد تعرض دالة النص البرمجي قيمة، والتي تقدّمها واجهة برمجة التطبيقات إلى التطبيق إذا كانت القيمة من نوع متوافق.
يمكنك الاطّلاع على أمثلة على script.run
طلبات البيانات من واجهة برمجة التطبيقات أدناه.
أمثلة على طلبات البيانات من واجهة برمجة التطبيقات
تعرض الأمثلة التالية كيفية إرسال طلب تنفيذ إلى إحدى واجهات برمجة التطبيقات في "برمجة تطبيقات Google" بلغات مختلفة، وذلك من خلال استدعاء دالة في "برمجة تطبيقات Google" لطباعة قائمة بالمجلدات في الدليل الجذر الخاص بالمستخدم. يجب تحديد معرّف البرنامج النصي لمشروع "برمجة تطبيقات Google" الذي يحتوي على الدالة التي تم تنفيذها في المكان المحدّد بعلامة ENTER_YOUR_SCRIPT_ID_HERE
. تعتمد الأمثلة على مكتبات عملاء Google API للغات المعنية.
النص البرمجي المستهدَف
تستخدم الدالة في هذا النص البرمجي واجهة برمجة تطبيقات Drive.
يجب تفعيل Drive API في المشروع الذي يستضيف النص البرمجي.
بالإضافة إلى ذلك، يجب أن ترسل التطبيقات التي تجري مكالمات بيانات اعتماد OAuth التي تتضمّن نطاق Drive التالي:
https://www.googleapis.com/auth/drive
تستخدم التطبيقات النموذجية هنا مكتبات برامج Google للعملاء لإنشاء عناصر بيانات اعتماد لبروتوكول OAuth باستخدام هذا النطاق.
/** * Return the set of folder names contained in the user's root folder as an * object (with folder IDs as keys). * @return {Object} A set of folder names keyed by folder ID. */ function getFoldersUnderRoot() { const root = DriveApp.getRootFolder(); const folders = root.getFolders(); const folderSet = {}; while (folders.hasNext()) { const folder = folders.next(); folderSet[folder.getId()] = folder.getName(); } return folderSet; }
Java
/** * Create a HttpRequestInitializer from the given one, except set * the HTTP read timeout to be longer than the default (to allow * called scripts time to execute). * * @param {HttpRequestInitializer} requestInitializer the initializer * to copy and adjust; typically a Credential object. * @return an initializer with an extended read timeout. */ private static HttpRequestInitializer setHttpTimeout( final HttpRequestInitializer requestInitializer) { return new HttpRequestInitializer() { @Override public void initialize(HttpRequest httpRequest) throws IOException { requestInitializer.initialize(httpRequest); // This allows the API to call (and avoid timing out on) // functions that take up to 6 minutes to complete (the maximum // allowed script run time), plus a little overhead. httpRequest.setReadTimeout(380000); } }; } /** * Build and return an authorized Script client service. * * @param {Credential} credential an authorized Credential object * @return an authorized Script client service */ public static Script getScriptService() throws IOException { Credential credential = authorize(); return new Script.Builder( HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential)) .setApplicationName(APPLICATION_NAME) .build(); } /** * Interpret an error response returned by the API and return a String * summary. * * @param {Operation} op the Operation returning an error response * @return summary of error response, or null if Operation returned no * error */ public static String getScriptError(Operation op) { if (op.getError() == null) { return null; } // Extract the first (and only) set of error details and cast as a Map. // The values of this map are the script's 'errorMessage' and // 'errorType', and an array of stack trace elements (which also need to // be cast as Maps). Map<String, Object> detail = op.getError().getDetails().get(0); List<Map<String, Object>> stacktrace = (List<Map<String, Object>>) detail.get("scriptStackTraceElements"); java.lang.StringBuilder sb = new StringBuilder("\nScript error message: "); sb.append(detail.get("errorMessage")); sb.append("\nScript error type: "); sb.append(detail.get("errorType")); if (stacktrace != null) { // There may not be a stacktrace if the script didn't start // executing. sb.append("\nScript error stacktrace:"); for (Map<String, Object> elem : stacktrace) { sb.append("\n "); sb.append(elem.get("function")); sb.append(":"); sb.append(elem.get("lineNumber")); } } sb.append("\n"); return sb.toString(); } public static void main(String[] args) throws IOException { // ID of the script to call. Acquire this from the Apps Script editor, // under Publish > Deploy as API executable. String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE"; Script service = getScriptService(); // Create an execution request object. ExecutionRequest request = new ExecutionRequest() .setFunction("getFoldersUnderRoot"); try { // Make the API request. Operation op = service.scripts().run(scriptId, request).execute(); // Print results of request. if (op.getError() != null) { // The API executed, but the script returned an error. System.out.println(getScriptError(op)); } else { // The result provided by the API needs to be cast into // the correct type, based upon what types the Apps // Script function returns. Here, the function returns // an Apps Script Object with String keys and values, // so must be cast into a Java Map (folderSet). Map<String, String> folderSet = (Map<String, String>) (op.getResponse().get("result")); if (folderSet.size() == 0) { System.out.println("No folders returned!"); } else { System.out.println("Folders under your root folder:"); for (String id : folderSet.keySet()) { System.out.printf( "\t%s (%s)\n", folderSet.get(id), id); } } } } catch (GoogleJsonResponseException e) { // The API encountered a problem before the script was called. e.printStackTrace(System.out); } }
JavaScript
/** * Load the API and make an API call. Display the results on the screen. */ function callScriptFunction() { const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>'; // Call the Apps Script API run method // 'scriptId' is the URL parameter that states what script to run // 'resource' describes the run request body (with the function name // to execute) try { gapi.client.script.scripts.run({ 'scriptId': scriptId, 'resource': { 'function': 'getFoldersUnderRoot', }, }).then(function(resp) { const result = resp.result; if (result.error && result.error.status) { // The API encountered a problem before the script // started executing. appendPre('Error calling API:'); appendPre(JSON.stringify(result, null, 2)); } else if (result.error) { // The API executed, but the script returned an error. // Extract the first (and only) set of error details. // The values of this object are the script's 'errorMessage' and // 'errorType', and an array of stack trace elements. const error = result.error.details[0]; appendPre('Script error message: ' + error.errorMessage); if (error.scriptStackTraceElements) { // There may not be a stacktrace if the script didn't start // executing. appendPre('Script error stacktrace:'); for (let i = 0; i < error.scriptStackTraceElements.length; i++) { const trace = error.scriptStackTraceElements[i]; appendPre('\t' + trace.function + ':' + trace.lineNumber); } } } else { // The structure of the result will depend upon what the Apps // Script function returns. Here, the function returns an Apps // Script Object with String keys and values, and so the result // is treated as a JavaScript object (folderSet). const folderSet = result.response.result; if (Object.keys(folderSet).length == 0) { appendPre('No folders returned!'); } else { appendPre('Folders under your root folder:'); Object.keys(folderSet).forEach(function(id) { appendPre('\t' + folderSet[id] + ' (' + id + ')'); }); } } }); } catch (err) { document.getElementById('content').innerText = err.message; return; } }
Node.js
/** * Call an Apps Script function to list the folders in the user's root Drive * folder. * */ async function callAppsScript() { const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT'; const {GoogleAuth} = require('google-auth-library'); const {google} = require('googleapis'); // Get credentials and build service // TODO (developer) - Use appropriate auth mechanism for your app const auth = new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/drive', }); const script = google.script({version: 'v1', auth}); try { // Make the API request. The request object is included here as 'resource'. const resp = await script.scripts.run({ auth: auth, resource: { function: 'getFoldersUnderRoot', }, scriptId: scriptId, }); if (resp.error) { // The API executed, but the script returned an error. // Extract the first (and only) set of error details. The values of this // object are the script's 'errorMessage' and 'errorType', and an array // of stack trace elements. const error = resp.error.details[0]; console.log('Script error message: ' + error.errorMessage); console.log('Script error stacktrace:'); if (error.scriptStackTraceElements) { // There may not be a stacktrace if the script didn't start executing. for (let i = 0; i < error.scriptStackTraceElements.length; i++) { const trace = error.scriptStackTraceElements[i]; console.log('\t%s: %s', trace.function, trace.lineNumber); } } } else { // The structure of the result will depend upon what the Apps Script // function returns. Here, the function returns an Apps Script Object // with String keys and values, and so the result is treated as a // Node.js object (folderSet). const folderSet = resp.response.result; if (Object.keys(folderSet).length == 0) { console.log('No folders returned!'); } else { console.log('Folders under your root folder:'); Object.keys(folderSet).forEach(function(id) { console.log('\t%s (%s)', folderSet[id], id); }); } } } catch (err) { // TODO(developer) - Handle error throw err; } }
Python
import google.auth from googleapiclient.discovery import build from googleapiclient.errors import HttpError def main(): """Runs the sample.""" # pylint: disable=maybe-no-member script_id = "1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt" creds, _ = google.auth.default() service = build("script", "v1", credentials=creds) # Create an execution request object. request = {"function": "getFoldersUnderRoot"} try: # Make the API request. response = service.scripts().run(scriptId=script_id, body=request).execute() if "error" in response: # The API executed, but the script returned an error. # Extract the first (and only) set of error details. The values of # this object are the script's 'errorMessage' and 'errorType', and # a list of stack trace elements. error = response["error"]["details"][0] print(f"Script error message: {0}.{format(error['errorMessage'])}") if "scriptStackTraceElements" in error: # There may not be a stacktrace if the script didn't start # executing. print("Script error stacktrace:") for trace in error["scriptStackTraceElements"]: print(f"\t{0}: {1}.{format(trace['function'], trace['lineNumber'])}") else: # The structure of the result depends upon what the Apps Script # function returns. Here, the function returns an Apps Script # Object with String keys and values, and so the result is # treated as a Python dictionary (folder_set). folder_set = response["response"].get("result", {}) if not folder_set: print("No folders returned!") else: print("Folders under your root folder:") for folder_id, folder in folder_set.items(): print(f"\t{0} ({1}).{format(folder, folder_id)}") except HttpError as error: # The API encountered a problem before the script started executing. print(f"An error occurred: {error}") print(error.content) if __name__ == "__main__": main()
القيود
تتضمّن واجهة برمجة التطبيقات "برمجة التطبيقات" عدة قيود:
مشروع Cloud مشترك يجب أن يتشارك النص البرمجي الذي يتم استدعاؤه والتطبيق الذي يستدعيه في مشروع Cloud. يجب أن يكون مشروع Cloud مشروع Cloud عاديًا، فالمشاريع التلقائية التي يتم إنشاؤها لمشاريع "برمجة التطبيقات" غير كافية. يمكن أن يكون مشروع Cloud العادي مشروعًا جديدًا أو مشروعًا حاليًا.
أنواع المَعلمات الأساسية وأنواع الإرجاع لا يمكن لواجهة برمجة التطبيقات تمرير أو عرض كائنات خاصة بـ "برمجة تطبيقات Google" (مثل المستندات والكائنات الثنائية الكبيرة والتقاويم وملفات Drive وما إلى ذلك) إلى التطبيق. يمكن تمرير الأنواع الأساسية فقط، مثل السلاسل والمصفوفات والعناصر والأرقام والقيم المنطقية.
نطاقات OAuth لا يمكن لواجهة برمجة التطبيقات تنفيذ النصوص البرمجية التي لا تتضمّن نطاقًا واحدًا على الأقل من النطاقات المطلوبة. وهذا يعني أنّه لا يمكنك استخدام واجهة برمجة التطبيقات لاستدعاء نص برمجي لا يتطلّب تفويض خدمة واحدة أو أكثر.
لا يمكن إنشاء مشغِّلات: لا يمكن لواجهة برمجة التطبيقات إنشاء مشغِّلات في Apps Script.