Halaman ini diterjemahkan oleh Cloud Translation API.

Menjalankan Fungsi dengan Apps Script API

Google Apps Script API menyediakan metode scripts.run yang mengeksekusi fungsi Apps Script yang ditentukan dari jarak jauh. Anda dapat menggunakan metode ini dalam aplikasi panggilan untuk menjalankan fungsi di salah satu project skrip dari jarak jauh dan menerima respons.

Persyaratan

Anda harus memenuhi persyaratan berikut sebelum aplikasi panggilan dapat menggunakan metode scripts.run. Anda harus:

Deploy project skrip sebagai API yang dapat dieksekusi. Anda dapat men-deploy, membatalkan deployment, dan men-deploy ulang project sesuai kebutuhan.
Berikan token OAuth dengan cakupan yang tepat untuk eksekusi. Token OAuth ini harus mencakup semua cakupan yang digunakan oleh skrip, bukan hanya yang digunakan oleh fungsi yang dipanggil. Lihat daftar lengkap cakupan otorisasi dalam referensi metode.
Pastikan skrip dan klien OAuth2 aplikasi panggilan memiliki project Google Cloud yang sama. Project Cloud harus berupa project Cloud standar; project default yang dibuat untuk project Apps Script tidak memadai. Anda dapat menggunakan project Cloud standar baru atau yang sudah ada.
Aktifkan Google Apps Script API di project Cloud.

Metode `scripts.run`

Metode scripts.run memerlukan informasi identifikasi kunci agar dapat berjalan:

ID project skrip.
Nama fungsi yang akan dieksekusi.
Daftar parameter yang diperlukan fungsi (jika ada).

Secara opsional, Anda dapat mengonfigurasi skrip untuk dijalankan dalam mode pengembangan. Mode ini dijalankan dengan versi project skrip yang baru saja disimpan, bukan versi yang baru saja di-deploy. Lakukan hal ini dengan menetapkan Boolean devMode di isi permintaan ke true. Hanya pemilik skrip yang dapat menjalankannya dalam mode pengembangan.

Menangani jenis data parameter

Menggunakan metode scripts.run Apps Script API biasanya melibatkan pengiriman data ke Apps Script sebagai parameter fungsi dan mendapatkan data kembali sebagai nilai return fungsi. API hanya dapat mengambil dan menampilkan nilai dengan jenis dasar: string, array, objek, angka, dan boolean. Jenis ini mirip dengan jenis dasar di JavaScript. Objek Apps Script yang lebih kompleks seperti Dokumen atau Sheet tidak dapat diteruskan ke atau dari project skrip oleh API.

Jika aplikasi panggilan Anda ditulis dalam bahasa dengan jenis yang kuat seperti Java, aplikasi akan meneruskan parameter sebagai daftar atau array objek generik yang sesuai dengan jenis dasar ini. Dalam banyak kasus, Anda dapat menerapkan konversi jenis sederhana secara otomatis. Misalnya, fungsi yang menggunakan parameter angka dapat diberi objek Double atau Integer atau Long Java sebagai parameter tanpa penanganan tambahan.

Saat API menampilkan respons fungsi, Anda sering kali perlu mentransmisikan nilai yang ditampilkan ke jenis yang benar sebelum dapat digunakan. Berikut beberapa contoh berbasis Java:

Angka yang ditampilkan oleh API ke aplikasi Java akan muncul sebagai objek java.math.BigDecimal, dan mungkin perlu dikonversi ke jenis Doubles atau int sesuai kebutuhan.
Jika fungsi Apps Script menampilkan array string, aplikasi Java akan mentransmisikan respons ke objek List<String>:
```
List<String> mylist = (List<String>)(op.getResponse().get("result"));
```
Jika ingin menampilkan array Bytes, Anda mungkin merasa lebih mudah untuk mengenkode array sebagai String base64 dalam fungsi Apps Script dan menampilkan String tersebut:
```
return Utilities.base64Encode(myByteArray); // returns a String.
```

Contoh contoh kode di bawah ini menggambarkan cara menafsirkan respons API.

Prosedur umum

Berikut ini penjelasan prosedur umum untuk menggunakan Apps Script API guna menjalankan fungsi Apps Script:

Langkah 1: Siapkan project Cloud umum

Skrip dan aplikasi panggilan Anda harus menggunakan project Cloud yang sama. Project Cloud ini dapat berupa project yang ada atau project baru yang dibuat untuk tujuan ini. Setelah memiliki project Cloud, Anda harus mengganti project skrip untuk menggunakannya.

Langkah 2: Deploy skrip sebagai API yang dapat dieksekusi

Buka project Apps Script dengan fungsi yang ingin Anda gunakan.
Di kanan atas, klik Deploy > New Deployment.
Pada dialog yang terbuka, klik Aktifkan jenis deployment > API Executable.
Di menu drop-down "Siapa yang memiliki akses", pilih pengguna yang diizinkan untuk memanggil fungsi skrip menggunakan Apps Script API.
Klik Deploy.

Langkah 3: Konfigurasikan aplikasi panggilan

Aplikasi panggilan harus mengaktifkan Apps Script API dan membuat kredensial OAuth sebelum dapat digunakan. Anda harus memiliki akses ke project Cloud untuk melakukannya.

Konfigurasikan project Cloud yang digunakan aplikasi dan skrip panggilan Anda. Anda dapat melakukannya dengan langkah-langkah berikut:
Buka project skrip dan di sebelah kiri, klik Ringkasan .
Di bagian Cakupan Oauth project, catat semua cakupan yang diperlukan skrip.
Dalam kode aplikasi panggilan, buat token akses OAuth skrip untuk panggilan API. Ini bukan token yang digunakan API itu sendiri, tetapi token yang diperlukan skrip saat dieksekusi. Aplikasi ini harus dibuat menggunakan client ID project Cloud dan cakupan skrip yang Anda rekam.

Library klien Google dapat sangat membantu dalam membuat token ini dan menangani OAuth untuk aplikasi, yang biasanya memungkinkan Anda membuat objek "kredensial" tingkat lebih tinggi menggunakan cakupan skrip. Lihat panduan memulai Apps Script API untuk mengetahui contoh pembuatan objek kredensial dari daftar cakupan.

Langkah 4: Buat permintaan `script.run`

Setelah aplikasi panggilan dikonfigurasi, Anda dapat melakukan panggilan scripts.run. Setiap panggilan API terdiri dari langkah-langkah berikut:

Buat permintaan API menggunakan ID skrip, nama fungsi, dan parameter yang diperlukan.
Lakukan panggilan scripts.run dan sertakan token OAuth skrip yang Anda buat di header (jika menggunakan permintaan POST dasar) atau gunakan objek kredensial yang Anda buat dengan cakupan skrip.
Biarkan skrip selesai dieksekusi. Skrip diizinkan untuk memerlukan waktu eksekusi hingga enam menit, sehingga aplikasi Anda harus mengizinkannya.
Setelah selesai, fungsi skrip dapat menampilkan nilai, yang dikirimkan kembali oleh API ke aplikasi jika nilai tersebut adalah jenis yang didukung.

Anda dapat menemukan contoh panggilan API script.run di bawah.

Peringatan: Jika token akses Anda berakhir masa berlakunya saat permintaan API script.run menjalankan fungsi skrip, hal ini dapat menyebabkan error Authorization is required to perform that action. Untuk menghindari hal ini, muat ulang token akses Anda sebelum melakukan panggilan API jika waktu expires_in-nya kurang dari runtime skrip maksimum untuk akun Anda (6 menit dalam sebagian besar kasus).

Untuk memperbarui token akses, Anda dapat menambahkan cuplikan berikut sebelum permintaan API script.run:

if (credential.getExpiresInSeconds() <= 360) {
  credential.refreshToken();
}

Contoh permintaan API

Contoh berikut menunjukkan cara membuat permintaan eksekusi Apps Script API dalam berbagai bahasa, memanggil fungsi Apps Script untuk mencetak daftar folder di direktori utama pengguna. ID skrip project Apps Script yang berisi fungsi yang dieksekusi harus ditentukan di tempat yang ditunjukkan dengan ENTER_YOUR_SCRIPT_ID_HERE. Contoh ini mengandalkan Library Klien Google API untuk bahasanya masing-masing.

Skrip Target

Fungsi dalam skrip ini menggunakan Drive API.

Anda harus mengaktifkan Drive API di project yang menghosting skrip.

Selain itu, aplikasi panggilan harus mengirim kredensial OAuth yang menyertakan cakupan Drive berikut:

https://www.googleapis.com/auth/drive

Contoh aplikasi di sini menggunakan library klien Google untuk membuat objek kredensial untuk OAuth menggunakan cakupan ini.

/**
 * 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;
}target.js

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);
  }
}Execute.java

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;
  }
}
index.js

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;
  }
}index.js

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()execute.py

Batasan

Apps Script API memiliki beberapa batasan:

Project Cloud umum. Skrip yang dipanggil dan aplikasi pemanggilan harus berbagi project Cloud. Project Cloud harus berupa project Cloud standar; project default yang dibuat untuk project Apps Script tidak memadai. Project Cloud standar dapat berupa project baru atau yang sudah ada.
Parameter dan jenis nilai yang ditampilkan dasar. API tidak dapat meneruskan atau menampilkan objek khusus Apps Script (seperti Dokumen, Blob, Kalender, File Drive, dll.) ke aplikasi. Hanya jenis dasar seperti string, array, objek, angka, dan boolean yang dapat diteruskan dan ditampilkan.
Cakupan OAuth. API hanya dapat menjalankan skrip yang memiliki setidaknya satu cakupan yang diperlukan. Artinya, Anda tidak dapat menggunakan API untuk memanggil skrip yang tidak memerlukan otorisasi satu atau beberapa layanan.
Tidak ada pemicu.API tidak dapat membuat pemicu Apps Script.