Method: scripts.run

Uruchamia funkcję w projekcie Apps Script. Aby można było używać interfejsu Apps Script API, projekt skryptu musi być wdrożony, a aplikacja wywołująca musi współdzielić ten sam projekt Cloud Platform.

Ta metoda wymaga autoryzacji przy użyciu tokena OAuth 2.0 zawierającego co najmniej jeden z zakresów wymienionych w sekcji Autoryzacja. projektów skryptów, które nie wymagają autoryzacji, nie można uruchamiać za pomocą tego interfejsu API. Aby znaleźć odpowiednie zakresy do uwzględnienia w tokenie uwierzytelniania, otwórz stronę Przegląd projektu skryptu i przewiń w dół do sekcji „Zakresy protokołu OAuth projektu”.

Błąd 403, PERMISSION_DENIED: The caller does not have permission oznacza, że projekt Cloud Platform użyty do autoryzacji żądania różni się od projektu używanego przez skrypt.

Żądanie HTTP

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
scriptId

string

Identyfikator skryptu, który ma zostać wykonany. Identyfikator skryptu znajdziesz na stronie Ustawienia projektu w sekcji „Identyfikatory”.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Pola
function

string

Nazwa funkcji, która ma zostać wykonana w danym skrypcie. Nazwa nie zawiera nawiasów ani parametrów. Może odwoływać się do funkcji w uwzględnionej bibliotece, np. Library.libFunction1.
parameters[]

value (Value format)

Parametry, które mają zostać przekazane do wykonywanej funkcji. Typ obiektu każdego parametru powinien być zgodny z oczekiwanym typem w Apps Script. Parametry nie mogą być typami obiektów typowych dla Apps Script (takich jak Document czy Calendar). mogą to być tylko typy podstawowe, takie jak string, number, array, object lub boolean. Opcjonalnie:
sessionState

string

Wycofano. Do użytku tylko z dodatkami na Androida. Identyfikator reprezentujący bieżącą sesję użytkownika Dokumentów lub Arkuszy Google w aplikacji na Androida, który jest uwzględniony jako dodatkowe dane w intencji uruchamiającej dodatek. Gdy dodatek na Androida jest uruchamiany w stanie sesji, uzyskuje uprawnienia do skryptu powiązanego – to znaczy, że może uzyskać dostęp do informacji takich jak bieżąca pozycja kursora użytkownika (w Dokumentach) lub wybrana komórka (w Arkuszach). Aby pobrać stan, wywołaj Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Opcjonalnie:
devMode

boolean

Jeśli właścicielem skryptu jest true, a użytkownik jest jego właścicielem, skrypt zostanie uruchomiony w najnowszej zapisanej wersji, a nie w wersji wdrożonej na potrzeby interfejsu Apps Script API. Opcjonalnie; domyślna wartość to false.

Treść odpowiedzi

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Prezentacja wykonania funkcji Apps Script rozpoczętej przez run. Odpowiedź wykonania nie przychodzi, dopóki funkcja nie zakończy wykonywania. Maksymalne środowisko wykonawcze znajdziesz w przewodniku po limitach Apps Script.

Po rozpoczęciu może to przynieść jeden z 4 wyników:

  • Jeśli funkcja skryptu zwraca się prawidłowo, pole response zawiera obiekt ExecutionResponse z wartością zwrotną funkcji w polu result obiektu.
  • Jeśli funkcja skryptu (lub sama Apps Script) zgłosi wyjątek, pole error zawiera obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który dostarcza informacji o charakterze błędu.
  • Jeśli wykonanie nie zostało jeszcze ukończone, pole done zawiera wartość false, a pola response i error nie są obecne.
  • Jeśli samo wywołanie run zakończy się niepowodzeniem (na przykład z powodu nieprawidłowego formatu żądania lub błędu autoryzacji), metoda zwróci kod odpowiedzi HTTP z zakresu 4XX z innym formatem treści odpowiedzi. Biblioteki klienta automatycznie konwertują odpowiedź 4XX na klasę wyjątku.

Zapis JSON 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Pola
done

boolean

To pole informuje, czy wykonywanie skryptu zostało zakończone. Ukończone wykonanie ma wypełnione pole response zawierające funkcję ExecutionResponse z wykonanej funkcji.
Pole sumy result. Wynik operacji, którym może być error lub prawidłowy response. Jeśli done == false, nie ustawiono error ani response. Jeśli done == true, może być ustawione dokładnie jedna z tych wartości: error lub response. Niektóre usługi mogą nie dawać oczekiwanych rezultatów. result może mieć tylko jedną z tych wartości:
error

object (Status)

Jeśli wywołanie run powiedzie się, ale funkcja skryptu (lub sam Apps Script) zgłosi wyjątek, to pole zawiera obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który dostarcza informacji o charakterze błędu.
response

object

Jeśli funkcja skryptu zostanie zwrócona, to pole będzie zawierać obiekt ExecutionResponse z wartością zwrotną tej funkcji.

Obiekt zawierający pola dowolnego typu. Dodatkowe pole "@type" zawiera identyfikator URI identyfikujący typ. Przykład: { "id": 1234, "@type": "types.example.com/standard/id" }.

Zakresy autoryzacji

Wymaga jednego z tych zakresów protokołu OAuth:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Więcej informacji znajdziesz w artykule Omówienie protokołu OAuth 2.0.

Stan

Jeśli wywołanie run zakończy się powodzeniem, ale funkcja skryptu (lub sama aplikacja Apps Script) zgłosi wyjątek, pole error w treści odpowiedzi będzie zawierać ten obiekt Status.

Zapis JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Pola
code

integer

Kod stanu. W przypadku tego interfejsu API ta wartość:

  • 10, co oznacza błąd SCRIPT_TIMEOUT,
  • 3, co oznacza błąd INVALID_ARGUMENT lub
  • 1, co oznacza wykonanie CANCELLED.
message

string

komunikat o błędzie widoczny dla dewelopera (w języku angielskim). Każdy komunikat o błędzie widoczny dla użytkowników jest lokalizowany i wysyłany w polu details lub przez klienta.
details[]

object

Tablica z pojedynczym obiektem ExecutionError, który dostarcza informacje o charakterze błędu.

Obiekt zawierający pola dowolnego typu. Dodatkowe pole "@type" zawiera identyfikator URI identyfikujący typ. Przykład: { "id": 1234, "@type": "types.example.com/standard/id" }.