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 requer 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 com 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

O nome da função a ser executada no script fornecido. O nome não inclui parênteses nem 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 passados para a função que está sendo executada. 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 objeto específicos do Apps Script, como Document ou Calendar. elas 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 Documentos ou Planilhas Google, incluído como dados extras no 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 Documentos) ou a célula selecionada (no app 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 um proprietário do script, o script será executado na versão salva mais recente em vez da 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 de uma 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 a execução. 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 for retornada corretamente, 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 vai ser false e os campos response e error não vão estar presentes.
  • Se a própria chamada run falhar (por exemplo, devido a uma solicitação malformada ou a um erro de autorização), o método 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 contendo 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 do script (ou o próprio Apps Script) gerar uma exceção, esse campo 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 for retornada corretamente, 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 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. Qualquer mensagem de erro voltada ao usuário é localizada e enviada no campo details ou localizada 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" }.