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 do dzwonienia, aby zdalnie uruchomić funkcję w jednym z projektów skryptów i otrzymać odpowiedź.

Wymagania

Zanim aplikacja do 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ć, cofać wdrożenie i ponownie wdrażać projekty.

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

  • Upewnij się, że skrypt i klient OAuth2 aplikacji wywołującej korzystają z tego samego projektu Google Cloud. Projekt w chmurze musi być standardowym projektem Google Cloud. 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 API w projekcie Cloud.

Metoda scripts.run

Metoda scripts.run wymaga do działania kluczowych informacji identyfikacyjnych:

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

Obsługa typów danych parametrów

Korzystanie z metody interfejsu API Apps Scriptscripts.run zwykle polega na wysyłaniu danych do Apps Script jako parametrów funkcji i otrzymywaniu danych z powrotem 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. Są one podobne do typów podstawowych w JavaScript. Bardziej złożone obiekty Apps Script, takie jak Document czy Sheet, nie mogą być przekazywane do projektu skryptu ani z niego przez interfejs API.

Gdy aplikacja do dzwonienia jest napisana w języku o silnym typowaniu, np. Java, przekazuje parametry jako listę lub tablicę obiektów ogólnych odpowiadających tym typom podstawowym. W wielu przypadkach możesz automatycznie stosować proste 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 odpowiedni 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 w razie potrzeby mogą wymagać przekształcenia w typy Doubles lub int.
  • Jeśli funkcja Apps Script zwraca tablicę ciągów znaków, aplikacja w Javie rzutuje odpowiedź na obiekt List<String>:

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

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

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

Ogólna procedura

Poniżej opisujemy ogólną procedurę wykonywania funkcji Apps Script przy użyciu interfejsu Apps Script API:

Krok 1. Skonfiguruj wspólny projekt w chmurze

Zarówno skrypt, jak i aplikacja wywołująca muszą korzystać z tego samego projektu w Cloud. Może to być istniejący projekt w Google Cloud lub nowy projekt utworzony w tym celu. Po utworzeniu projektu Cloud musisz przełączyć projekt skryptu, aby go używać.

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  > Wykonywalny plik 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 korzystać z interfejsu Apps Script API, musi go włączyć i ustanowić dane logowania OAuth. Aby to zrobić, musisz mieć dostęp do projektu w Cloud.

  1. Skonfiguruj projekt w Google Cloud, z którego korzystają aplikacja wywołująca i skrypt. Aby to zrobić:
    1. Włącz 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 OAuth projektu zapisz wszystkie zakresy, których skrypt wymaga.
  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 Google Cloud i zakresów skryptu, które zostały przez Ciebie zarejestrowane.

    Biblioteki klienta Google mogą znacznie ułatwić tworzenie tego tokena i obsługę OAuth w aplikacji, zwykle umożliwiając zamiast tego utworzenie obiektu „dane logowania” wyższego poziomu za pomocą zakresów skryptu. Przykłady tworzenia obiektu danych logowania na podstawie listy zakresów znajdziesz w samouczkach wprowadzających do interfejsu Apps Script API.

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

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

  1. Utwórz żądanie interfejsu API za pomocą identyfikatora skryptu, nazwy funkcji i wszystkich wymaganych parametrów.
  2. Wykonaj wywołanie scripts.run i uwzględnij w nagłówku token OAuth skryptu (jeśli używasz podstawowego żądania POST) lub użyj obiektu danych logowania utworzonego za pomocą zakresów skryptu.
  3. Poczekaj, aż skrypt zakończy działanie. 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ługiwanego typu.

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. Identyfikator skryptu projektu Apps Script zawierającego wykonaną funkcję musi być podany w miejscu oznaczonym symbolem ENTER_YOUR_SCRIPT_ID_HERE. Przykłady korzystają z bibliotek klienta interfejsów 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 znajduje się skrypt.

Dodatkowo 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 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

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

Ograniczenia

Interfejs Apps Script API ma kilka ograniczeń:

  1. Wspólny projekt Cloud Wywoływany skrypt i aplikacja wywołująca muszą współdzielić projekt 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. Podstawowe typy parametrów i wartości zwracanych Interfejs API nie może przekazywać ani zwracać obiektów specyficznych dla Apps Script (takich jak Dokumenty, obiekty Blob, Kalendarze, pliki na Dysku itp.) 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 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.