Method: scripts.run

لتشغيل دالة في مشروع برمجة التطبيقات. يجب نشر مشروع النص البرمجي لاستخدامه مع واجهة برمجة التطبيقات "لبرمجة التطبيقات" ويجب أن يشارك تطبيق الاتصال المشروع نفسه على 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)

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

string

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

boolean

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

نص الاستجابة

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

بدأ تنفيذ دالة برمجة التطبيقات باستخدام run. لا تصل استجابة التنفيذ إلى أن تنتهي الدالة من التنفيذ. يتم إدراج الحد الأقصى لوقت تشغيل التنفيذ في دليل حصص برمجة التطبيقات.

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

  • إذا تم إرجاع دالة النص البرمجي بنجاح، فإن الحقل 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" }.