Sử dụng giao diện dòng lệnh với clasp

Để phát triển và quản lý các dự án Google Apps Script từ thiết bị đầu cuối thay vì trình chỉnh sửa Apps Script, hãy sử dụng công cụ nguồn mở clasp.

Codelab clasp cung cấp thông tin tổng quan về tất cả các tính năng clasp.

Tính năng

clasp bao gồm các tính năng sau:

Phát triển cục bộ

clasp cho phép bạn phát triển các dự án Apps Script cục bộ. Viết mã trên máy tính của riêng bạn và tải mã đó lên Apps Script khi hoàn tất. Bạn cũng có thể tải các dự án Apps Script hiện có xuống để chỉnh sửa ngoại tuyến. Sử dụng các công cụ phát triển yêu thích như git khi xây dựng các dự án Apps Script.

Quản lý các phiên bản triển khai

Tạo, cập nhật và xem nhiều đợt triển khai dự án của bạn.

Cấu trúc mã

clasp cho phép bạn sắp xếp mã thành các thư mục được giữ nguyên khi bạn tải mã đó lên script.google.com. Ví dụ:

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

Loại dự án

Bạn có thể sử dụng clasp để quản lý cả dự án tập lệnh độc lập và dự án tập lệnh liên kết với vùng chứa.

Dự án độc lập

Dự án độc lập xuất hiện dưới dạng một tệp riêng biệt trong Google Drive. Bạn có thể tạo một tập lệnh độc lập mới bằng lệnh clasp create.

Dự án liên kết với vùng chứa

Dự án liên kết với vùng chứa được đính kèm vào một tệp Google Tài liệu, Trang tính, Trang trình bày hoặc Google Biểu mẫu. Bạn có thể tạo một tập lệnh liên kết với vùng chứa mới được đính kèm vào một tệp mới bằng lệnh clasp create. Bạn cũng có thể đính kèm một tập lệnh mới vào một tệp hiện có bằng cờ --parentId.

Các loại dự án khác

clasp cũng hỗ trợ việc tạo tập lệnh cho các ứng dụng web và API.

Yêu cầu

clasp được viết bằng Node.js và phân phối bằng công cụ npm. Trước khi sử dụng clasp, bạn phải cài đặt Node.js phiên bản 20.0.0 trở lên. Việc cài đặt Node.js yêu cầu bạn phải có đặc quyền quản trị.

Cài đặt

Sau khi cài đặt Node.js, hãy sử dụng lệnh npm sau để cài đặt clasp:

npm install @google/clasp -g

Sau khi cài đặt, hãy sử dụng lệnh clasp từ bất kỳ thư mục nào trên máy tính.

Sử dụng clasp

Sử dụng clasp để xử lý nhiều tác vụ từ dòng lệnh. Phần này mô tả các thao tác phổ biến cần sử dụng khi phát triển bằng clasp.

Đăng nhập

Lệnh này đăng nhập và cho phép quản lý các dự án Apps Script của Tài khoản Google. Sau khi chạy lệnh này, bạn sẽ được yêu cầu đăng nhập vào một Tài khoản Google nơi lưu trữ các dự án Apps Script.

clasp login

Đăng xuất

Lệnh này đăng xuất khỏi công cụ dòng lệnh. Đăng nhập lại bằng clasp login để xác thực lại với Google trước khi tiếp tục sử dụng clasp.

clasp logout

Tạo dự án Apps Script mới

Lệnh này tạo một tập lệnh mới trong thư mục hiện tại với tiêu đề tập lệnh không bắt buộc.

clasp create [scriptTitle] [--type <projectType>] [--parentId <parentId>]

Lệnh này sử dụng các tham số không bắt buộc sau:

• scriptTitle: Tiêu đề của dự án tập lệnh.
• --type <projectType>: Loại dự án cần tạo. Các giá trị được phép là standalone, docs, sheets, slides, forms, webapp và api.
• --parentId <parentId>: Mã của tệp Google Drive hiện có (Tài liệu, Trang tính, Trang trình bày hoặc Biểu mẫu) mà dự án tập lệnh mới sẽ được liên kết.

Lệnh này cũng tạo 2 tệp trong thư mục hiện tại:

• Tệp .clasp.json lưu trữ mã tập lệnh.
• Tệp kê khai dự án appsscript.json chứa siêu dữ liệu dự án.

Sao chép một dự án hiện có

Lệnh này sao chép một dự án hiện có trong thư mục hiện tại. Tập lệnh phải được tạo hoặc chia sẻ với Tài khoản Google của bạn. Bạn chỉ định dự án tập lệnh cần sao chép bằng cách cung cấp mã tập lệnh của dự án đó. Bạn có thể nhân bản cả dự án độc lập và dự án liên kết với vùng chứa.

Cách tìm Mã tập lệnh của dự án:

1. Mở dự án Apps Script.
2. Ở bên trái, hãy nhấp vào biểu tượng Cài đặt dự án settings.

3. Trong phần Mã, hãy sao chép Mã tập lệnh.

   clasp clone

Tải dự án tập lệnh xuống

Lệnh này tải dự án Apps Script từ Google Drive xuống hệ thống tệp của máy tính.

clasp pull

Tải dự án tập lệnh lên

Lệnh này tải tất cả các tệp của dự án tập lệnh từ máy tính của bạn lên Drive.

clasp push

Liệt kê các phiên bản dự án

Lệnh này liệt kê số và nội dung mô tả của từng phiên bản của dự án tập lệnh.

clasp versions

Triển khai dự án đã xuất bản

Triển khai các dự án tập lệnh dưới dạng ứng dụng web, tiện ích bổ sung Google Workspace hoặc tệp thực thi. Tạo đợt triển khai trong trình chỉnh sửa tập lệnh, trong tệp kê khai dự án hoặc bằng clasp.

Để triển khai một dự án bằng clasp, trước tiên, hãy tạo một phiên bản không thay đổi của dự án Apps Script. Phiên bản là "ảnh chụp nhanh" của dự án tập lệnh và tương tự như bản phát hành phân nhánh chỉ đọc.

clasp version [description]

Lệnh này hiển thị số phiên bản mới tạo. Sử dụng số đó để triển khai và huỷ triển khai các thực thể của dự án:

clasp deploy [version] [description]
clasp undeploy <deploymentId>

Lệnh này cập nhật một đợt triển khai hiện có bằng phiên bản và nội dung mô tả mới:

clasp redeploy <deploymentId> <version> <description>

Liệt kê các đợt triển khai

Lệnh này liệt kê mã đợt triển khai, phiên bản và nội dung mô tả của dự án tập lệnh.

clasp deployments

Mở dự án trong trình chỉnh sửa tập lệnh Apps Script

Lệnh này mở một dự án tập lệnh trong trình chỉnh sửa Apps Script. Trình chỉnh sửa sẽ khởi chạy dưới dạng một thẻ mới trong trình duyệt web mặc định của bạn.

clasp open-script

Đóng góp cho dự án nguồn mở clasp

Đóng góp cho clasp trên GitHub.

CI/CD cho Apps Script bằng clasp và GitHub Actions

Hướng dẫn này trình bày cách thiết lập quy trình tự động hoá việc tìm lỗi mã nguồn, kiểm thử và triển khai cho các dự án Google Apps Script bằng clasp và GitHub Actions.

1. Điều kiện tiên quyết

Trước khi bắt đầu, hãy hoàn tất các bước thiết lập trong phần Yêu cầu.

Bạn cũng cần:

• Kho lưu trữ GitHub.
• API Apps Script được bật tại script.google.com/home/usersettings.

2. Xác thực trong CI

Vì trình chạy CI không thể mở trình duyệt cho OAuth, nên bạn lưu trữ thông tin xác thực dưới dạng GitHub Secrets:

Mã làm mới trong .clasprc.json cấp quyền truy cập vào các dự án Apps Script. Hãy coi đây là thông tin xác thực nhạy cảm và thay đổi định kỳ.

Thêm .clasprc.json và .clasp.json vào .gitignore. Các tệp này chứa thông tin xác thực và không bao giờ được cam kết.

3. Quy trình CI – Kiểm tra lỗi và kiểm thử trên các yêu cầu kéo

.github/workflows/ci.yml:

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.3
      - uses: actions/setup-node@v6.3
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint

4. Quy trình CD – Triển khai khi hợp nhất

.github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint && npm test
      - name: Setup clasp credentials
        run: |

          echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json
          echo '${{ secrets.CLASP_JSON }}' > .clasp.json

      - name: Push and version
        run: |
          npx @google/clasp push --force
          npx @google/clasp version "$(git rev-parse --short HEAD)"

Cờ --force ghi đè mã từ xa mà không cần xác nhận. Sau khi quy trình này được thiết lập, hãy tránh chỉnh sửa thủ công trong trình chỉnh sửa Apps Script – kho lưu trữ sẽ trở thành nguồn đáng tin cậy duy nhất.

5. Triển khai nhiều môi trường

Đối với các môi trường phát triển/thử nghiệm/sản xuất riêng biệt, hãy tạo một dự án Apps Script riêng biệt cho từng môi trường và lưu trữ cấu hình của chúng dưới dạng các bí mật riêng biệt (CLASP_JSON_DEV, CLASP_JSON_STAGING, CLASP_JSON_PROD). Trong quy trình làm việc, hãy ghi bí mật thích hợp vào .clasp.json dựa trên nhánh đang được triển khai.

Khắc phục sự cố

Tài liệu đọc thêm

• Tài liệu về GitHub Actions