Die Google Apps Script API bietet die Methode scripts.run, mit der eine bestimmte Apps Script-Funktion aus der Ferne ausgeführt wird. Sie können diese Methode in einer aufrufenden Anwendung verwenden, um eine Funktion in einem Ihrer Scriptprojekte aus der Ferne auszuführen und eine Antwort zu erhalten.
Voraussetzungen
Damit eine aufrufende Anwendung die Methode scripts.run verwenden kann, müssen die folgenden Anforderungen erfüllt sein. Sie müssen:
Stellen Sie das Scriptprojekt als ausführbare API bereit. Sie können Projekte bei Bedarf bereitstellen, die Bereitstellung aufheben und Projekte neu bereitstellen.
Geben Sie ein OAuth-Token mit dem richtigen Umfang für die Ausführung an. Dieses OAuth-Token muss alle Umfänge abdecken, die vom Script verwendet werden, nicht nur die, die von der aufgerufenen Funktion verwendet werden. Eine vollständige Liste der Zugriffsbereiche für die Autorisierung finden Sie in der Methodenreferenz.
Das Script und der OAuth2-Client der aufrufenden Anwendung müssen dasselbe Google Cloud-Projekt verwenden. Das Cloud-Projekt muss ein Standard-Cloud-Projekt sein. Standardprojekte, die für Apps Script-Projekte erstellt wurden, reichen nicht aus. Sie können ein neues oder ein vorhandenes Cloud-Standardprojekt verwenden.
Aktivieren Sie die Google Apps Script API im Cloud-Projekt.
Die Methode scripts.run
Für die Ausführung der Methode scripts.run sind wichtige Informationen zur Identifizierung erforderlich:
- Die ID des Scriptprojekts.
- Der Name der Funktion, die ausgeführt werden soll.
- Die Liste der Parameter, die für die Funktion erforderlich sind (falls zutreffend).
Optional können Sie Ihr Script so konfigurieren, dass es im Entwicklungsmodus ausgeführt wird.
In diesem Modus wird die zuletzt gespeicherte Version des Scriptprojekts ausgeführt, nicht die zuletzt bereitgestellte Version. Legen Sie dazu den booleschen Wert devMode im Anfragetext auf true fest. Nur der Inhaber des Scripts kann es im Entwicklungsmodus ausführen.
Umgang mit Parameterdatentypen
Bei der Verwendung der Apps Script API-Methode scripts.run werden in der Regel Daten als Funktionsparameter an Apps Script gesendet und als Funktionsrückgabewerte zurückgegeben. Die API kann nur Werte mit grundlegenden Typen annehmen und zurückgeben: Strings, Arrays, Objekte, Zahlen und Boolesche Werte. Sie ähneln den Grundtypen in JavaScript. Komplexere Apps Script-Objekte wie Document oder Sheet können nicht über die API an das Script-Projekt übergeben oder daraus zurückgegeben werden.
Wenn die aufrufende Anwendung in einer stark typisierten Sprache wie Java geschrieben ist, werden die Parameter als Liste oder Array von generischen Objekten übergeben, die diesen Grundtypen entsprechen. In vielen Fällen können Sie einfache Conversions automatisch anwenden. Beispielsweise kann einer Funktion, die einen Zahlenparameter annimmt, ohne zusätzliche Verarbeitung ein Java-Double-, Integer- oder Long-Objekt als Parameter übergeben werden.
Wenn die API die Funktionsantwort zurückgibt, müssen Sie den zurückgegebenen Wert oft in den richtigen Typ umwandeln, bevor er verwendet werden kann. Hier einige Java-basierte Beispiele:
- Zahlen, die von der API an eine Java-Anwendung zurückgegeben werden, sind
java.math.BigDecimal-Objekte und müssen bei Bedarf inDoubles- oderint-Typen umgewandelt werden. Wenn die Apps Script-Funktion ein Array von Strings zurückgibt, wird die Antwort in einer Java-Anwendung in ein
List<String>-Objekt umgewandelt:List<String> mylist = (List<String>)(op.getResponse().get("result"));Wenn Sie ein Array von
Byteszurückgeben möchten, ist es unter Umständen praktischer, das Array in der Apps Script-Funktion als Base64-String zu codieren und stattdessen diesen String zurückzugeben:return Utilities.base64Encode(myByteArray); // returns a String.
Die folgenden Codebeispiele veranschaulichen Möglichkeiten zur Interpretation der API-Antwort.
Allgemeine Vorgehensweise
Im Folgenden wird der allgemeine Ablauf für die Ausführung von Apps Script-Funktionen mit der Apps Script API beschrieben:
Schritt 1: Gemeinsames Cloud-Projekt einrichten
Sowohl Ihr Script als auch die aufrufende Anwendung müssen sich im selben Cloud-Projekt befinden. Dieses Cloud-Projekt kann ein vorhandenes Projekt oder ein neues Projekt sein, das zu diesem Zweck erstellt wurde. Sobald Sie ein Cloud-Projekt haben, müssen Sie Ihr Scriptprojekt darauf umstellen.
Schritt 2: Skript als ausführbare API bereitstellen
- Öffnen Sie das Apps Script-Projekt mit den Funktionen, die Sie verwenden möchten.
- Klicken Sie rechts oben auf Bereitstellen > Neue Bereitstellung.
- Klicken Sie im sich öffnenden Dialogfeld auf „Bereitstellungstypen aktivieren“
> API-Ausführbare Datei. - Wählen Sie im Drop-down-Menü „Wer hat Zugriff?“ die Nutzer aus, die die Funktionen des Scripts über die Apps Script API aufrufen dürfen.
- Klicken Sie auf Bereitstellen.
Schritt 3: Anrufanwendung konfigurieren
Die aufrufende Anwendung muss die Apps Script API aktivieren und OAuth-Anmeldedaten einrichten, bevor sie verwendet werden kann. Dazu benötigen Sie Zugriff auf das Cloud-Projekt.
- Konfigurieren Sie das Cloud-Projekt, das von Ihrer anrufenden Anwendung und Ihrem Script verwendet wird. Sie können dazu so vorgehen:
- Öffnen Sie das Script-Projekt und klicken Sie links auf Übersicht
. - Geben Sie unter Project Oauth scopes (Oauth-Bereiche des Projekts) alle Bereiche an, die für das Script erforderlich sind.
Erstellen Sie im Code der aufrufenden Anwendung ein OAuth-Script-Zugriffstoken für den API-Aufruf. Dies ist kein Token, das von der API selbst verwendet wird, sondern eines, das das Script bei der Ausführung benötigt. Es sollte mit der Cloud-Projekt-Client-ID und den von Ihnen aufgezeichneten Script-Bereichen erstellt werden.
Die Google-Clientbibliotheken können beim Erstellen dieses Tokens und beim Umgang mit OAuth für die Anwendung sehr hilfreich sein. In der Regel können Sie stattdessen mithilfe der Scriptbereiche ein „Anmeldedaten“-Objekt auf höherer Ebene erstellen. In den Schnellstarts für die Apps Script API finden Sie Beispiele zum Erstellen eines Anmeldedatenobjekts aus einer Liste von Bereichen.
Schritt 4: script.run-Anfrage stellen
Sobald die Anrufanwendung konfiguriert ist, können Sie scripts.run-Anrufe starten. Jeder API-Aufruf besteht aus den folgenden Schritten:
- Erstelle eine API-Anfrage mit der Script-ID, dem Funktionsnamen und allen erforderlichen Parametern.
- Rufe
scripts.runauf und füge das von dir erstellte OAuth-Token für das Script in den Header ein (bei Verwendung einer einfachenPOST-Anfrage) oder verwende ein Anmeldedatenobjekt, das du mit den Script-Bereichen erstellt hast. - Warten Sie, bis die Ausführung des Scripts abgeschlossen ist. Scripts dürfen eine Ausführungszeit von bis zu sechs Minuten haben. Ihre Anwendung sollte dies berücksichtigen.
- Nach Abschluss kann die Scriptfunktion einen Wert zurückgeben, der von der API an die Anwendung zurückgegeben wird, wenn der Wert ein unterstützter Typ ist.
Beispiele für script.run API-Aufrufe finden Sie unten.
Beispiele für API-Anfragen
In den folgenden Beispielen wird gezeigt, wie Sie eine Ausführungsanfrage der Apps Script API in verschiedenen Sprachen stellen und eine Apps Script-Funktion aufrufen, um eine Liste der Ordner im Stammverzeichnis des Nutzers auszugeben. Die Script-ID des Apps Script-Projekts, das die ausgeführte Funktion enthält, muss an der Stelle angegeben werden, an der ENTER_YOUR_SCRIPT_ID_HERE steht. Die Beispiele basieren auf den Google API-Clientbibliotheken für die jeweiligen Sprachen.
Ziel-Script
Die Funktion in diesem Script verwendet die Drive API.
Sie müssen die Drive API in dem Projekt aktivieren, in dem das Script gehostet wird.
Außerdem müssen aufrufende Anwendungen OAuth-Anmeldedaten mit dem folgenden Drive-Bereich senden:
https://www.googleapis.com/auth/drive
In den Beispielanwendungen werden die Google-Clientbibliotheken verwendet, um Anmeldedatenobjekte für OAuth mit diesem Umfang zu erstellen.
/**
* 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()
Beschränkungen
Die Apps Script API unterliegt einigen Einschränkungen:
Ein gängiges Cloud-Projekt Das aufgerufene Script und die aufrufende Anwendung müssen dasselbe Cloud-Projekt verwenden. Das Cloud-Projekt muss ein Standard-Cloud-Projekt sein. Standardprojekte, die für Apps Script-Projekte erstellt wurden, reichen nicht aus. Das Standard-Cloud-Projekt kann ein neues oder ein vorhandenes Projekt sein.
Grundlegende Parameter- und Rückgabetypen Die API kann keine Apps Script-spezifischen Objekte (z. B. Dokumente, Blobs, Kalender oder Drive-Dateien) an die Anwendung übergeben oder zurückgeben. Es können nur einfache Typen wie Strings, Arrays, Objekte, Zahlen und boolesche Werte übergeben und zurückgegeben werden.
OAuth-Bereiche Die API kann nur Scripts ausführen, die mindestens einen erforderlichen Bereich haben. Das bedeutet, dass Sie mit der API kein Script aufrufen können, für das keine Autorisierung für einen oder mehrere Dienste erforderlich ist.
Keine Trigger: Mit der API können keine Apps Script-Trigger erstellt werden.