Wykonywanie funkcji za pomocą interfejsu Google Apps Script API

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

Wymagania

Zanim aplikacja wywołująca będzie mogła używać metody scripts.run, musisz:

  • wdrożyć projekt skryptu jako plik wykonywalny interfejsu API. W razie potrzeby możesz wdrażać, cofać wdrożenie i ponownie wdrażać projekty.

  • podać token OAuth z odpowiednim zakresem na potrzeby 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 dokumentacji metody.

  • upewnić się, że skrypt i klient OAuth2 aplikacji wywołującej korzystają z tego samego projektu Google Cloud. Projekt w chmurze musi być standardowym projektem w chmurze; domyślne projekty utworzone na potrzeby projektów Apps Script są niewystarczające. Możesz użyć nowego standardowego projektu w chmurze lub istniejącego.

  • Włączyć interfejs Google Apps Script API w projekcie w chmurze.

Metoda scripts.run

Metoda scripts.run wymaga tych informacji:

Opcjonalnie możesz skonfigurować skrypt tak, aby był wykonywany w trybie programowania. W tym trybie wykonywana jest ostatnio zapisana wersja projektu skryptu, a nie ostatnio wdrożona. Aby to zrobić, ustaw wartość logiczną devMode w treści żądania na true. Tylko właściciel skryptu może go wykonać w trybie programowania.

Obsługa typów danych parametrów

Używanie metody interfejsu Apps Script API scripts.run zwykle wiąże się z wysyłaniem danych do Apps Script jako parametrów funkcji i odbieraniem danych jako wartości zwracanych przez funkcję. Interfejs API może przyjmować i zwracać tylko wartości podstawowych typów: ciągi znaków, tablice, obiekty, liczby i wartości logiczne. Bardziej złożone obiekty Apps Script, takie jak Document lub Sheet, nie mogą być przekazywane do projektu skryptu ani z niego za pomocą interfejsu API.

Gdy aplikacja wywołująca jest napisana w języku o silnym typowaniu, takim jak Java, przekazuje parametry jako listę lub tablicę obiektów ogólnych odpowiadających tym podstawowym typom. W wielu przypadkach możesz automatycznie stosować konwersje typów. Na przykład funkcja, która przyjmuje parametr liczbowy, może otrzymać jako parametr obiekt Java Double, Integer lub Long bez dodatkowej obsługi.

Gdy interfejs API zwraca odpowiedź funkcji, często musisz rzutować zwróconą wartość na prawidłowy typ, zanim będzie można jej użyć. Oto kilka przykładów w języku Java:

  • Liczby zwracane przez interfejs API do aplikacji Java są przekazywane jako obiekty java.math.BigDecimal i mogą wymagać przekonwertowania na typy Double lub int.
  • Jeśli funkcja Apps Script zwraca tablicę ciągów znaków, aplikacja Java rzutuje odpowiedź na obiekt List<String>:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Jeśli chcesz zwrócić tablicę Bytes, zakoduj ją jako ciąg znaków base64 w funkcji Apps Script i zwróć ten ciąg znaków:

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

Poniższe przykładowe fragmenty kodu pokazują, jak interpretować odpowiedź interfejsu API.

Ogólna procedura

Aby użyć interfejsu Apps Script API do wykonywania funkcji Apps Script, wykonaj te czynności:

Krok 1. Skonfiguruj wspólny projekt w chmurze

Zarówno skrypt, jak i aplikacja wywołująca muszą korzystać z tego samego projektu w chmurze. Ten projekt w chmurze może być projektem istniejącym lub nowym utworzonym w tym celu. Gdy masz już projekt w chmurze, musisz przełączyć projekt skryptu na jego używanie.

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

  1. Otwórz projekt Apps Script z funkcjami, których chcesz używać.
  2. W prawym górnym rogu kliknij Wdróż > Nowe wdrożenie.
  3. W otwartym oknie kliknij Włącz typy wdrożeń > 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ę wywołującą

Zanim aplikacja wywołująca będzie mogła używać interfejsu Apps Script API, musi go włączyć i skonfigurować dane logowania OAuth. Aby to zrobić, musisz mieć dostęp do projektu w chmurze.

  1. Skonfiguruj projekt w chmurze, którego używa aplikacja wywołująca i skrypt:
    1. Włącz interfejs Apps Script API w projekcie w chmurze.
    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 OAuth projektu zapisz wszystkie zakresy wymagane przez skrypt.
  4. W kodzie aplikacji wywołującej wygeneruj token dostępu OAuth skryptu na potrzeby wywołania interfejsu API. Nie jest to token używany przez sam interfejs API, ale token wymagany przez skrypt podczas wykonywania. Powinien on być utworzony przy użyciu identyfikatora klienta projektu w chmurze i zapisanych zakresów skryptu.

    Biblioteki klienta Google mogą pomóc w utworzeniu tego tokena i obsłudze OAuth w aplikacji, zwykle umożliwiając utworzenie obiektu „dane logowania” wyższego poziomu przy użyciu zakresów skryptu. Przykłady tworzenia obiektu danych logowania na podstawie listy zakresów znajdziesz w przewodnikach Szybki start interfejsu Apps Script API.

Krok 4. Wyślij żądanie scripts.run

Po skonfigurowaniu aplikacji wywołującej możesz wykonywać scripts.run wywołania:

  1. Utwórz żądanie do interfejsu API przy użyciu identyfikatora wdrożenia, nazwy funkcji i wszystkich wymaganych parametrów.
  2. Wykonaj scripts.run wywołanie i dodaj utworzony token OAuth skryptu w nagłówku (jeśli używasz podstawowego POST żądania) lub użyj obiektu danych logowania utworzonego za pomocą zakresów skryptu.
  3. Poczekaj na zakończenie działania skryptu. Wykonanie skryptów może zająć do 6 minut, więc aplikacja powinna to uwzględniać.
  4. Po zakończeniu skrypt może zwrócić wartość, którą interfejs API przekazuje z powrotem do aplikacji, jeśli jest to obsługiwany typ.

Przykłady wywołań interfejsu API scripts.run znajdziesz w sekcji poniżej.

Aby odświeżyć token dostępu, dodaj ten fragment kodu przed żądaniem do interfejsu API scripts.run:

if (credential.getExpiresInSeconds() <= 360) {
  credential.refreshToken();
}

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. Identyfikator wdrożenia projektu Apps Script zawierającego wykonywaną funkcję musi być podany w miejscu oznaczonym jako ENTER_YOUR_DEPLOYMENT_ID_HERE. Przykłady korzystają z bibliotek klienta Google API.

Skrypt docelowy

Funkcja w tym skrypcie używa interfejsu Drive API.

Musisz włączyć interfejs Drive API w projekcie hostującym skrypt.

Ponadto aplikacje wywołujące muszą wysył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 na potrzeby protokołu OAuth przy użyciu 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;
}

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


import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Calls an Apps Script function to list the folders in the user's root Drive folder.
 */
async function callAppsScript() {
  // The ID of the Apps Script project to call.
  const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';

  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Apps Script API client.
  const script = google.script({version: 'v1', auth});

  const resp = await script.scripts.run({
    auth,
    requestBody: {
      // The name of the function to call in the Apps Script project.
      function: 'getFoldersUnderRoot',
    },
    scriptId,
  });

  if (resp.data.error?.details?.[0]) {
    // The API executed, but the script returned an error.
    // Extract the error details.
    const error = resp.data.error.details[0];
    console.log(`Script error message: ${error.errorMessage}`);
    console.log('Script error stacktrace:');

    if (error.scriptStackTraceElements) {
      // Log the stack trace.
      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 script executed successfully.
    // The structure of the response depends on the Apps Script function's return value.
    const folderSet = resp.data.response ?? {};
    if (Object.keys(folderSet).length === 0) {
      console.log('No folders returned!');
    } else {
      console.log('Folders under your root folder:');
      Object.keys(folderSet).forEach((id) => {
        console.log('\t%s (%s)', folderSet[id], id);
      });
    }
  }
}

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()

Ograniczenia

Interfejs Apps Script API ma te ograniczenia:

  1. Wspólny projekt w chmurze. Wywoływany skrypt i aplikacja wywołująca muszą korzystać z tego samego projektu w chmurze. Projekt w chmurze musi być standardowym projektem w chmurze; domyślne projekty utworzone na potrzeby projektów Apps Script są niewystarczające.

  2. Podstawowe typy parametrów i wartości zwracanych. Interfejs API nie może przekazywać do aplikacji ani zwracać z niej obiektów specyficznych dla Apps Script (takich jak dokumenty, obiekty Blob, kalendarze, pliki na Dysku itp.). Można przekazywać i zwracać tylko podstawowe typy, takie jak ciągi znaków, tablice, obiekty, liczby i wartości logiczne.

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

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