Thực thi các hàm bằng API Apps Script

API Google Apps Script cung cấp Phương thức scripts.run thực thi từ xa một hàm Apps Script được chỉ định. Bạn có thể dùng phương thức này trong ứng dụng gọi để chạy một hàm thuộc một trong các dự án tập lệnh của bạn từ xa và nhận phản hồi.

Yêu cầu

Bạn phải đáp ứng các yêu cầu sau đây thì ứng dụng gọi mới có thể sử dụng scripts.run . Bạn phải:

  • Triển khai dự án tập lệnh ở dạng API có thể thực thi. Bạn có thể triển khai, ngừng triển khai và triển khai lại các dự án nếu cần.

  • Cung cấp mã thông báo OAuth trong phạm vi phù hợp để thực thi. Mã thông báo OAuth này phải bao gồm tất cả phạm vi mà tập lệnh sử dụng chứ không chỉ những mã mà hàm được gọi sử dụng. Xem danh sách đầy đủ các phạm vi uỷ quyền trong tham chiếu phương thức.

  • Đảm bảo rằng tập lệnh và OAuth2 của ứng dụng gọi khách hàng dùng chung một dự án Google Cloud. Dự án Cloud phải là một dự án Cloud chuẩn; không đủ các dự án mặc định được tạo cho dự án Apps Script. Bạn có thể sử dụng dự án Cloud chuẩn mới hoặc dự án hiện có.

  • Bật API Google Apps Script trong dự án Cloud.

Phương thức scripts.run

scripts.run yêu cầu thông tin nhận dạng chính để chạy:

Bạn có thể tuỳ ý định cấu hình để tập lệnh thực thi ở chế độ phát triển. Chế độ này thực thi bằng phiên bản đã lưu gần đây nhất của dự án tập lệnh thay vì phiên bản được triển khai gần đây nhất. Hãy thực hiện việc này bằng cách đặt Giá trị boolean devMode trong nội dung yêu cầu đến true. Chỉ chủ sở hữu của tập lệnh mới có thể thực thi tập lệnh đó ở chế độ phát triển.

Xử lý các loại dữ liệu thông số

Sử dụng API Apps Script Phương thức scripts.run thường liên quan đến việc gửi dữ liệu đến Apps Script dưới dạng tham số hàm và việc lấy lại dữ liệu dưới dạng các giá trị trả về của hàm. API chỉ có thể nhận và trả về giá trị với các loại cơ bản: chuỗi, mảng, đối tượng, số và boolean. Các tương tự như các loại cơ bản trong JavaScript. Phức tạp hơn Đối tượng Apps Script như Document hoặc Trang tính không thể được chuyển vào hoặc từ dự án tập lệnh bởi API.

Khi ứng dụng gọi điện của bạn được viết bằng ngôn ngữ khó sử dụng như Java, truyền vào các tham số dưới dạng danh sách hoặc mảng các đối tượng chung tương ứng với các loại cơ bản này. Trong nhiều trường hợp, bạn có thể áp dụng các phương pháp tự động nhập lượt chuyển đổi. Ví dụ: một hàm nhận số có thể được cung cấp một đối tượng Java Double hoặc Integer hoặc Long của Java dưới dạng một mà không cần xử lý thêm.

Khi API trả về phản hồi hàm, thông thường bạn cần truyền trả về đúng loại trước khi có thể sử dụng. Sau đây là một số Ví dụ dựa trên Java:

  • Các số được API trả về cho ứng dụng Java được cung cấp dưới dạng java.math.BigDecimal và có thể cần phải chuyển đổi thành Doubles hoặc int loại nếu cần.
  • Nếu hàm Apps Script trả về một mảng chuỗi, thì một ứng dụng Java truyền phản hồi vào một đối tượng List<String>:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Nếu muốn trả về một mảng Bytes, bạn có thể thấy cách này thuận tiện để mã hoá mảng dưới dạng Chuỗi base64 trong hàm Apps Script và trả về Chuỗi đó:

    return Utilities.base64Encode(myByteArray); // returns a String.
    

Mã mẫu dưới đây minh hoạ cách diễn giải phản hồi của API.

Quy trình chung

Phần sau đây mô tả quy trình chung để sử dụng API Apps Script để thực thi các hàm của Apps Script:

Bước 1: Thiết lập dự án Google Cloud dùng chung

Cả tập lệnh và ứng dụng gọi cần chia sẻ cùng một tệp Dự án trên đám mây. Dự án Cloud này có thể là một dự án hiện có hoặc một dự án mới được tạo cho mục đích này. Sau khi có một dự án trên Google Cloud, bạn phải chuyển đổi dự án tập lệnh của mình để sử dụng tập lệnh đó.

Bước 2: Triển khai tập lệnh dưới dạng API có thể thực thi

  1. Mở dự án Apps Script có các hàm bạn muốn dùng.
  2. Ở trên cùng bên phải, hãy nhấp vào Triển khai &gt; Triển khai mới.
  3. Trong hộp thoại mở ra, hãy nhấp vào mục Bật loại triển khai &gt; API có thể thực thi.
  4. Trong phần "Người có quyền truy cập" trong trình đơn thả xuống, hãy chọn người dùng được phép gọi các hàm của tập lệnh bằng API Apps Script.
  5. Nhấp vào Triển khai.

Bước 3: Định cấu hình ứng dụng gọi

Ứng dụng gọi phải bật Apps Script API và thiết lập OAuth trước khi có thể sử dụng. Bạn phải có quyền truy cập vào dự án trên Google Cloud để làm việc này.

  1. Định cấu hình dự án trên đám mây mà tập lệnh và ứng dụng gọi của bạn đang sử dụng. Bạn có thể thực hiện việc này bằng cách làm theo các bước sau:
    1. Bật API Apps Script trong dự án Cloud.
    2. Định cấu hình màn hình xin phép bằng OAuth.
    3. Tạo thông tin đăng nhập OAuth.
  2. Mở dự án tập lệnh và ở bên trái, hãy nhấp vào biểu tượng Tổng quan .
  3. Trong Phạm vi OAuth của dự án, hãy ghi lại tất cả các phạm vi mà tập lệnh yêu cầu.
  4. Trong mã xử lý ứng dụng gọi, hãy tạo một mã truy cập OAuth của tập lệnh cho lệnh gọi API. Đây không phải là mã thông báo mà API tự sử dụng, mà là một mã tập lệnh yêu cầu khi thực thi. Công cụ này nên được xây dựng bằng cách sử dụng Mã ứng dụng khách của dự án trên đám mây và phạm vi tập lệnh mà bạn đã ghi lại.

    Thư viện ứng dụng của Google có thể giúp ích rất nhiều hỗ trợ tạo mã thông báo này và xử lý OAuth cho ứng dụng, thường cho phép bạn xây dựng "thông tin xác thực" cấp cao hơn đối tượng bằng cách sử dụng phạm vi tập lệnh. Xem Bắt đầu nhanh API Apps Script để xem ví dụ tạo đối tượng thông tin xác thực từ danh sách phạm vi.

Bước 4: Đưa ra yêu cầu script.run

Sau khi định cấu hình ứng dụng gọi, bạn có thể thực hiện scripts.run cuộc gọi. Mỗi API cuộc gọi bao gồm các bước sau:

  1. Tạo yêu cầu API bằng cách sử dụng mã tập lệnh, tên hàm và mọi yêu cầu tham số.
  2. Tạo scripts.run gọi và bao gồm mã thông báo OAuth của tập lệnh mà bạn đã tạo trong tiêu đề (nếu sử dụng yêu cầu POST cơ bản) hoặc sử dụng đối tượng thông tin xác thực mà bạn đã tạo bằng phạm vi tập lệnh.
  3. Cho phép tập lệnh hoàn tất việc thực thi. Tập lệnh được phép đăng tối đa thời gian thực thi là 6 phút, vì vậy ứng dụng của bạn nên cho phép điều này.
  4. Sau khi hoàn tất, hàm của tập lệnh có thể trả về một giá trị mà API sẽ gửi lại cho ứng dụng nếu giá trị là một kiểu được hỗ trợ.

Bạn có thể xem ví dụ về lệnh gọi API script.run bên dưới.

Ví dụ về yêu cầu API

Các ví dụ sau đây minh hoạ cách tạo một yêu cầu thực thi API Apps Script trong nhiều ngôn ngữ khác nhau, gọi hàm Apps Script để in ra danh sách các thư mục trong thư mục gốc của người dùng. Mã tập lệnh của dự án Apps Script chứa hàm được thực thi phải được chỉ định ở nơi biểu thị bằng ENTER_YOUR_SCRIPT_ID_HERE. Những ví dụ này dựa trên Thư viện ứng dụng API của Google cho các thư viện tương ứng ngôn ngữ.

Tập lệnh mục tiêu

Hàm trong tập lệnh này sử dụng API Drive.

Bạn phải bật API Drive trong dự án lưu trữ tập lệnh.

Ngoài ra, ứng dụng gọi phải gửi thông tin xác thực OAuth, bao gồm phạm vi Drive sau đây:

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

Các ứng dụng mẫu ở đây sử dụng thư viện ứng dụng của Google để tạo đối tượng thông tin xác thực cho OAuth bằng phạm vi này.

/**
 * 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

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

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()

Các điểm hạn chế

API Apps Script có một số hạn chế:

  1. Một dự án Google Cloud phổ biến. Tập lệnh đang được gọi và ứng dụng gọi phải chia sẻ một dự án trên đám mây. Dự án Cloud phải là dự án Cloud chuẩn; không đủ các dự án mặc định được tạo cho dự án Apps Script. Chiến lược phát hành đĩa đơn dự án Cloud chuẩn có thể là dự án mới hoặc hiện có.

  2. Các kiểu dữ liệu trả về và tham số cơ bản. API không thể chuyển hoặc trả về Các đối tượng dành riêng cho Apps Script (chẳng hạn như Documents (Tài liệu), Thắt lưng, Lịch, Drive Files, v.v.) vào . Chỉ các loại cơ bản như chuỗi, mảng, đối tượng, số và boolean có thể được truyền và trả về.

  3. Các phạm vi của OAuth. API chỉ có thể thực thi các tập lệnh có ít nhất một phạm vi bắt buộc. Điều này có nghĩa là bạn không thể dùng API để gọi một tập lệnh không yêu cầu uỷ quyền một hoặc nhiều dịch vụ.

  4. Không có điều kiện kích hoạt.API không thể tạo Apps Script điều kiện kích hoạt.