A API Google Apps Script fornece uma
Método scripts.run
que executa remotamente uma função específica do Apps Script. Use esse método
em um aplicativo de chamada para executar uma função em um dos projetos de script;
remotamente e receber uma resposta.
Requisitos
Atenda aos requisitos a seguir para que um aplicativo de chamada possa usar
scripts.run
. Você precisa:
Implante o projeto de script como um executável de API. Você pode implantar, cancelar a implantação e reimplantar projetos conforme necessário.
Forneça um token OAuth com o escopo adequado para a execução. Esse token OAuth precisa abranger todos os escopos usados pelo script, não apenas aqueles usados pela função chamada. Consulte a lista completa de escopos de autorização na referência do método.
Verifique se o script e o OAuth2 do aplicativo de chamada cliente compartilham um projeto em comum do Google Cloud. O projeto precisa ser um projeto padrão do Cloud. projetos padrão criados para projetos do Apps Script são insuficientes. É possível usar um novo projeto padrão do Cloud ou um existente.
Ativar a API Google Apps Script no projeto do Cloud.
Método scripts.run
O scripts.run
requer informações de identificação importantes para ser executado:
- O ID do projeto de script.
- O nome da função executar.
- A lista de parâmetros necessário para a função (se houver).
Como opção, você pode configurar seu script para ser executado no modo de desenvolvimento.
Este modo é executado com a versão salva mais recente do projeto de script.
em vez da versão implantada mais recentemente. Faça isso definindo o
O booleano devMode
na
corpo da solicitação
para true
. Somente o proprietário do script pode executá-lo no modo de desenvolvimento.
Como gerenciar tipos de dados de parâmetro
Como usar a API Apps Script
Método scripts.run
geralmente envolve o envio de dados para o Apps Script como parâmetros de função e
para recuperar dados como valores de retorno da função. A API só pode pegar e retornar
com tipos básicos: strings, matrizes, objetos, números e booleanos. Esses
são semelhantes aos tipos básicos em JavaScript. Mais complexo
Objetos do Apps Script, como Document
ou Página não pode ser transmitida para
ou do projeto de script pela API.
Quando seu aplicativo de chamada é escrito em uma linguagem de tipo forte, como
Java, ele passa parâmetros como uma lista ou matriz de objetos genéricos
correspondentes a esses tipos básicos. Em muitos casos, você pode aplicar
de tipos de conversão automaticamente. Por exemplo, uma função que usa um número
pode receber um objeto Java Double
, Integer
ou Long
como um
sem processamento extra.
Quando a API retorna a resposta da função, muitas vezes é necessário transmitir o retornado para o tipo correto antes de poder ser usado. Confira alguns Exemplos baseados em Java:
- Os números retornados pela API a um aplicativo Java chegam como
java.math.BigDecimal
e pode precisar ser convertido emDoubles
ouint
, conforme necessário. Se a função do Apps Script retornar uma matriz de strings, um aplicativo Java transmite a resposta em um objeto
List<String>
:List<String> mylist = (List<String>)(op.getResponse().get("result"));
Se você quiser retornar uma matriz de
Bytes
, isso pode ser conveniente para codificar a matriz como uma string base64 na função do Apps Script e retornar essa string:return Utilities.base64Encode(myByteArray); // returns a String.
Os exemplos de código abaixo ilustram formas de a interpretar a resposta da API.
Procedimento geral
Veja a seguir o procedimento geral para usar a API Apps Script para executar funções do Apps Script:
Etapa 1: configurar o projeto comum do Cloud
O script e o aplicativo de chamada precisam compartilhar o mesmo do Google Cloud. Esse projeto do Cloud pode ser um projeto atual ou um novo projeto criado com essa finalidade. Depois de criar um projeto do Cloud, precisa trocar seu projeto de script para usá-lo.
Etapa 2: implantar o script como um executável de API
- Abra o projeto do Apps Script com as funções que você quer usar.
- No canto superior direito, clique em Implantar > Nova implantação.
- Na caixa de diálogo exibida, clique em Ativar tipos de implantação
. > Executável da API.
- Na página "Quem pode acessar", no menu suspenso, selecione os usuários que podem chamar as funções do script usando a API Apps Script.
- Clique em Implantar.
Etapa 3: configurar o aplicativo de chamada
O aplicativo de chamada precisa ativar a API Apps Script e estabelecer o OAuth crenderais antes de serem usados. Você precisa ter acesso ao projeto do Cloud para fazer isso.
- Configure o projeto do Cloud usado pelo aplicativo e script de chamada. Para isso, siga estas etapas:
- Abra o projeto de script e, à esquerda, clique em Visão geral
.
- Em Escopos Oauth do projeto, registre todos os escopos pelo script.
No código do aplicativo de chamada, gere um script de token de acesso OAuth para a chamada de API. Não é um token que a própria API usa, mas um dos que o script exige ao executar. Ele precisa ser criado usando O ID do cliente do projeto do Google Cloud e os escopos do script que você registrou.
As bibliotecas de cliente do Google podem ajudar bastante ajudar na criação desse token e no tratamento do OAuth para o aplicativo, permitindo que você crie "credenciais" de nível mais alto objeto usando os escopos de script. Consulte a Guias de início rápido da API Apps Script para exemplos de criar um objeto de credenciais usando uma lista de escopos.
Etapa 4: fazer a solicitação script.run
Depois que o aplicativo de chamada estiver configurado, você poderá fazer
chamadas scripts.run
. Cada API
consiste nas seguintes etapas:
- Criar uma solicitação de API usando o ID do script, o nome da função e quaisquer parâmetros.
- Faça a
scripts.run
e inclua o token de script OAuth criado no cabeçalho (se estiver usando uma solicitaçãoPOST
básica) ou então use um objeto de credenciais criados com os escopos do script. - Aguarde a execução do script terminar. Os scripts podem levar até seis minutos de tempo de execução, portanto, seu aplicativo deve permitir isso.
- Ao terminar, a função de script pode retornar um valor, que a API entregará ao aplicativo se o valor for de um tipo compatível.
Veja exemplos de chamadas de API script.run
.
a seguir.
Exemplos de solicitações de API
Os exemplos a seguir mostram como fazer uma solicitação de execução da API Apps Script no
várias linguagens, chamando uma função do Apps Script para imprimir uma lista de
no diretório raiz do usuário. O ID do script do projeto do Apps Script
que contém a função executada deve ser especificado onde for indicado com
ENTER_YOUR_SCRIPT_ID_HERE
: Os exemplos dependem
Bibliotecas de cliente das APIs do Google para as respectivas
idiomas.
Script de destino
A função neste script usa a API Drive.
Você precisa ativar a API Drive no projeto que hospeda o script.
Além disso, os aplicativos de chamada devem enviar credenciais OAuth que incluam o seguinte escopo do Drive:
https://www.googleapis.com/auth/drive
Os aplicativos de exemplo aqui usam bibliotecas de cliente do Google para criar objetos de credencial para OAuth usando este escopo.
/**
* Return the set of folder names contained in the user's root folder as an
* object (with folder IDs as keys).
* @return {Object} A set of folder names keyed by folder ID.
*/
function getFoldersUnderRoot() {
const root = DriveApp.getRootFolder();
const folders = root.getFolders();
const folderSet = {};
while (folders.hasNext()) {
const folder = folders.next();
folderSet[folder.getId()] = folder.getName();
}
return folderSet;
}
Java
/**
* Create a HttpRequestInitializer from the given one, except set
* the HTTP read timeout to be longer than the default (to allow
* called scripts time to execute).
*
* @param {HttpRequestInitializer} requestInitializer the initializer
* to copy and adjust; typically a Credential object.
* @return an initializer with an extended read timeout.
*/
private static HttpRequestInitializer setHttpTimeout(
final HttpRequestInitializer requestInitializer) {
return new HttpRequestInitializer() {
@Override
public void initialize(HttpRequest httpRequest) throws IOException {
requestInitializer.initialize(httpRequest);
// This allows the API to call (and avoid timing out on)
// functions that take up to 6 minutes to complete (the maximum
// allowed script run time), plus a little overhead.
httpRequest.setReadTimeout(380000);
}
};
}
/**
* Build and return an authorized Script client service.
*
* @param {Credential} credential an authorized Credential object
* @return an authorized Script client service
*/
public static Script getScriptService() throws IOException {
Credential credential = authorize();
return new Script.Builder(
HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential))
.setApplicationName(APPLICATION_NAME)
.build();
}
/**
* Interpret an error response returned by the API and return a String
* summary.
*
* @param {Operation} op the Operation returning an error response
* @return summary of error response, or null if Operation returned no
* error
*/
public static String getScriptError(Operation op) {
if (op.getError() == null) {
return null;
}
// Extract the first (and only) set of error details and cast as a Map.
// The values of this map are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements (which also need to
// be cast as Maps).
Map<String, Object> detail = op.getError().getDetails().get(0);
List<Map<String, Object>> stacktrace =
(List<Map<String, Object>>) detail.get("scriptStackTraceElements");
java.lang.StringBuilder sb =
new StringBuilder("\nScript error message: ");
sb.append(detail.get("errorMessage"));
sb.append("\nScript error type: ");
sb.append(detail.get("errorType"));
if (stacktrace != null) {
// There may not be a stacktrace if the script didn't start
// executing.
sb.append("\nScript error stacktrace:");
for (Map<String, Object> elem : stacktrace) {
sb.append("\n ");
sb.append(elem.get("function"));
sb.append(":");
sb.append(elem.get("lineNumber"));
}
}
sb.append("\n");
return sb.toString();
}
public static void main(String[] args) throws IOException {
// ID of the script to call. Acquire this from the Apps Script editor,
// under Publish > Deploy as API executable.
String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE";
Script service = getScriptService();
// Create an execution request object.
ExecutionRequest request = new ExecutionRequest()
.setFunction("getFoldersUnderRoot");
try {
// Make the API request.
Operation op =
service.scripts().run(scriptId, request).execute();
// Print results of request.
if (op.getError() != null) {
// The API executed, but the script returned an error.
System.out.println(getScriptError(op));
} else {
// The result provided by the API needs to be cast into
// the correct type, based upon what types the Apps
// Script function returns. Here, the function returns
// an Apps Script Object with String keys and values,
// so must be cast into a Java Map (folderSet).
Map<String, String> folderSet =
(Map<String, String>) (op.getResponse().get("result"));
if (folderSet.size() == 0) {
System.out.println("No folders returned!");
} else {
System.out.println("Folders under your root folder:");
for (String id : folderSet.keySet()) {
System.out.printf(
"\t%s (%s)\n", folderSet.get(id), id);
}
}
}
} catch (GoogleJsonResponseException e) {
// The API encountered a problem before the script was called.
e.printStackTrace(System.out);
}
}
JavaScript
/**
* Load the API and make an API call. Display the results on the screen.
*/
function callScriptFunction() {
const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>';
// Call the Apps Script API run method
// 'scriptId' is the URL parameter that states what script to run
// 'resource' describes the run request body (with the function name
// to execute)
try {
gapi.client.script.scripts.run({
'scriptId': scriptId,
'resource': {
'function': 'getFoldersUnderRoot',
},
}).then(function(resp) {
const result = resp.result;
if (result.error && result.error.status) {
// The API encountered a problem before the script
// started executing.
appendPre('Error calling API:');
appendPre(JSON.stringify(result, null, 2));
} else if (result.error) {
// The API executed, but the script returned an error.
// Extract the first (and only) set of error details.
// The values of this object are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements.
const error = result.error.details[0];
appendPre('Script error message: ' + error.errorMessage);
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start
// executing.
appendPre('Script error stacktrace:');
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
appendPre('\t' + trace.function + ':' + trace.lineNumber);
}
}
} else {
// The structure of the result will depend upon what the Apps
// Script function returns. Here, the function returns an Apps
// Script Object with String keys and values, and so the result
// is treated as a JavaScript object (folderSet).
const folderSet = result.response.result;
if (Object.keys(folderSet).length == 0) {
appendPre('No folders returned!');
} else {
appendPre('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
appendPre('\t' + folderSet[id] + ' (' + id + ')');
});
}
}
});
} catch (err) {
document.getElementById('content').innerText = err.message;
return;
}
}
Node.js
/**
* Call an Apps Script function to list the folders in the user's root Drive
* folder.
*
*/
async function callAppsScript() {
const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';
const {GoogleAuth} = require('google-auth-library');
const {google} = require('googleapis');
// Get credentials and build service
// TODO (developer) - Use appropriate auth mechanism for your app
const auth = new GoogleAuth({
scopes: 'https://www.googleapis.com/auth/drive',
});
const script = google.script({version: 'v1', auth});
try {
// Make the API request. The request object is included here as 'resource'.
const resp = await script.scripts.run({
auth: auth,
resource: {
function: 'getFoldersUnderRoot',
},
scriptId: scriptId,
});
if (resp.error) {
// The API executed, but the script returned an error.
// Extract the first (and only) set of error details. The values of this
// object are the script's 'errorMessage' and 'errorType', and an array
// of stack trace elements.
const error = resp.error.details[0];
console.log('Script error message: ' + error.errorMessage);
console.log('Script error stacktrace:');
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start executing.
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
console.log('\t%s: %s', trace.function, trace.lineNumber);
}
}
} else {
// The structure of the result will depend upon what the Apps Script
// function returns. Here, the function returns an Apps Script Object
// with String keys and values, and so the result is treated as a
// Node.js object (folderSet).
const folderSet = resp.response.result;
if (Object.keys(folderSet).length == 0) {
console.log('No folders returned!');
} else {
console.log('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
console.log('\t%s (%s)', folderSet[id], id);
});
}
}
} catch (err) {
// TODO(developer) - Handle error
throw err;
}
}
Python
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
def main():
"""Runs the sample."""
# pylint: disable=maybe-no-member
script_id = "1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt"
creds, _ = google.auth.default()
service = build("script", "v1", credentials=creds)
# Create an execution request object.
request = {"function": "getFoldersUnderRoot"}
try:
# Make the API request.
response = service.scripts().run(scriptId=script_id, body=request).execute()
if "error" in response:
# The API executed, but the script returned an error.
# Extract the first (and only) set of error details. The values of
# this object are the script's 'errorMessage' and 'errorType', and
# a list of stack trace elements.
error = response["error"]["details"][0]
print(f"Script error message: {0}.{format(error['errorMessage'])}")
if "scriptStackTraceElements" in error:
# There may not be a stacktrace if the script didn't start
# executing.
print("Script error stacktrace:")
for trace in error["scriptStackTraceElements"]:
print(f"\t{0}: {1}.{format(trace['function'], trace['lineNumber'])}")
else:
# The structure of the result depends upon what the Apps Script
# function returns. Here, the function returns an Apps Script
# Object with String keys and values, and so the result is
# treated as a Python dictionary (folder_set).
folder_set = response["response"].get("result", {})
if not folder_set:
print("No folders returned!")
else:
print("Folders under your root folder:")
for folder_id, folder in folder_set.items():
print(f"\t{0} ({1}).{format(folder, folder_id)}")
except HttpError as error:
# The API encountered a problem before the script started executing.
print(f"An error occurred: {error}")
print(error.content)
if __name__ == "__main__":
main()
Limitações
A API Apps Script tem várias limitações:
Um projeto comum do Cloud. O script que está sendo chamado o aplicativo de chamada precisa compartilhar um projeto do Cloud. O projeto do Cloud precisa ser um projeto padrão do Cloud projetos padrão criados para projetos do Apps Script são insuficientes. A padrão do Cloud pode ser um projeto novo ou existente.
Tipos básicos de parâmetro e retorno. A API não pode transmitir ou retornar objetos específicos do Apps Script (como Documents, Blobs, Agendas, Arquivos do Drive etc.) ao para o aplicativo. Somente tipos básicos como strings, matrizes, objetos, números e booleanos podem ser passados e retornados.
Escopos do OAuth. A API só pode executar scripts que tenham um escopo obrigatório. Isso significa que não é possível usar a API para chamar um script que não requer autorização de um ou mais serviços.
Nenhum acionador. A API não pode criar o Apps Script. acionadores.