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)

المعلمات التي يتم تمريرها إلى الدالة التي يتم تنفيذها. يجب أن يتطابق نوع الكائن لكل مَعلمة مع النوع المتوقّع في "برمجة التطبيقات". لا يمكن أن تكون المعلمات أنواع عناصر خاصة ببرمجة التطبيقات (مثل 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. لا تصل استجابة التنفيذ إلى أن ينتهي تنفيذ الدالة. يتم إدراج الحد الأقصى لوقت التشغيل للتنفيذ في دليل حصص النصوص البرمجية للتطبيقات.

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

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