Wykonywanie funkcji przy użyciu interfejsu Apps Script API

Interfejs Google Apps Script API udostępnia metodę scripts.run, która zdalnie wykonuje określoną funkcję Apps Script. Możesz użyć tej metody w aplikacji wywołującej, aby zdalnie uruchomić funkcję w jednym ze swoich projektów skryptów i otrzymać odpowiedź.

Wymagania

Zanim aplikacja do wykonywania połączeń będzie mogła używać metody scripts.run, musi spełniać te wymagania: Musisz:

  • Wdróż projekt skryptu jako plik wykonywalny interfejsu API. W razie potrzeby możesz wdrażać, wycofywać i ponownie wdrażać projekty.

  • Podaj token OAuth o odpowiednim zakresie do wykonania. Ten token OAuth musi obejmować wszystkie zakresy używane przez skrypt, a nie tylko te używane przez wywoływaną funkcję. Pełną listę zakresów autoryzacji znajdziesz w opisie metody.

  • Sprawdź, czy skrypt i klient OAuth2 aplikacji wywołującej należą do tego samego projektu Google Cloud. Projekt w chmurze musi być standardowym projektem w chmurze; domyślne projekty utworzone dla projektów Apps Script nie wystarczą. Możesz użyć nowego standardowego projektu Cloud lub istniejącego.

  • Włącz interfejs Google Apps Script APIw projekcie Cloud.

Metoda scripts.run

Aby uruchomić metodę scripts.run, musisz podać kluczowe informacje identyfikacyjne:

Opcjonalnie możesz skonfigurować skrypt tak, aby działał w trybie programistycznym. Ten tryb działa z ostatnią zapisaną wersją projektu skryptu, a nie z ostatnio wdrożonym plikiem. Aby to zrobić, ustaw wartość logiczną devMode w treści żądania na true. Tylko właściciel skryptu może go uruchomić w trybie programistycznym.

Obsługa typów danych parametrów

Korzystanie z metody interfejsu Apps Script API scripts.run zazwyczaj polega na wysyłaniu danych do Apps Script jako parametrów funkcji i odbieraniu danych jako wartości zwracanych przez funkcję. Interfejs API może przyjmować i zwracać tylko wartości o podstawowych typach: ciągi znaków, tablice, obiekty, liczby i wartości logiczne. Te typy są podobne do podstawowych typów w JavaScript. Bardziej złożone obiekty Apps Script, takie jak Document lub Sheet, nie mogą być przekazywane do projektu skryptu za pomocą interfejsu API.

Jeśli wywołująca aplikacja jest napisana w języku o ściśle określonym typie, takim jak Java, przekazuje parametry jako listę lub tablicę obiektów ogólnych odpowiadających tym podstawowym typom. W wielu przypadkach możesz stosować konwersje typu simple automatycznie. Na przykład funkcja, która przyjmuje parametr typu liczba, może otrzymać jako parametr obiekt Java Double lub Integer lub Long bez dodatkowej obsługi.

Gdy interfejs API zwraca odpowiedź funkcji, często trzeba przekształcić zwróconą wartość w odpowiednią, aby można było z niej korzystać. Oto kilka przykładów w języku Java:

  • Liczby zwracane przez interfejs API do aplikacji w Javie są dostarczane jako obiekty java.math.BigDecimal i w razie potrzeby mogą wymagać konwersji na typy Doubles lub int.

  • Jeśli funkcja Apps Script zwraca tablicę ciągów tekstowych, aplikacja w Javie zamienia odpowiedź na obiekt List<String>:

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

  • Jeśli chcesz zwrócić tablicę Bytes, możesz ją zakodować w formacie base64 w ramach funkcji Apps Script i zamiast tego zwrócić ten ciąg znaków:

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

Przykładowe fragmenty kodu poniżej pokazują sposoby interpretowania odpowiedzi interfejsu API.

Procedura ogólna

Poniżej opisujemy ogólną procedurę korzystania z interfejsu Apps Script API do wykonywania funkcji Apps Script:

Krok 1. Skonfiguruj wspólny projekt Cloud

Zarówno skrypt, jak i aplikacja wywołująca muszą mieć ten sam projekt w Cloud. Może to być istniejący projekt lub nowy projekt utworzony w tym celu. Gdy masz już projekt Cloud, musisz przełączyć projekt skryptu, aby go użyć.

Krok 2. Wdróż skrypt jako plik wykonywalny interfejsu API

  1. Otwórz projekt Apps Script z funkcjami, których chcesz użyć.
  2. W prawym górnym rogu kliknij Wdróż > Nowe wdrożenie.
  3. W wyświetlonym oknie kliknij Włącz typy wdrożenia  > Plik wykonywalny interfejsu API.
  4. W menu „Kto ma dostęp” wybierz użytkowników, którzy mogą wywoływać funkcje skryptu za pomocą interfejsu Apps Script API.
  5. Kliknij Wdróż.

Krok 3. Skonfiguruj aplikację do wykonywania połączeń

Zanim aplikacja wywołująca będzie mogła być używana, musi włączyć interfejs Apps Script API i utworzyć poświadczenia OAuth. Musisz mieć dostęp do projektu Cloud.

  1. Skonfiguruj projekt Cloud, którego używa aplikacja wywołująca i skrypt. Aby to zrobić, wykonaj te czynności:
    1. Włącz interfejs Apps Script API w projekcie Cloud.
    2. Skonfiguruj ekran zgody OAuth.
    3. Utwórz dane logowania OAuth.
  2. Otwórz projekt skryptu i po lewej stronie kliknij Przegląd .
  3. W sekcji Zakresy projektu OAuth zapisz wszystkie zakresy wymagane przez skrypt.

  4. W kodzie wywoływanej aplikacji wygeneruj skryptowy token dostępu OAuth do wywołania interfejsu API. To nie jest token używany przez interfejs API, ale token wymagany przez skrypt podczas wykonywania. Należy go utworzyć, używając identyfikatora klienta projektu Cloud i zapisanych zakresów skryptu.

    Biblioteki klientów Google mogą znacznie ułatwić tworzenie tego tokena i obsługę OAuth w aplikacji. Zazwyczaj umożliwiają tworzenie obiektu „credentials” wyższego poziomu za pomocą zakresów skryptu. Przykłady tworzenia obiektu danych logowania na podstawie listy zakresów znajdziesz w artykule [EN] Wprowadzenie do interfejsu Apps Script API.

Krok 4. Prześlij prośbę o script.run

Po skonfigurowaniu aplikacji do wykonywania połączeń możesz wykonywać połączenia scripts.run. Każde wywołanie interfejsu API składa się z tych kroków:

  1. Utwórz żądanie interfejsu API, używając identyfikatora skryptu, nazwy funkcji i wymaganych parametrów.
  2. Wykonaj wywołanie scripts.run, dołączając w nagłówku token OAuth skryptu utworzony przez siebie (jeśli używasz podstawowego żądania POST) lub używając obiektu danych uwierzytelniających utworzonego z zakresami skryptu.
  3. Poczekaj na zakończenie działania skryptu. Skrypty mogą być wykonywane przez maksymalnie 6 minut, więc aplikacja powinna to uwzględniać.
  4. Po zakończeniu działania funkcja skryptu może zwrócić wartość, którą interfejs API przekazuje z powrotem do aplikacji, jeśli jest ona obsługiwana.

Poniżej znajdziesz przykłady wywołań interfejsu API script.run.

Przykłady żądań do interfejsu API

Poniższe przykłady pokazują, jak wysłać żądanie wykonania interfejsu Apps Script API w różnych językach, wywołując funkcję Apps Script, aby wydrukować listę folderów w katalogu głównym użytkownika. W miejscu wskazanym przez ENTER_YOUR_SCRIPT_ID_HERE musisz podać identyfikator skryptu projektu Apps Script, który zawiera wykonywaną funkcję. Przykłady korzystają z bibliotek klienta interfejsu API Google w odpowiednich językach.

Skrypt docelowy

Funkcja w tym skrypcie korzysta z interfejsu Drive API.

Musisz włączyć interfejs Drive API w projekcie, w którym hostowany jest skrypt.

Dodatkowo aplikacje wywołujące muszą przesyłać dane logowania OAuth, które obejmują ten zakres Dysku:

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

Przykładowe aplikacje używają bibliotek klienta Google do tworzenia obiektów danych logowania OAuth za pomocą tego zakresu.

/**
 * 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

Ograniczenia

Interfejs Apps Script API ma kilka ograniczeń:

  1. Wspólny projekt Cloud. Skrypt, który jest wywoływany, i aplikacja wywołująca muszą należeć do tego samego projektu Cloud. Projekt w chmurze musi być standardowym projektem w chmurze; domyślne projekty utworzone dla projektów Apps Script nie wystarczą. Standardowy projekt Cloud może być nowym lub istniejącym projektem.

  2. Typy podstawowych parametrów i zwracanych wartości. Interfejs API nie może przekazywać ani zwracać obiektów specyficznych dla Apps Script (takich jak Dokumenty, Bloby, Kalendarze czy Pliki Dysku) do aplikacji. Można przekazywać i zwracać tylko typy podstawowe, takie jak ciągi znaków, tablice, obiekty, liczby i wartości logiczne.

  3. Zakresy protokołu OAuth. Interfejs API może wykonywać tylko skrypty, które mają co najmniej jeden wymagany zakres. Oznacza to, że nie możesz używać interfejsu API do wywołania skryptu, który nie wymaga autoryzacji co najmniej 1 usługi.

  4. Brak reguł.Interfejs API nie może tworzyć reguł Apps Script.