Method: scripts.run

Uruchamia funkcję w projekcie Apps Script. Projekt skryptu należy wdrożyć do użytku z interfejsem Apps Script API, a aplikacja do wywoływania musi mieć ten sam projekt Cloud Platform.

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

Błąd 403, PERMISSION_DENIED: The caller does not have permission wskazuje, że projekt Cloud Platform używany 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ć uruchomiony. 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 on odwoływać się do funkcji w dodanej bibliotece, takiej jak Library.libFunction1.

parameters[]

value (Value format)

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

sessionState

string

Wycofane. Dotyczy tylko dodatków do Androida. Identyfikator reprezentujący aktualną sesję użytkownika w aplikacji Dokumenty lub Arkusze Google na Androida. Uwzględnione jako dodatkowe dane w intencji, która uruchamia dodatek. Gdy dodatek na Androida działa ze stanem sesji, zyskuje uprawnienia powiązanego skryptu, czyli dostępu 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"). Opcjonalne.

devMode

boolean

Jeśli true jest użytkownikiem skryptu, ten skrypt uruchamia się w ostatnio zapisanej wersji, a nie w wersji wdrożonej za pomocą interfejsu Apps Script API. Opcjonalnie – domyślnie false.

Treść odpowiedzi

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

Prezentacja wykonania funkcji Apps Script rozpoczynała się od run. Odpowiedź uruchamia się dopiero po zakończeniu wykonywania funkcji. Maksymalne środowisko wykonawcze znajdziesz w przewodniku po limitach Apps Script.

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

  • Jeśli funkcja skryptu zwróci się, pole response będzie zawierać obiekt ExecutionResponse z wartością zwracaną w polu result obiektu.
  • Jeśli funkcja skryptu (lub sam skrypt Apps Script) zgłosi wyjątek, pole error zawiera obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który przekazuje informacje o charakterze błędu.
  • Jeśli wykonanie nie zostało jeszcze zakończone, pole done ma wartość false i nie ma pól response ani error.
  • Jeśli wywołanie run nie powiedzie się (np. z powodu nieprawidłowego żądania lub błędu autoryzacji), metoda zwróci kod odpowiedzi HTTP z zakresu 4XX w innym formacie dla 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 zakończone. Wykonane wykonanie ma wypełnione pole response z funkcją ExecutionResponse, która została wykonana.

Pole związkowe result. Wynik operacji może być wartością error lub prawidłową wartością response. Jeśli done == false, nie jest ustawiony żaden error ani response. Jeśli done == true, można ustawić dokładnie jedną wartość error lub response. Niektóre usługi mogą nie podawać wyników. result może mieć tylko jedną z tych wartości:
error

object (Status)

Jeśli wywołanie run się powiedzie, ale funkcja skryptu (lub sama skrypt Apps Script) zwróci wyjątek, to pole zawiera obiekt Status. Pole details obiektu Status zawiera tablicę z pojedynczym obiektem ExecutionError, który przekazuje informacje o charakterze błędu.

response

object

Jeśli funkcja skryptu zwróci się, pole będzie 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 następujących 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 OAuth 2.0.

Stan

Jeśli wywołanie run się powiedzie, ale funkcja skryptu (lub sama skrypt Apps Script) zwróci wyjątek, pole error treści odpowiedzi 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, wskazujący błąd SCRIPT_TIMEOUT,
  • 3 – wskazuje błąd INVALID_ARGUMENT lub
  • 1 – oznacza wykonanie CANCELLED

message

string

Komunikat o błędzie wyświetlany deweloperowi w języku angielskim. Wszystkie komunikaty o błędach wyświetlane użytkownikom są zlokalizowane i wysyłane w polu details lub 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" }.