Method: scripts.run

عملکردی را در پروژه Apps Script اجرا می کند. پروژه اسکریپت باید برای استفاده با Apps Script API مستقر شود و برنامه فراخوان باید همان پروژه Cloud Platform را به اشتراک بگذارد.

این روش نیاز به مجوز با یک توکن OAuth 2.0 دارد که حداقل یکی از حوزه های فهرست شده در بخش مجوز را شامل می شود. پروژه های اسکریپتی که نیازی به مجوز ندارند از طریق این API قابل اجرا نیستند. برای یافتن دامنه‌های صحیح برای گنجاندن در نشانه احراز هویت، صفحه نمای کلی پروژه اسکریپت را باز کنید و به سمت «محدوده‌های پروژه OAuth» بروید.

خطای 403, PERMISSION_DENIED: The caller does not have permission نشان می‌دهد که پروژه Cloud Platform که برای مجوز دادن به درخواست استفاده می‌شود با پروژه مورد استفاده در اسکریپت یکسان نیست.

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

پارامترهای مسیر

پارامترها
scriptId

string

شناسه اسکریپت اسکریپتی که باید اجرا شود. شناسه اسکریپت را در صفحه تنظیمات پروژه در قسمت «IDs» پیدا کنید.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
فیلدها
function

string

نام تابعی که باید در اسکریپت داده شده اجرا شود. نام شامل پرانتز یا پارامتر نیست. می‌تواند به یک تابع در یک کتابخانه موجود مانند Library.libFunction1 ارجاع دهد.

parameters[]

value ( Value format)

پارامترهایی که باید به تابع در حال اجرا منتقل شوند. نوع شی برای هر پارامتر باید با نوع مورد انتظار در Apps Script مطابقت داشته باشد. پارامترها نمی توانند انواع شیء خاص Apps Script (مانند یک Document یا یک Calendar ) باشند. آنها فقط می توانند انواع اولیه مانند string ، number ، array ، object یا boolean باشند. اختیاری.

sessionState

string

منسوخ شده فقط برای استفاده با افزونه های اندروید. شناسه‌ای که نشان‌دهنده جلسه فعلی کاربر در برنامه Android برای Google Docs یا Sheets است که به‌عنوان داده اضافی در Intent گنجانده شده است که افزونه را راه‌اندازی می‌کند. هنگامی که یک افزونه Android با وضعیت جلسه اجرا می‌شود، امتیازات یک اسکریپت محدود را به دست می‌آورد – یعنی می‌تواند به اطلاعاتی مانند موقعیت مکان‌نمای فعلی کاربر (در اسناد) یا سلول انتخابی (در کاربرگ‌نگار) دسترسی داشته باشد. برای بازیابی وضعیت، با Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState") تماس بگیرید. اختیاری.

devMode

boolean

اگر true و کاربر مالک اسکریپت باشد، اسکریپت در آخرین نسخه ذخیره شده به جای نسخه ای که برای استفاده با Apps Script API استفاده شده است اجرا می شود. اختیاری؛ پیش فرض false است.

بدن پاسخگو

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایشی از اجرای یک تابع Apps Script با run شروع شد. پاسخ اجرا تا زمانی که اجرای تابع به پایان برسد نمی رسد. حداکثر زمان اجرا در راهنمای سهمیه بندی Apps Script فهرست شده است.

پس از شروع اجرا، می تواند یکی از چهار نتیجه را داشته باشد:

  • اگر تابع اسکریپت با موفقیت برگردد، فیلد response حاوی یک شی ExecutionResponse با مقدار بازگشتی تابع در فیلد result شی است.
  • اگر تابع اسکریپت (یا خود Apps Script) یک استثنا ایجاد کند، فیلد 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 با موفقیت انجام شود اما تابع اسکریپت (یا خود Apps Script) یک استثنا ایجاد کند، این فیلد حاوی یک شی 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

کد وضعیت. برای این API، این مقدار یا:

  • 10، نشان دهنده خطای SCRIPT_TIMEOUT ،
  • 3، نشان دهنده خطای INVALID_ARGUMENT ، یا
  • 1، نشان دهنده اجرای CANCELLED .

message

string

یک پیام خطای برنامه‌نویس، که به زبان انگلیسی است. هر پیام خطای کاربر بومی سازی شده و در قسمت details ارسال می شود یا توسط مشتری بومی سازی می شود.

details[]

object

آرایه ای که حاوی یک شی ExecutionError است که اطلاعاتی در مورد ماهیت خطا ارائه می دهد.

یک شی حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .