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 do wykonywania połączeń, 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, 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łowo określony token OAuth do 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.
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. Projekty domyślne utworzone dla projektów Apps Script są niewystarczające. Możesz użyć nowego standardowego projektu w chmurze lub istniejącego.
Włącz interfejs Google Apps Script API w projekcie w chmurze.
Metoda scripts.run
Metoda scripts.run wymaga tych informacji:
- Identyfikator projektu skryptu.
- Nazwa funkcji do wykonania.
- Lista parametrów wymaganych przez funkcję (jeśli takie istnieją).
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 wersja. Aby to zrobić, ustaw wartość logiczną devMode w treści żądania na true. Tylko właściciel skryptu może go uruchomić w trybie deweloperskim.
Obsługa typów danych parametrów
Korzystanie z metody interfejsu Apps Script APIscripts.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. 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 wywołująca 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ć konwersje typu. 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.BigDecimali mogą wymagać przekształcenia na typyDoublelubint. Jeśli funkcja Apps Script zwraca tablicę ciągów znaków, aplikacja Java przekształca odpowiedź w 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łady 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ą być w tym samym projekcie w chmurze. Może to być istniejący projekt lub nowy projekt utworzony w tym celu. Po utworzeniu projektu w chmurze musisz przełączyć projekt skryptu, aby go używać.
Krok 2. Wdróż skrypt jako plik wykonywalny interfejsu API
- Otwórz projekt Apps Script z funkcjami, których chcesz używać.
- W prawym górnym rogu kliknij Wdróż > Nowe wdrożenie.
- W otwartym oknie kliknij Włącz typy wdrożenia
> Plik wykonywalny interfejsu API.
- W menu „Kto ma dostęp” wybierz użytkowników, którzy mogą wywoływać funkcje skryptu za pomocą interfejsu Apps Script API.
- Kliknij Wdróż.
Krok 3. Skonfiguruj aplikację do wykonywania połączeń
Aplikacja wywołująca musi przed użyciem włączyć interfejs Apps Script API i ustanowić dane logowania OAuth. Aby to zrobić, musisz mieć dostęp do projektu w chmurze.
- Skonfiguruj projekt w chmurze, z którego korzysta aplikacja wywołująca i skrypt:
- Otwórz projekt skryptu i po lewej stronie kliknij Przegląd
.
- W sekcji Zakresy OAuth projektu zapisz wszystkie zakresy, których skrypt wymaga.
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 zakresów skryptu, które zostały przez Ciebie zarejestrowane.
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 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 scripts.run
Po skonfigurowaniu aplikacji do dzwonienia możesz wykonywać połączenia:scripts.run
- Utwórz żądanie do interfejsu API za pomocą identyfikatora skryptu, nazwy funkcji i wszystkich wymaganych parametrów.
- Wykonaj wywołanie
scripts.runi uwzględnij w nagłówku token OAuth skryptu (jeśli używasz podstawowego żądaniaPOST) lub użyj obiektu danych logowania utworzonego za pomocą zakresów skryptu. - Poczekaj, aż skrypt zakończy działanie. Skrypty mogą działać do 6 minut, więc aplikacja powinna to uwzględniać.
- 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.
Przykłady wywołań interfejsu API znajdziesz w sekcji poniżej.scripts.run
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, która wyświetla 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.
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
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:
Wspólny projekt w chmurze Wywoływany skrypt i aplikacja wywołująca muszą należeć do tego samego projektu w chmurze. Projekt w chmurze musi być standardowym projektem w chmurze. Projekty domyślne utworzone dla projektów Apps Script nie wystarczą.
Podstawowe typy parametrów i wartości zwracanych Interfejs API nie może przekazywać ani zwracać do aplikacji obiektów specyficznych dla Apps Script (takich jak Dokumenty, obiekty Blob, Kalendarze, pliki na Dysku itp.). Można przekazywać i zwracać tylko typy podstawowe, takie jak ciągi znaków, tablice, obiekty, liczby i wartości logiczne.
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ływania skryptu, który nie wymaga autoryzacji co najmniej 1 usługi.
Brak reguł Interfejs API nie może tworzyć reguł Apps Script.