Method: scripts.run

تُشغّل هذه الدالة إحدى الدوال في مشروع "برمجة تطبيقات Google". يجب نشر مشروع النص البرمجي لاستخدامه مع Apps Script API، ويجب أن يتشارك التطبيق الذي يستدعي واجهة برمجة التطبيقات مشروع Cloud Platform نفسه.

تتطلّب هذه الطريقة الحصول على تفويض باستخدام رمز مميّز OAuth 2.0 يتضمّن نطاقًا واحدًا على الأقل من النطاقات المدرَجة في قسم التفويض، ولا يمكن تنفيذ مشاريع النصوص البرمجية التي لا تتطلّب تفويضًا من خلال واجهة برمجة التطبيقات هذه. للعثور على النطاقات الصحيحة التي يجب تضمينها في رمز المصادقة، افتح صفحة نظرة عامة لمشروع البرنامج النصي وانتقِل للأسفل إلى "نطاقات OAuth للمشروع".

يشير الخطأ 403, PERMISSION_DENIED: The caller does not have permission إلى أنّ مشروع Cloud Platform المستخدَم لتفويض الطلب ليس هو نفسه المشروع المستخدَم بواسطة النص البرمجي.

طلب HTTP

POST https://script.googleapis.com/v1/scripts/{deploymentId}:run

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المعلمات
deploymentId

string

رقم تعريف عملية نشر ملف API القابل للتنفيذ ابحث عن رقم تعريف عملية النشر ضمن نشر > إدارة عمليات النشر في "محرّر النصوص البرمجية".

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
الحقول
function

string

اسم الدالة المطلوب تنفيذها في النص البرمجي المحدّد لا يتضمّن الاسم أقواسًا أو مَعلمات. يمكن أن يشير إلى دالة في مكتبة مضمّنة، مثل Library.libFunction1.
parameters[]

value (Value format)

المَعلمات التي سيتم تمريرها إلى الدالة التي يتم تنفيذها يجب أن يتطابق نوع العنصر لكل مَعلمة مع النوع المتوقّع في "برمجة التطبيقات". لا يمكن أن تكون المَعلمات أنواع كائنات خاصة بمنصة "برمجة التطبيقات" (مثل Document أو Calendar)، بل يمكن أن تكون أنواعًا أساسية فقط، مثل string أو number أو array أو object أو boolean. اختيارية:
sessionState

string

تمّت إزالة هذا العمود. للاستخدام مع إضافات Android فقط. رقم تعريف يمثّل جلسة المستخدم الحالية في تطبيق "مستندات Google" أو "جداول بيانات Google" على Android، ويتم تضمينه كبيانات إضافية في Intent الذي يطلق الإضافة. عند تشغيل إضافة Android مع حالة جلسة، تحصل على امتيازات نص برمجي مرتبط، أي يمكنها الوصول إلى معلومات مثل موضع المؤشر الحالي للمستخدم (في "مستندات Google") أو الخلية المحدّدة (في "جداول بيانات Google"). لاسترداد الولاية، اتّصِل بالرقم Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). اختيارية:
devMode

boolean

إذا كان true والمستخدم هو مالك النص البرمجي، يتم تشغيل النص البرمجي في أحدث إصدار تم حفظه بدلاً من الإصدار الذي تم نشره لاستخدامه مع Apps Script API. اختياري، والقيمة التلقائية هي false.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثّل هذه السمة عملية تنفيذ لدالة في "برمجة تطبيقات Google" تم بدؤها باستخدام run. لا يصل رد التنفيذ إلا بعد انتهاء تنفيذ الدالة. يتم إدراج الحد الأقصى لوقت تشغيل التنفيذ في دليل حصص Apps Script.

بعد بدء التنفيذ، يمكن أن تكون إحدى النتائج الأربع التالية:

  • إذا تم عرض دالة البرنامج النصي بنجاح، سيحتوي الحقل response على الكائن ExecutionResponse الذي يتضمّن قيمة العرض الخاصة بالدالة في الحقل result الخاص بالكائن.
  • إذا عرضت دالة النص البرمجي (أو "برمجة تطبيقات Google" نفسها) استثناءً، سيحتوي الحقل error على عنصر Status. يحتوي الحقل details الخاص بالعنصر Status على مصفوفة تتضمّن عنصر ExecutionError واحد يقدّم معلومات حول طبيعة الخطأ.
  • إذا لم يكتمل التنفيذ بعد، سيكون الحقل done هو false، ولن يكون الحقلان response وerror متوفّرَين.
  • إذا تعذّر تنفيذ طلب run نفسه (على سبيل المثال، بسبب طلب مكتوب بصيغة غير صحيحة أو خطأ في منح الإذن)، ستعرض الطريقة رمز استجابة HTTP في النطاق 4XX بتنسيق مختلف لنص الاستجابة. تحوّل مكتبات العملاء تلقائيًا الردّ 4XX إلى فئة استثناء.

تمثيل JSON 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
الحقول
done

boolean

يشير هذا الحقل إلى ما إذا كان قد تم إكمال تنفيذ النص البرمجي. يحتوي التنفيذ المكتمل على حقل response مملوء يتضمّن ExecutionResponse من الدالة التي تم تنفيذها.
حقل الدمج result تمثّل نتيجة العملية، والتي يمكن أن تكون إما error أو response صالحة. إذا كان false ‏== done، هذا يعني أنّه لم يتم ضبط أي من error أو response. إذا كان true ‏ == done، هذا يعني أنّه يمكن ضبط إما error أو response فقط. بعض الخدمات قد لا توفّر النتيجة. يمكن أن تكون result إحدى القيم التالية فقط:
error

object (Status)

إذا نجح طلب run ولكن طرحت دالة النص البرمجي (أو "برمجة تطبيقات Google" نفسها) استثناءً، سيحتوي هذا الحقل على عنصر Status. يحتوي الحقل details الخاص بالعنصر Status على مصفوفة تتضمّن عنصر ExecutionError واحدًا يقدّم معلومات حول طبيعة الخطأ.
response

object

إذا تم عرض دالة البرنامج النصي بنجاح، يحتوي هذا الحقل على عنصر ExecutionResponse يتضمّن قيمة العرض الخاصة بالدالة.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

نطاقات التفويض

يجب توفير أحد نطاقات OAuth التالية:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على بروتوكول OAuth 2.0.

الحالة

إذا نجح طلب run ولكن دالة النص البرمجي (أو "برمجة تطبيقات Google" نفسها) طرحت استثناءً، سيحتوي الحقل error في نص الاستجابة على عنصر Status هذا.

تمثيل JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
الحقول
code

integer

تمثّل هذه السمة رمز الحالة. بالنسبة إلى واجهة برمجة التطبيقات هذه، تكون هذه القيمة إما:

  • ‫10، ما يشير إلى حدوث خطأ SCRIPT_TIMEOUT
  • ‫3، ما يشير إلى حدوث خطأ INVALID_ARGUMENT، أو
  • ‫1، ما يشير إلى تنفيذ CANCELLED
message

string

يشير إلى رسالة خطأ موجّهة للمطوّرين، وهي باللغة الإنجليزية. يتم ترجمة أي رسالة خطأ موجّهة للمستخدمين وإرسالها في حقل details أو ترجمتها من قِبل العميل.
details[]

object

مصفوفة تحتوي على عنصر ExecutionError واحد يوفّر معلومات عن طبيعة الخطأ.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.