تشغيل دالة في مشروع "برمجة تطبيقات 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 |
رقم تعريف النص البرمجي المطلوب تنفيذه. ابحث عن رقم تعريف النص البرمجي في صفحة إعدادات المشروع ضمن "أرقام التعريف". |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "function": string, "parameters": [ value ], "sessionState": string, "devMode": boolean } |
الحقول | |
---|---|
function |
اسم الدالة المطلوب تنفيذها في البرنامج النصي المحدد. لا يحتوي الاسم على أقواس أو معلَمات. يمكن أن يشير إلى دالة في مكتبة مضمّنة، مثل |
parameters[] |
المعلمات التي يتم تمريرها إلى الدالة التي يتم تنفيذها. يجب أن يتطابق نوع الكائن لكل مَعلمة مع النوع المتوقّع في "برمجة التطبيقات". لا يمكن أن تكون المعلمات أنواع عناصر خاصة ببرمجة التطبيقات (مثل |
sessionState |
تمت إزالة هذا العمود. للاستخدام مع إضافات Android فقط. رقم تعريف يمثّل الجلسة الحالية للمستخدم في تطبيق Android في "مستندات Google" أو "جداول بيانات Google"، ويتم تضمينه كبيانات إضافية في هدف Intent الذي يؤدّي إلى إطلاق الإضافة. عند تشغيل إضافة Android بحالة جلسة، تحصل هذه الإضافة على امتيازات نص برمجي مرتبط، أي يمكنها الوصول إلى معلومات مثل موضع المؤشر الحالي للمستخدم (في "مستندات Google") أو الخلية المحددة (في "جداول بيانات Google"). لاسترداد الحالة، يمكنك طلب |
devMode |
إذا كان |
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
عرض لتنفيذ دالة "برمجة تطبيقات Google" التي بدأت بـ run
. لا تصل استجابة التنفيذ إلى أن ينتهي تنفيذ الدالة. يتم إدراج الحد الأقصى لوقت التشغيل للتنفيذ في دليل حصص النصوص البرمجية للتطبيقات.
بعد بدء التنفيذ، يمكن أن ينجم عن إحدى النتائج الأربع:
- إذا تم عرض دالة النص البرمجي بنجاح، سيحتوي الحقل
response
على عنصرExecutionResponse
مع القيمة التي تعرضها الدالة في الحقلresult
للكائن. - إذا طرحت دالة النص البرمجي (أو "برمجة التطبيقات" نفسها) استثناءً، سيحتوي الحقل
error
على الكائنStatus
. يحتوي الحقلdetails
في العنصرStatus
على مصفوفة تتضمّن عنصرExecutionError
واحدًا يقدّم معلومات عن طبيعة الخطأ. - في حال لم تكتمل عملية التنفيذ بعد، سيكون الحقل
done
هوfalse
ولا يتوفّر الحقلانresponse
أوerror
. - إذا تعذّر استدعاء
run
نفسه (على سبيل المثال، بسبب طلب مكتوب بشكلٍ غير صحيح أو خطأ في التفويض)، تعرض الطريقة رمز استجابة HTTP في نطاق 4XX بتنسيق مختلف لنص الاستجابة. تعمل مكتبات العملاء على تحويل استجابة 4XX تلقائيًا إلى فئة استثناء.
تمثيل JSON |
---|
{ "done": boolean, // Union field |
الحقول | |
---|---|
done |
يشير هذا الحقل إلى ما إذا كانت عملية تنفيذ النص البرمجي قد اكتملت أم لا. تحتوي عملية التنفيذ المكتملة على حقل |
حقل الاتحاد result نتيجة العملية، والتي قد تكون error أو response صالحة. إذا كانت done == false ، لن يتم ضبط error أو response . إذا كانت done == true ، يمكن ضبط قيمة واحدة من error أو response بالضبط. قد لا تعرض بعض الخدمات النتيجة. يمكن أن تكون السمة "result " واحدة فقط مما يلي: |
|
error |
إذا نجح استدعاء |
response |
إذا تم عرض دالة النص البرمجي بنجاح، سيحتوي هذا الحقل على كائن كائن يحتوي على حقول من نوع عشوائي. يحتوي الحقل الإضافي |
نطاقات الأذونات
يتطلب استخدام أحد نطاقات 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 |
رمز الحالة. بالنسبة إلى واجهة برمجة التطبيقات هذه، تكون هذه القيمة إما:
|
message |
رسالة خطأ موجّهة للمطوّر، وتكون باللغة الإنجليزية تتم ترجمة أي رسالة خطأ تظهر للمستخدمين وإرسالها في حقل |
details[] |
مصفوفة تحتوي على عنصر كائن يحتوي على حقول من نوع عشوائي. يحتوي الحقل الإضافي |