Die Google Apps Script API bietet eine scripts.run
-Methode, die eine bestimmte Apps Script-Funktion remote ausführt. Sie können diese Methode in einer aufrufenden Anwendung verwenden, um eine Funktion in einem Ihrer Skriptprojekte remote 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. Folgende Voraussetzungen müssen erfüllt sein:
Stellen Sie das Skriptprojekt als ausführbare API bereit. Sie können Projekte nach Bedarf bereitstellen, die Bereitstellung rückgängig machen und sie noch einmal bereitstellen.
Geben Sie für die Ausführung ein OAuth-Token mit dem entsprechenden Geltungsbereich an. Dieses OAuth-Token muss alle vom Skript verwendeten Bereiche abdecken, nicht nur die, die von der aufgerufenen Funktion verwendet werden. Eine vollständige Liste der Autorisierungsbereiche finden Sie in der Methodenreferenz.
Das Skript und der OAuth2-Client der aufrufenden Anwendung müssen ein gemeinsames Google Cloud-Projekt verwenden. Das Cloud-Projekt muss ein Cloud-Standardprojekt sein. Für Apps Script-Projekte erstellte Standardprojekte reichen nicht aus. Sie können ein neues Cloud-Standardprojekt oder ein vorhandenes Projekt verwenden.
Aktivieren Sie die Google Apps Script API im Cloud-Projekt.
Die Methode scripts.run
Zum Ausführen der Methode scripts.run
sind wichtige Informationen zur Identifizierung erforderlich:
- Die ID des Skriptprojekts.
- Der Name der auszuführenden Funktion.
- Die Liste der Parameter, die die Funktion benötigt (falls vorhanden).
Optional können Sie Ihr Skript für die Ausführung im Entwicklungsmodus konfigurieren.
Dieser Modus wird mit der zuletzt gespeicherten Version des Skriptprojekts ausgeführt und nicht mit der zuletzt bereitgestellten Version. Setzen Sie dazu den booleschen Wert devMode
im Anfragetext auf true
. Nur der Eigentümer des Skripts kann es im Entwicklungsmodus ausführen.
Parameterdatentypen verarbeiten
Wenn Sie die Methode scripts.run
der Apps Script API verwenden, 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. Diese ähneln den grundlegenden Typen in JavaScript. Komplexere Apps Script-Objekte wie Document oder Sheet können von der API nicht in das oder aus dem Skriptprojekt übergeben werden.
Wenn Ihre aufrufende Anwendung in einer stark typisierten Sprache wie Java geschrieben ist, übergibt sie Parameter als eine Liste oder ein Array generischer Objekte, die diesen grundlegenden Typen entsprechen. In vielen Fällen können Sie einfache
Conversion-Typen automatisch anwenden. Beispielsweise kann einer Funktion, die einen Zahlenparameter verwendet, ein Java-Objekt Double
, Integer
oder Long
als Parameter zugewiesen werden, ohne dass zusätzliche Maßnahmen erforderlich sind.
Wenn die API die Funktionsantwort zurückgibt, müssen Sie den zurückgegebenen Wert häufig in den richtigen Typ umwandeln, bevor er verwendet werden kann. Hier sind einige Java-basierte Beispiele:
- Zahlen, die von der API an eine Java-Anwendung zurückgegeben werden, kommen als
java.math.BigDecimal
-Objekte an und müssen gegebenenfalls in den TypDoubles
oderint
konvertiert werden. Wenn die Apps Script-Funktion ein Array von Strings zurückgibt, wandelt eine Java-Anwendung die Antwort in ein
List<String>
-Objekt um:List<String> mylist = (List<String>)(op.getResponse().get("result"));
Wenn Sie ein
Bytes
-Array zurückgeben möchten, kann es praktisch sein, 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 Beispielcodebeispiele veranschaulichen, wie die API-Antwort interpretiert werden kann.
Allgemeines Verfahren
Im Folgenden wird das allgemeine Verfahren zur Verwendung der Apps Script API zum Ausführen von Apps Script-Funktionen beschrieben:
Schritt 1: Gemeinsames Cloud-Projekt einrichten
Das Skript und die aufrufende Anwendung müssen sich im selben Cloud-Projekt befinden. Dieses Cloud-Projekt kann ein vorhandenes Projekt sein oder ein neues Projekt, das zu diesem Zweck erstellt wurde. Sobald Sie ein Cloud-Projekt haben, müssen Sie das Skriptprojekt wechseln, um es verwenden zu können.
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 > Neues Deployment.
- Klicken Sie im Dialogfeld, das geöffnet wird, auf „Bereitstellungstypen aktivieren“ > API Executable.
- Wählen Sie im Drop-down-Menü „Zugriffsberechtigt“ die Nutzer aus, die die Funktionen des Skripts mit der Apps Script API aufrufen dürfen.
- Klicken Sie auf Bereitstellen.
Schritt 3: Aufrufende Anwendung 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 die aufrufende Anwendung und das Skript verwenden. Gehen Sie dazu so vor:
- Öffnen Sie das Skriptprojekt und klicken Sie links auf Übersicht .
- Notieren Sie unter OAuth-Bereiche des Projekts alle Bereiche, die für das Skript erforderlich sind.
Generieren Sie im aufrufenden Anwendungscode ein OAuth-Zugriffstoken für den API-Aufruf. Dies ist kein Token, das von der API selbst verwendet wird, sondern ein Token, das das Skript für die Ausführung benötigt. Er sollte mit der Client-ID des Cloud-Projekts und den aufgezeichneten Skriptbereichen erstellt werden.
Die Google-Clientbibliotheken können Sie beim Erstellen dieses Tokens und bei der Verarbeitung von OAuth für die Anwendung sehr unterstützen. Sie ermöglichen es Ihnen normalerweise, mithilfe der Skriptbereiche ein übergeordnetes Objekt mit Anmeldedaten zu erstellen. Beispiele zum Erstellen eines Anmeldedatenobjekts aus einer Liste von Bereichen finden Sie in den Kurzanleitungen zur Apps Script API.
Schritt 4: script.run
-Anfrage stellen
Sobald die aufrufende Anwendung konfiguriert ist, können Sie scripts.run
-Aufrufe ausführen. Jeder API-Aufruf umfasst die folgenden Schritte:
- Erstellen Sie eine API-Anfrage mit der Skript-ID, dem Funktionsnamen und allen erforderlichen Parametern.
- Führen Sie den
scripts.run
-Aufruf aus und fügen Sie das OAuth-Token des Skripts, das Sie in den Header erstellt haben (bei einer einfachenPOST
-Anfrage), ein oder verwenden Sie ein Anmeldedatenobjekt, das Sie mit den Skriptbereichen erstellt haben. - Warte, bis die Skriptausführung abgeschlossen ist. Die Ausführung von Skripts kann bis zu sechs Minuten in Anspruch nehmen, also sollte Ihre Anwendung dies zulassen.
- Nach Abschluss des Vorgangs gibt die Skriptfunktion möglicherweise einen Wert zurück, den die API an die Anwendung zurückgibt, wenn der Wert ein unterstützter Typ ist.
Unten finden Sie Beispiele für script.run
-API-Aufrufe.
Beispiele für API-Anfragen
Die folgenden Beispiele zeigen, wie Sie eine Apps Script API-Ausführungsanfrage in verschiedenen Sprachen senden und eine Apps Script-Funktion aufrufen, um eine Liste der Ordner im Stammverzeichnis des Nutzers auszugeben. Die Skript-ID des Apps Script-Projekts, das die ausgeführte Funktion enthält, muss an der Stelle mit ENTER_YOUR_SCRIPT_ID_HERE
angegeben werden. Die Beispiele basieren auf den Google API-Clientbibliotheken für die jeweiligen Sprachen.
Zielskript
Für die Funktion in diesem Skript wird die Drive API verwendet.
Sie müssen die Drive API in dem Projekt aktivieren, das das Skript hostet.
Außerdem müssen aufrufende Anwendungen OAuth-Anmeldedaten senden, die den folgenden Drive-Bereich enthalten:
https://www.googleapis.com/auth/drive
Die Beispielanwendungen hier verwenden die Google-Clientbibliotheken, um Anmeldedatenobjekte für OAuth mit diesem Bereich 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 mehreren Einschränkungen:
Ein gemeinsames Cloud-Projekt. Das aufgerufene Skript und die aufrufende Anwendung müssen gemeinsam ein Cloud-Projekt verwenden. Das Cloud-Projekt muss ein Cloud-Standardprojekt sein. Für Apps Script-Projekte erstellte Standardprojekte reichen nicht aus. Das Cloud-Standardprojekt 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, Drive-Dateien usw.) an die Anwendung übergeben oder zurückgeben. Nur Basistypen wie Strings, Arrays, Objekte, Zahlen und boolesche Werte können übergeben und zurückgegeben werden.
OAuth-Bereiche. Die API kann nur Skripts ausführen, die mindestens einen erforderlichen Bereich haben. Das bedeutet, dass Sie die API nicht verwenden können, um ein Skript aufzurufen, für das keine Autorisierung eines oder mehrerer Dienste erforderlich ist.
Keine Trigger: Mit der API können keine Apps Script-Trigger erstellt werden.