Method: scripts.run

Uruchamia funkcję w projekcie Apps Script. Aby można było korzystać z interfejsu Apps Script API, trzeba wdrożyć projekt skryptu, a aplikacja wywołująca musi mieć ten sam projekt Cloud Platform.

Ta metoda wymaga autoryzacji za pomocą tokena OAuth 2.0, który zawiera co najmniej jeden z zakresów wymienionych w sekcji Autoryzacja. Projekty skryptu, które nie wymagają autoryzacji, nie mogą być wykonywane przy użyciu tego interfejsu API. Aby znaleźć odpowiednie zakresy do uwzględnienia w tokenie uwierzytelniania, otwórz stronę Overview (Przegląd) projektu skryptu i przewiń w dół do sekcji „Project OAuth Scopes” (Zakresy protokołu OAuth projektu).

Błąd 403, PERMISSION_DENIED: The caller does not have permission wskazuje, że projekt Cloud Platform użyty do autoryzacji żądania różni się od projektu użytego 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 do wykonania. Znajdź identyfikator skryptu 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 do wykonania 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 specyficznymi dla Apps Script (np. Document czy Calendar). Mogą być tylko typami podstawowymi, takimi jak string, number, array, object lub boolean. Opcjonalnie.
sessionState

string

Wycofano. Działa tylko z dodatkami do Androida. Identyfikator reprezentujący bieżącą sesję użytkownika w aplikacji Dokumenty lub Arkusze Google na Androida, umieszczony jako dodatkowe dane w intencji, która uruchamia dodatek. Gdy dodatek na Androida uruchamia się w stanie sesji, uzyskuje uprawnienia skryptu powiązanego – czyli dostęp do informacji takich jak bieżąca pozycja kursora użytkownika (w Dokumentach) lub wybrana komórka (w Arkuszach). Aby pobrać stan, zadzwoń pod numer Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Opcjonalnie.
devMode

boolean

Jeśli właścicielem skryptu jest true, a użytkownik jest właścicielem skryptu, skrypt działa w ostatniej zapisanej wersji, a nie w wersji wdrożonej na potrzeby interfejsu Apps Script API. Opcjonalna, wartość domyślna to false.

Treść odpowiedzi

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

Ilustracja przedstawiająca wykonanie funkcji Apps Script rozpoczynającej się od run. Odpowiedź wykonania nie zostanie dostarczona, dopóki funkcja nie zakończy wykonywania. Maksymalne czas wykonywania znajdziesz w przewodniku po limitach Apps Script.

Po rozpoczęciu realizacji może wystąpić jeden z 4 wyników:

  • Jeśli funkcja skryptu zostanie zwrócona, pole response będzie zawierać obiekt ExecutionResponse z wartością zwracaną przez funkcję w polu result obiektu.
  • Jeśli funkcja skryptu (lub sama skrypt Apps Script) zgłasza wyjątek, pole error zawiera obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który podaje informacje o charakterze błędu.
  • Jeśli wykonanie nie zostało jeszcze ukończone, pole done ma wartość false, a pola response ani error nie są obecne.
  • Jeśli samo wywołanie run nie powiedzie się (na przykład z powodu nieprawidłowego żądania lub błędu autoryzacji), metoda zwraca 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 wskazuje, czy wykonanie skryptu zostało ukończone. Ukończone wykonanie ma wypełnione pole response zawierające wartość ExecutionResponse z wykonanej funkcji.
Pole sumy result. Wynik operacji, którym może być error lub prawidłowy element response. Jeśli done == false, nie ustawiono ani error, ani response. Jeśli done == true, można ustawić dokładnie jedno z tych wartości: error lub response. Niektóre usługi mogą nie zapewniać oczekiwanych wyników. result może mieć tylko jedną z tych wartości:
error

object (Status)

Jeśli wywołanie run zakończy się powodzeniem, ale funkcja skryptu (lub sam skrypt Apps Script) zgłosi wyjątek, to pole będzie zawierać obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który podaje informacje o charakterze błędu.
response

object

Jeśli funkcja skryptu zostanie zwrócona, pole zawiera obiekt ExecutionResponse z wartością zwracaną przez funkcję.

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 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 sam skrypt Apps Script) zgłosi wyjątek, pole error 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 może to być jedna z wartości:

  • 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. Komunikaty o błędach, które widzą użytkownicy, są przetłumaczone i wysyłane w polu details lub przetłumaczone przez klienta.
details[]

object

Tablica zawierająca pojedynczy obiekt ExecutionError zawierający 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" }.