Method: scripts.run

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

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

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

درخواست HTTP

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

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

پارامترها
deploymentId

string

شناسه استقرار برای استقرار اجرایی API. شناسه استقرار را در قسمت استقرار > مدیریت استقرارها در ویرایشگر اسکریپت پیدا کنید.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش 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

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

devMode

boolean

اگر true و کاربر مالک اسکریپت باشد، اسکریپت به جای نسخه‌ای که برای استفاده با 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 فیلد Union. نتیجه عملیات، که می‌تواند یک 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 موفقیت‌آمیز باشد اما تابع اسکریپت (یا خود Apps Script) یک استثنا ایجاد کند، فیلد error بدنه پاسخ شامل این شیء Status خواهد بود.

نمایش JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
فیلدها
code

integer

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

  • ۱۰، که نشان‌دهنده‌ی خطای SCRIPT_TIMEOUT است،
  • ۳، که نشان‌دهنده‌ی خطای INVALID_ARGUMENT است، یا
  • ۱، که نشان‌دهنده‌ی اجرای CANCELLED .

message

string

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

details[]

object

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

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