Method: scripts.run

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Apps Script プロジェクトで関数を実行します。Apps Script API で使用するためにスクリプト プロジェクトをデプロイする必要があり、呼び出し元アプリケーションは同じ Cloud Platform プロジェクトを共有する必要があります。

この方法では、承認セクションに記載されているスコープの少なくとも 1 つを含む 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

実行されるスクリプトのスクリプト ID。スクリプト ID は [プロジェクト設定] ページの [ID] に設定します。

リクエスト本文

リクエストの本文には次の構造のデータが含まれます。

JSON 表現
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
フィールド
function

string

指定されたスクリプトで実行される関数の名前。名前にかっこやパラメータは含まれません。Library.libFunction1 などの付属ライブラリの関数を参照できます。

parameters[]

value (Value format)

実行される関数に渡されるパラメータ。各パラメータのオブジェクト タイプは、Apps Script で想定されるタイプと一致する必要があります。Apps Script 固有のオブジェクト タイプ(DocumentCalendar など)をパラメータにすることはできません。プリミティブ型(stringnumberarrayobjectboolean など)のみにできます。省略可。

sessionState

string

非推奨。Android アドオンでのみ使用できます。Google ドキュメントまたはスプレッドシートの Android アプリでのユーザーの現在のセッションを表す ID。アドオンを起動する インテントに追加データとして含まれます。Android アドオンをセッション状態で実行する場合、バインド スクリプトの権限を取得します。つまり、ユーザーの現在のカーソル位置(ドキュメントの場合)または選択したセル(スプレッドシートの場合)などの情報にアクセスできます。状態を取得するには、Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState") を呼び出します。省略可。

devMode

boolean

true がユーザーによってスクリプトのオーナーである場合、そのスクリプトは、Apps Script API でデプロイするためにデプロイされたバージョンではなく、最後に保存されたバージョンで実行されます。省略可。デフォルトは false です。

レスポンスの本文

成功すると、レスポンスの本文に次の構造のデータが含まれます。

run で始まる Apps Script 関数の実行表現。関数の実行が完了するまで、実行レスポンスは到着しません。最大実行ランタイムは、Apps Script 割り当てガイドに記載されています。

実行が開始すると、次の 4 つの結果のいずれかが得られます。

  • スクリプト関数が正常に返された場合、response フィールドに、ExecutionResponse オブジェクトが関数の result フィールドに返されます。
  • スクリプト関数(または Apps Script 自体)が例外をスローした場合、error フィールドには Status オブジェクトが含まれます。Status オブジェクトの details フィールドには、エラーの性質に関する情報を提供する単一の ExecutionError オブジェクトを含む配列が含まれています。
  • 実行がまだ完了していない場合、done フィールドは false となり、response フィールドと error フィールドのどちらも存在しません。
  • リクエストの形式が正しくない場合や承認エラーがあった場合など、run の呼び出し自体が失敗した場合、このメソッドは 4XX の範囲の HTTP レスポンス コードをレスポンス本文の形式が異なります。クライアント ライブラリは、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

このフィールドは、スクリプトの実行が完了したかどうかを示します。完了した実行には、実行された関数の ExecutionResponse を含む response フィールドに値が入力されます。

共用体フィールド result。オペレーションの結果。error または有効な response になります。done == false の場合、errorresponse も設定されません。done == true の場合、error または response のいずれかを設定できます。一部のサービスでは結果が表示されない場合があります。result は次のいずれかになります。
error

object (Status)

run 呼び出しが成功したにもかかわらず、スクリプト関数(または Apps Script 自体)が例外をスローした場合、このフィールドには Status オブジェクトが含まれます。Status オブジェクトの details フィールドには、エラーの性質に関する情報を提供する単一の ExecutionError オブジェクトを含む配列が含まれています。

response

object

スクリプト関数が正常に結果を返した場合、このフィールドには、関数の戻り値が指定された ExecutionResponse オブジェクトが含まれます。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含むフィールド "@type" を追加できます。例: { "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 では、この値は次のいずれかになります。

  • 10 は SCRIPT_TIMEOUT エラーであることを示します。
  • 3 は、INVALID_ARGUMENT エラーを示します。
  • 1 は CANCELLED の実行であることを示します。

message

string

デベロッパー向けのエラー メッセージ(英語)が表示されます。ユーザー向けのエラー メッセージは、ローカライズして details フィールドで送信するか、クライアントでローカライズします。

details[]

object

エラーの性質に関する情報を提供する単一の ExecutionError オブジェクトを含む配列。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含むフィールド "@type" を追加できます。例: { "id": 1234, "@type": "types.example.com/standard/id" }