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 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
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 전용 객체 유형 (예: Document 또는 Calendar)일 수 없습니다. string, number, array, object 또는 boolean과 같은 프리미티브 유형만 될 수 있습니다. 선택사항입니다.
sessionState

string

지원 중단되었습니다. Android 부가기능에서만 사용할 수 있습니다. Google Docs 또는 Sheets용 Android 앱에서 사용자의 현재 세션을 나타내는 ID로, 부가기능을 실행하는 Intent에 추가 데이터로 포함됩니다. Android 부가기능이 세션 상태로 실행되면 바인드된 스크립트의 권한을 얻게 됩니다. 즉, 사용자의 현재 커서 위치 (Docs) 또는 선택된 셀 (Sheets)과 같은 정보에 액세스할 수 있습니다. 상태를 가져오려면 Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState")를 호출합니다. 선택사항입니다.
devMode

boolean

true이고 사용자가 스크립트의 소유자인 경우 스크립트는 Apps Script API와 함께 사용하기 위해 배포된 버전이 아닌 가장 최근에 저장된 버전에서 실행됩니다. 선택사항입니다. 기본값은 false입니다.

응답 본문

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

run로 시작하는 Apps Script 함수의 실행을 나타냅니다. 함수 실행이 완료될 때까지 실행 응답은 도착하지 않습니다. 최대 실행 런타임은 Apps Script 할당량 가이드에 나열되어 있습니다.

실행이 시작된 후 다음 네 가지 결과 중 하나가 표시될 수 있습니다.

  • 스크립트 함수가 성공적으로 반환되면 response 필드에는 함수의 반환 값이 객체의 result 필드에 있는 ExecutionResponse 객체가 포함됩니다.
  • 스크립트 함수 (또는 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이면 error와 response가 모두 설정되지 않습니다. done == true이면 error 또는 response 중 정확히 하나만 설정할 수 있습니다. 일부 서비스는 결과를 제공하지 않을 수 있습니다. result은 다음 중 하나여야 합니다.
error

object (Status)

run 호출은 성공했지만 스크립트 함수 (또는 Apps Script 자체)에서 예외가 발생하는 경우 이 필드에 Status 객체가 포함됩니다. Status 객체의 details 필드에는 오류의 특성에 대한 정보를 제공하는 단일 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의 경우 이 값은 다음 중 하나입니다.

  • 10은 SCRIPT_TIMEOUT 오류를 나타냅니다.
  • 3: INVALID_ARGUMENT 오류를 나타냅니다.
  • 1은 CANCELLED 실행을 나타냅니다.
message

string

개발자에게 정보를 제공하는 오류 메시지(영어) 사용자에게 표시되는 모든 오류 메시지는 현지화되어 details 필드에 전송되거나 클라이언트에 의해 현지화됩니다.
details[]

object

오류의 특성에 대한 정보를 제공하는 단일 ExecutionError 객체가 포함된 배열입니다.

임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type"은 유형을 식별하는 URI를 포함합니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" }