خدمات Google المُدمَجة

يوفّر Google Apps Script أكثر من 30 خدمة مضمّنة للتفاعل مع بيانات المستخدمين وأنظمة Google الأخرى والأنظمة الخارجية. يتم تقديم هذه الخدمات كعناصر عالمية مشابهة لكائن Math العادي في JavaScript. على سبيل المثال، تمامًا كما يوفّر Math طرقًا مثل random() و ثوابت مثل PI، يوفّر في Apps Script خدمة جداول البيانات طرقًا مثل openById(id)، وفئات (عناصر فرعية) مثل Range، وقوائم تصانيف مثل DataValidationCriteria.

يتم جمع المستندات المرجعية للخدمات التي تتحكّم في Google Workspace المنتجات في القسم "Google Workspace الخدمات" ضمن العنوان "مرجع" في الشريط الجانبي لهذا الموقع الإلكتروني. يتم جمع خدمات المرافق (مثل إنشاء واجهات المستخدم أو تحليل تنسيق XML أو كتابة بيانات السجلّ) في قسم "خدمات النصوص البرمجية".

ميزات JavaScript الحديثة

يتوافق Apps Script مع وقتَي تشغيل JavaScript: وقت التشغيل الحديث V8 ووقت التشغيل القديم المستنِد إلى مُفسِّر JavaScript Rhino من Mozilla.

يتوافق وقت تشغيل V8 مع ميزات وبنية ECMAScript الحديثة. يستند وقت تشغيل Rhino إلى الإصدار الأقدم من JavaScript 1.6 ، بالإضافة إلى بعض الميزات من الإصدارين 1.7 و1.8. يمكنك اختيار وقت التشغيل بحرية لاستخدامه مع النص البرمجي، ولكننا ننصح بشدة باستخدام وقت التشغيل V8.

يتوافق كل وقت تشغيل مع فئات JavaScript والكائنات المتاحة لملف برمجي بالإضافة إلى خدمات Google المتقدّمة المضمّنة. يمكن أن تستخدم النصوص البرمجية الكائنات الشائعة مثل Array و Date و RegExp و وما إلى ذلك، بالإضافة إلى الكائنات الشاملة Math و Object.

استخدام ميزة "الإكمال التلقائي"

يقدّم محرِّر النصوص البرمجية ميزة "مساعدة المحتوى"، والتي تُعرف بشكلٍ شائع باسم "الإكمال التلقائي"، والتي تكشف عن العناصر الشاملة بالإضافة إلى الطرق والعناصر المدرَجة في القوائم التي تكون صالحة في السياق الحالي للنص البرمجي. تظهر اقتراحات الإكمال التلقائي تلقائيًا عند كتابة نقطة بعد استدعاء مثيل أو قائمة أو طريقة شاملة يعرض فئة Apps Script. على سبيل المثال:

  • إذا كتبت الاسم الكامل لكائن شامل أو اخترت أحد الكائنات من ميزة الإكمال التلقائي، ثم كتبت . (نقطة)، ستظهر لك جميع الطرق والعناصر المحددة لهذه الفئة.
  • إذا كتبت بضع أحرف، ستظهر لك كل الاقتراحات ال válida التي تبدأ بهذه الأحرف.

فهم العناصر الشاملة

توفّر كل خدمة عنصرًا عامًا واحدًا على الأقل (من المستوى الأعلى). على سبيل المثال، لا يمكن الوصول إلى خدمة Gmail إلا من العنصر GmailApp. تقدّم بعض الخدمات كائنات عالمية متعدّدة. على سبيل المثال، تتضمّن الخدمة الأساسية أربعة كائنات عالمية: Browser و Logger و MimeType و Session.

طرق الاتصال

تتضمّن العناصر الشاملة لجميع الخدمات المتقدّمة أو المضمّنة تقريبًا طرقًا تؤدي إلى عرض بيانات أو فئة Apps Script. تُجري النصوص البرمجية مكالمات بالطريقة التالية:

GlobalObjectName.methodName(argument1, argument2, ..., argumentN);

على سبيل المثال، يمكن لنص برمجي إرسال رسالة إلكترونية من خلال استدعاء sendEmail(recipient, subject, body) طريقة خدمة Gmail على النحو التالي:

GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');

إذا كانت إحدى الطرق تعرِض فئة أخرى من Apps Script، يمكنك ربط طلبات استدعاء الطريقة في سطر واحد. (يتم عرض أنواع الإرجاع في ميزة الإكمال التلقائي وفي مستندات مرجع الطريقة.) على سبيل المثال، تُعرِض الطريقة DocumentApp.create() Document، وبالتالي، فإنّ القسمَين التاليَين من الرمز البرمجي متكافئان:

var doc = DocumentApp.create('New document');
var body = doc.getTab('t.0').asDocumentTab().getBody();
body.appendParagraph('New paragraph.');

// Same result as above.
DocumentApp.create('New document').getTab('t.0').asDocumentTab().getBody()
    .appendParagraph('New paragraph.');

الوصول إلى الصفوف الفرعية

تتضمّن كل خدمة فئة فرعية واحدة أو أكثر لا يمكن الوصول إليها من المستوى الأعلى كما يمكن الوصول إلى عنصر شامل. لا يمكنك استخدام الكلمة الرئيسية new ل إنشاء هذه الفئات، كما يمكنك استخدام فئات JavaScript العادية مثل Date. لا يمكنك الوصول إلى فئة فرعية إلا من خلال استدعاء طريقة تعرضها. إذا لم تكن متأكّدًا من كيفية الوصول إلى فئة معيّنة، انتقِل إلى الصفحة الرئيسية للمستندات المرجعية للخدمة وابحث عن طريقة تعرض الفئة التي تريدها.

التعامل مع الواجهات

تتضمّن بعض الخدمات فئات خاصة مصنّفة على أنّها "واجهات" في المستندات المرجعية. هذه فئات عامة تُستخدَم كأنواع معروضة للطُرق التي لا يمكنها تحديد النوع الدقيق مسبقًا. على سبيل المثال، تُعرِض طريقة خدمة المستندات Body.getChild(childIndex) عنصرًا عامًا من النوع Element. Element هي واجهة تمثّل فئة أخرى، ربما Paragraph أو Table. نادرًا ما تكون مثيلات الواجهات مفيدة بمفردها، وبدلاً من ذلك، عليك عادةً استدعاء طريقة مثل Element.asParagraph() لتحويل العنصر مرة أخرى إلى فئة دقيقة.

العمل مع القوائم المحددة

تتضمّن معظم الخدمات بعض أنواع القيم المُسمّاة. على سبيل المثال، تستخدِم خدمة Drive العناصر المدرَجة Access و Permission لتحديد المستخدمين الذين يمكنهم الوصول إلى ملف أو مجلد. في جميع الحالات تقريبًا، يمكنك الوصول إلى قوائم القيم المحدَّدة مسبقًا هذه من الكائن الشامل. على سبيل المثال، تبدو الدعوة إلى الطريقة Folder.setSharing(accessType, permissionType) على النحو التالي:

// Creates a folder that anyone on the Internet can read from and write to. (Domain administrators can
// prohibit this setting for Google Workspace users.)
var folder = DriveApp.createFolder('Shared Folder');
folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);