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" }