Funktionen mit der Apps Script API ausführen

Die Google Apps Script API bietet eine Methode scripts.run das eine bestimmte Apps Script-Funktion remote ausführt. Sie können diese Methode verwenden, in einer aufrufenden Anwendung, um eine Funktion in einem Ihrer Skriptprojekte auszuführen und eine Antwort erhalten.

Voraussetzungen

Sie müssen die folgenden Anforderungen erfüllen, bevor eine aufrufende Anwendung Folgendes verwenden kann: scripts.run . 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 Bereiche abdecken. die vom Skript verwendet werden, nicht nur diejenigen, die von der aufgerufenen Funktion verwendet werden. Weitere Informationen finden Sie in der Vollständige Liste der Autorisierungsbereiche in der Methodenreferenz.

  • Stellen Sie sicher, dass das Skript und die Berechtigung von OAuth2 der aufrufenden Anwendung Client ein gemeinsames Google Cloud-Projekt teilen. 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.

  • Google Apps Script API aktivieren im Cloud-Projekt.

Die Methode scripts.run

Die scripts.run benötigt zum Ausführen wichtige Informationen zur Identifizierung:

Sie können Ihr Skript optional für die Ausführung im Entwicklungsmodus konfigurieren. Dieser Modus wird mit der zuletzt gespeicherten Version des Skriptprojekts ausgeführt und nicht auf die zuletzt bereitgestellte Version. Legen Sie dazu die Einstellung Boolescher Wert devMode in der Anfragetext an true. Nur der Eigentümer des Skripts kann es im Entwicklungsmodus ausführen.

Parameterdatentypen verarbeiten

Apps Script API verwenden Methode scripts.run umfasst in der Regel das Senden von Daten als Funktionsparameter an Apps Script Daten als Funktionsrückgabewerte zurückzubekommen. Die API kann nur -Werten mit Basistypen: Strings, Arrays, Objekte, Zahlen und boolesche Werte. Diese ähneln den Grundtypen in JavaScript. Komplexer Apps Script-Objekte wie Document oder Tabellenblatt kann nicht an oder über die API aus dem Skriptprojekt.

Wenn Ihre aufrufende Anwendung in einer stark typisierten Sprache wie Java, werden Parameter als Liste oder Array generischer Objekte übergeben. die diesen Basistypen entsprechen. In vielen Fällen können Sie einfache automatisch konvertieren. Eine Funktion, die eine Zahl kann ein Java-Double-, Integer- oder Long-Objekt als ohne zusätzliche Behandlung.

Wenn die API die Funktionsantwort zurückgibt, müssen Sie häufig den auf den richtigen Typ zurückgegeben, bevor er verwendet werden kann. Hier sind einige Java-basierte Beispiele:

  • Von der API an eine Java-Anwendung zurückgegebene Zahlen kommen als java.math.BigDecimal-Objekten und müssen möglicherweise konvertiert werden in Doubles- oder int-Typen nach Bedarf.

  • Wenn die Apps Script-Funktion ein Array von Zeichenfolgen zurückgibt, wandelt die Antwort in ein List<String>-Objekt um:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));

  • Wenn Sie ein Array von Bytes zurückgeben möchten, kann dies praktisch sein. um das Array in der Apps Script-Funktion als base64-String zu codieren und diesen String zurückgeben:

    return Utilities.base64Encode(myByteArray); // returns a String.

Die Codebeispiele unten zeigen Möglichkeiten, Interpretieren der API-Antwort.

Allgemeines Verfahren

Im Folgenden wird das allgemeine Verfahren zur Verwendung der Apps Script API beschrieben. zum Ausführen von Apps Script-Funktionen:

Schritt 1: Gemeinsames Cloud-Projekt einrichten

Das Skript und die aufrufende Anwendung müssen Cloud-Projekt Dieses Cloud-Projekt kann ein vorhandenes Projekt sein oder ein neues zu diesem Zweck erstelltes Projekt erstellen. Sobald Sie ein Cloud-Projekt haben, müssen Sie das Skriptprojekt umstellen, um es verwenden zu können.

Schritt 2: Skript als ausführbare API bereitstellen

  1. Öffnen Sie das Apps Script-Projekt mit den Funktionen, die Sie verwenden möchten.
  2. Klicken Sie rechts oben auf Bereitstellen &gt; Neues Deployment.
  3. Klicken Sie im Dialogfeld, das geöffnet wird, auf „Bereitstellungstypen aktivieren“ . &gt; Ausführbare API.
  4. Wählen Sie im Feld „Wer hat Zugriff?“ und wählen Sie die Nutzer aus, dürfen die Funktionen des Skripts mit der Apps Script API aufrufen.
  5. Klicken Sie auf Bereitstellen.

Schritt 3: Aufrufende Anwendung konfigurieren

Die aufrufende Anwendung muss die Apps Script API aktivieren und OAuth einrichten. Anmeldedaten, bevor sie verwendet werden können. Sie benötigen Zugriff auf das Cloud-Projekt um dies zu tun.

  1. Konfigurieren Sie das Cloud-Projekt, das die aufrufende Anwendung und das Skript verwenden. Führen Sie dazu die folgenden Schritte aus: <ph type="x-smartling-placeholder">
      </ph>
    1. Aktivieren Sie die Apps Script API im Cloud-Projekt.
    2. Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
    3. OAuth-Anmeldedaten erstellen
  2. Öffnen Sie das Skriptprojekt und klicken Sie links auf Übersicht .
  3. Notieren Sie sich unter OAuth-Bereiche des Projekts alle Bereiche, Script erfordert.

  4. Generieren Sie im Code der aufrufenden Anwendung ein OAuth-Zugriffstoken für das Skript. für den API-Aufruf. Dies ist kein Token, das von der API selbst verwendet wird, sondern eines der das bei der Ausführung des Skripts erforderlich ist. Sie sollte mithilfe der Cloud-Projekt-Client-ID und die aufgezeichneten Skriptbereiche

    Die Google-Clientbibliotheken können beim Erstellen dieses Tokens und bei der Verarbeitung von OAuth für die Anwendung, in der Regel die Erstellung übergeordneter "Anmeldedaten". Objekt mit den Skriptbereichen. Weitere Informationen finden Sie in der Kurzanleitungen zur Apps Script API mit Beispielen wie man ein Anmeldedatenobjekt aus einer Liste von Bereichen erstellt.

Schritt 4: script.run-Anfrage stellen

Sobald die aufrufende Anwendung konfiguriert ist, können Sie scripts.run Aufrufe Jede API besteht aus den folgenden Schritten:

  1. Erstellen Sie eine API-Anfrage. die Skript-ID, den Funktionsnamen und alle erforderlichen Parameter.
  2. Machen Sie die scripts.run rufen Sie das OAuth-Token des Skripts auf und fügen Sie es ein, (bei einfachen POST-Anfragen) oder ein Anmeldedatenobjekt verwenden die Sie mit den Skriptbereichen erstellt haben.
  3. Warte, bis die Skriptausführung abgeschlossen ist. Skripts dürfen bis zu eine Ausführungszeit von sechs Minuten, also sollte Ihre Anwendung dies zulassen.
  4. Nach Abschluss des Vorgangs kann die Skriptfunktion einen Wert zurückgeben, den die API an die Anwendung zurückgegeben, wenn der Wert ein unterstützter Typ ist.

Hier finden Sie Beispiele für script.run API-Aufrufe. weiter unten.

Beispiele für API-Anfragen

Die folgenden Beispiele zeigen, wie eine Apps Script API-Ausführungsanfrage in und eine Apps Script-Funktion aufrufen, um eine Liste Ordner im Stammverzeichnis des Nutzers. Die Skript-ID des Apps Script-Projekts , die die ausgeführte Funktion enthält, muss an der Stelle angegeben werden, an der durch ENTER_YOUR_SCRIPT_ID_HERE Die Beispiele basieren auf dem 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 aktivieren in der das das Skript hostet.

Außerdem müssen aufrufende Anwendungen OAuth-Anmeldedaten senden, die folgende Elemente enthalten: Drive-Bereich:

  • https://www.googleapis.com/auth/drive

Die Beispielanwendungen hier erstellen mithilfe der Google-Clientbibliotheken Anmeldedatenobjekte für OAuth, die diesen Bereich verwenden.

/**
 * 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;
}
target.js

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);
  }
}
Execute.java

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;
  }
}

index.js

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;
  }
}
index.js

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()
execute.py

Beschränkungen

Die Apps Script API unterliegt mehreren Einschränkungen:

  1. Ein gemeinsames Cloud-Projekt. Das aufgerufene Skript und die aufrufende Anwendung muss ein Cloud-Projekt gemeinsam nutzen. Das Cloud-Projekt muss ein Cloud-Standardprojekt; Für Apps Script-Projekte erstellte Standardprojekte sind unzureichend. Die Das Cloud-Standardprojekt kann ein neues oder ein vorhandenes Projekt sein.

  2. Grundlegende Parameter und Rückgabetypen: Die API kann keine übergebenen oder zurückgeben Apps Script-spezifische Objekte (z. B. Dokumente, Blobs Kalender, Drive-Dateien usw.) in den . Nur Basistypen wie Strings, Arrays, Objekte, Zahlen und können boolesche Werte übergeben und zurückgegeben werden.

  3. OAuth-Bereiche. Die API kann nur Skripts ausführen, die mindestens einen erforderlichen Umfang. Das bedeutet, dass Sie die API nicht zum Aufrufen eines Skripts verwenden können. für die keine Autorisierung eines oder mehrerer Dienste erforderlich ist.

  4. Keine Trigger: Mit der API kann kein Apps Script erstellt werden. Trigger