Method: scripts.run

Executa uma função em um projeto do Apps Script. O projeto de script precisa ser implantado para uso com a API Apps Script, e o aplicativo de chamada precisa compartilhar o mesmo projeto do Cloud Platform.

Esse método exige autorização com um token OAuth 2.0 que inclua pelo menos um dos escopos listados na seção Autorização. Projetos de script que não exigem autorização não podem ser executados por essa API. Para encontrar os escopos corretos a serem incluídos no token de autenticação, abra a página Visão geral do projeto de script e role para baixo até "Escopos OAuth do projeto".

O erro 403, PERMISSION_DENIED: The caller does not have permission indica que o projeto do Cloud Platform usado para autorizar a solicitação não é o mesmo usado pelo script.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
deploymentId

string

O ID da implantação do executável da API. Encontre o ID de implantação em Implantar > Gerenciar implantações no editor de script.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Campos
function

string

O nome da função a ser executada no script especificado. O nome não inclui parênteses ou parâmetros. Ela pode referenciar uma função em uma biblioteca incluída, como Library.libFunction1.
parameters[]

value (Value format)

Os parâmetros a serem transmitidos para a função em execução. O tipo de objeto de cada parâmetro precisa corresponder ao tipo esperado no Apps Script. Os parâmetros não podem ser tipos de objetos específicos do Apps Script, como Document ou Calendar. Eles só podem ser tipos primitivos, como string, number, array, object ou boolean. Opcional.
sessionState

string

Descontinuado. Para uso somente com complementos do Android. Um ID que representa a sessão atual do usuário no app Android do Google Documentos ou Planilhas, incluído como dados extras na intent que inicia o complemento. Quando um complemento do Android é executado com um estado de sessão, ele ganha os privilégios de um script vinculado. Ou seja, ele pode acessar informações como a posição atual do cursor do usuário (no Documentos) ou a célula selecionada (no Planilhas). Para recuperar o estado, chame Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Opcional.
devMode

boolean

Se true e o usuário for proprietário do script, ele será executado na versão salva mais recentemente, e não na versão implantada para uso com a API Apps Script. Opcional. O padrão é false.

Corpo da resposta

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Uma representação da execução de uma função do Apps Script iniciada com run. A resposta de execução não chega até que a função termine de ser executada. O tempo máximo de execução está listado no guia de cotas do Apps Script.

Depois que a execução é iniciada, ela pode ter um destes quatro resultados:

  • Se a função de script for retornada com sucesso, o campo response vai conter um objeto ExecutionResponse com o valor de retorno da função no campo result do objeto.
  • Se a função de script (ou o próprio Apps Script) gerar uma exceção, o campo error vai conter um objeto Status. O campo details do objeto Status contém uma matriz com um único objeto ExecutionError que fornece informações sobre a natureza do erro.
  • Se a execução ainda não tiver sido concluída, o campo done será false e os campos response e error não estarão presentes.
  • Se a própria chamada run falhar (por exemplo, devido a uma solicitação malformada ou um erro de autorização), o método vai retornar um código de resposta HTTP no intervalo 4XX com um formato diferente para o corpo da resposta. As bibliotecas de cliente convertem automaticamente uma resposta 4XX em uma classe de exceção.

Representação 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.
}
Campos
done

boolean

Esse campo indica se a execução do script foi concluída. Uma execução concluída tem um campo response preenchido com o ExecutionResponse da função que foi executada.
Campo de união result. O resultado da operação, que pode ser um error ou uma response válida. Se done == false, nem error ou response estão definidos. Se done == true, é possível definir exatamente um entre error ou response. Alguns serviços podem não fornecer o resultado. result pode ser apenas de um dos tipos a seguir:
error

object (Status)

Se uma chamada run for bem-sucedida, mas a função de script (ou o próprio Apps Script) gerar uma exceção, esse campo vai conter um objeto Status. O campo details do objeto Status contém uma matriz com um único objeto ExecutionError que fornece informações sobre a natureza do erro.
response

object

Se a função de script for retornada com sucesso, esse campo vai conter um objeto ExecutionResponse com o valor de retorno da função.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Escopos de autorização

Requer um dos seguintes escopos do 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

Para mais informações, consulte a visão geral do OAuth 2.0.

Status

Se uma chamada run for bem-sucedida, mas a função de script (ou o próprio Apps Script) gerar uma exceção, o campo error do corpo da resposta vai conter esse objeto Status.

Representação JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

O código de status. Para essa API, esse valor:

  • 10, indicando um erro SCRIPT_TIMEOUT,
  • 3, indicando um erro INVALID_ARGUMENT, ou
  • 1, indicando uma execução de CANCELLED.
message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário é localizada e enviada no campo details, ou localizada pelo cliente.
details[]

object

Uma matriz que contém um único objeto ExecutionError com informações sobre a natureza do erro.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.