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 do 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/{scriptId}:run

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

Parâmetros de caminho

Parâmetros
scriptId

string

O ID do script a ser executado. Encontre o ID do script na página Configurações do projeto em "IDs".

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

Nome da função a ser executada no script fornecido. O nome não inclui parênteses ou parâmetros. Ele 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 que está sendo executada. O tipo de objeto de cada parâmetro deve corresponder ao tipo esperado no Apps Script. Os parâmetros não podem ser tipos de objeto 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

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

boolean

Se true e o usuário forem proprietários do script, o script vai ser executado na versão salva mais recentemente em vez da 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:

Representação de uma execução de uma função do Apps Script iniciada com run. A resposta de execução não chega até a função terminar de ser executada. O ambiente de execução máximo está listado no guia de cotas do Apps Script.

Após o início da execução, ela pode ter um dos quatro resultados:

  • Se a função do script retornar, 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 do script (ou o próprio Apps Script) gerar uma exceção, o campo error 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 incorreta ou a um erro de autorização), o método retorna 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 que contém o ExecutionResponse da função 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, exatamente um de error ou response pode ser definido. 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 do 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 do script retornar, esse campo 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 de 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 do 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 esta 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 voltada para o desenvolvedor. Todas as mensagens de erro para o usuário são localizadas e enviadas no campo details ou localizadas pelo cliente.
details[]

object

Uma matriz que contém um único objeto ExecutionError que fornece 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" }.