Method: scripts.run

تشغِّل دالة في مشروع "برمجة تطبيقات Google". يجب نشر مشروع النص البرمجي للاستخدام مع واجهة برمجة التطبيقات لبرمجة التطبيقات، ويجب أن يشارك تطبيق الاتصال مشروع 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/{scriptId}:run

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

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

المعلمات
scriptId

string

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

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

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

string

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

value (Value format)

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

string

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

boolean

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

نص الاستجابة

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

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

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

  • إذا تم إرجاع دالة النص البرمجي بنجاح، سيحتوي الحقل response على كائن ExecutionResponse يتضمن القيمة المعروضة للدالة في حقل result للكائن.
  • إذا طرحت دالة النص البرمجي (أو برمجة التطبيقات نفسها) استثناءً، سيحتوي الحقل 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 صالحة. إذا كانت done == false، لم يتم ضبط error أو response. إذا كانت قيمة done == true، قد يتم ضبط قيمة واحدة بالضبط من error أو response. قد لا تقدّم بعض الخدمات النتيجة. يمكن أن يكون result واحدًا فقط مما يلي:
error

object (Status)

إذا نجح طلب run ولكن عرضت دالة النص البرمجي (أو برمجة التطبيقات نفسها) استثناءً، يحتوي هذا الحقل على كائن 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 ولكن طرحت دالة النص البرمجي (أو برمجة التطبيقات نفسها) استثناءً، سيحتوي حقل 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" }