استفاده از رابط خط فرمان با clasp

برای توسعه و مدیریت پروژه‌های اسکریپت گوگل اپس از طریق ترمینال خود به جای ویرایشگر اسکریپت اپس، از ابزار متن‌باز clasp استفاده کنید.

آزمایشگاه کد clasp ، مروری کلی بر تمام ویژگی‌های clasp ارائه می‌دهد.

ویژگی‌ها

clasp شامل ویژگی‌های زیر است:

توسعه محلی

clasp به شما امکان می‌دهد پروژه‌های Apps Script خود را به صورت محلی توسعه دهید. کد را روی رایانه خود بنویسید و پس از اتمام، آن را در Apps Script آپلود کنید. همچنین می‌توانید پروژه‌های Apps Script موجود را دانلود کنید تا آنها را به صورت آفلاین ویرایش کنید. هنگام ساخت پروژه‌های Apps Script از ابزارهای توسعه مورد علاقه خود مانند git استفاده کنید.

مدیریت نسخه‌های استقرار

چندین نسخه از پروژه خود را ایجاد، به‌روزرسانی و مشاهده کنید.

کد ساختار

clasp به شما امکان می‌دهد کدهای خود را در دایرکتوری‌هایی سازماندهی کنید که هنگام آپلود آنها در script.google.com حفظ می‌شوند. برای مثال:

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

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

انواع پروژه

شما می‌توانید clasp برای مدیریت پروژه‌های اسکریپت مستقل و پروژه‌های اسکریپت وابسته به کانتینر استفاده کنید.

پروژه‌های مستقل

یک پروژه مستقل به عنوان یک فایل جداگانه در گوگل درایو شما ظاهر می‌شود. می‌توانید با استفاده از دستور clasp create یک اسکریپت مستقل جدید ایجاد کنید.

پروژه‌های کانتینری

یک پروژه متصل به کانتینر به یک فایل Google Docs، Sheets، Slides یا Google Forms متصل می‌شود. می‌توانید با استفاده از دستور clasp create یک اسکریپت متصل به کانتینر جدید ایجاد کنید که به یک فایل جدید متصل شده باشد. همچنین می‌توانید با استفاده از پرچم --parentId یک اسکریپت جدید را به یک فایل موجود متصل کنید.

انواع دیگر پروژه

clasp همچنین از ایجاد اسکریپت برای برنامه‌های وب و APIها پشتیبانی می‌کند.

الزامات

clasp با Node.js نوشته شده و با استفاده از ابزار npm توزیع شده است. قبل از استفاده از clasp ، باید Node.js نسخه 20.0.0 یا بالاتر را نصب کرده باشید. نصب Node.js نیاز به دسترسی ادمین دارد.

نصب

پس از نصب Node.js، از دستور npm زیر برای نصب clasp استفاده کنید:

npm install @google/clasp -g

پس از نصب، از دستور clasp در هر دایرکتوری روی رایانه خود استفاده کنید.

clasp استفاده کنید

clasp برای انجام وظایف مختلف از خط فرمان استفاده کنید. این بخش عملیات رایج مورد استفاده هنگام توسعه با clasp را شرح می‌دهد.

ورود

این دستور به حساب کاربری گوگل شما وارد می‌شود و مدیریت پروژه‌های Apps Script را مجاز می‌کند. پس از اجرا، از شما خواسته می‌شود وارد حساب گوگلی شوید که پروژه‌های Apps Script شما در آن ذخیره شده‌اند.

clasp login

خروج

این دستور از ابزار خط فرمان خارج می‌شود. قبل از ادامه استفاده clasp دوباره با استفاده clasp login وارد سیستم شوید تا دوباره با گوگل احراز هویت شوید.

clasp logout

یک پروژه جدید Apps Script ایجاد کنید

این دستور یک اسکریپت جدید در دایرکتوری فعلی با عنوان اسکریپت اختیاری ایجاد می‌کند.

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

این دستور از پارامترهای اختیاری زیر استفاده می‌کند:

• scriptTitle : عنوان پروژه اسکریپت.
• --type <projectType> : نوع پروژه‌ای که باید ایجاد شود. مقادیر مجاز عبارتند از standalone ، docs ، sheets ، slides ، forms ، webapp و api .
• --parentId <parentId> : شناسه فایل موجود در گوگل درایو (اسناد، برگه‌ها، اسلایدها یا فرم‌ها) که پروژه اسکریپت جدید باید به آن متصل شود.

این دستور همچنین دو فایل در دایرکتوری فعلی ایجاد می‌کند:

• یک فایل .clasp.json که شناسه اسکریپت را ذخیره می‌کند.
• یک فایل مانیفست پروژه appsscript.json که شامل فراداده‌های پروژه است.

کلون کردن یک پروژه موجود

این دستور یک پروژه موجود در دایرکتوری فعلی را کپی می‌کند. اسکریپت باید با حساب گوگل شما ایجاد یا به اشتراک گذاشته شود. شما با ارائه شناسه اسکریپت، پروژه اسکریپت مورد نظر برای کپی کردن را مشخص می‌کنید. می‌توانید هم پروژه‌های مستقل و هم پروژه‌های متصل به کانتینر را کپی کنید.

برای پیدا کردن شناسه اسکریپت پروژه:

1. پروژه Apps Script را باز کنید.
2. در سمت چپ، روی settings پروژه کلیک کنید.

3. در قسمت شناسه‌ها ، شناسه اسکریپت را کپی کنید.

   کلون قلاب

دانلود یک پروژه اسکریپت نویسی

این دستور پروژه Apps Script را از گوگل درایو روی سیستم فایل رایانه شما دانلود می‌کند.

clasp pull

آپلود پروژه اسکریپت

این دستور تمام فایل‌های یک پروژه اسکریپت را از رایانه شما به Drive آپلود می‌کند.

clasp push

فهرست نسخه‌های پروژه

این دستور تعداد و توضیحات هر یک از نسخه‌های یک پروژه اسکریپت را فهرست می‌کند.

clasp versions

استقرار یک پروژه منتشر شده

پروژه‌های اسکریپت را به عنوان برنامه‌های وب، افزونه‌های Google Workspace یا فایل‌های اجرایی مستقر کنید. استقرارها را در ویرایشگر اسکریپت، در مانیفست پروژه یا با استفاده از clasp ایجاد کنید.

برای استقرار یک پروژه با clasp ، ابتدا یک نسخه تغییرناپذیر از پروژه Apps Script ایجاد کنید. یک نسخه، "عکس فوری" از یک پروژه اسکریپت است و مشابه یک نسخه شاخه‌ای فقط خواندنی است.

clasp version [description]

این دستور شماره نسخه جدید ایجاد شده را نمایش می‌دهد. از آن شماره برای استقرار و لغو استقرار نمونه‌های پروژه خود استفاده کنید:

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

این دستور، یک نسخه و توضیحات جدید از یک استقرار موجود را به‌روزرسانی می‌کند:

clasp redeploy <deploymentId> <version> <description>

فهرست استقرارها

این دستور، شناسه‌های استقرار پروژه اسکریپت، نسخه‌ها و توضیحات آنها را فهرست می‌کند.

clasp deployments

پروژه را در ویرایشگر Apps Script باز کنید.

این دستور یک پروژه اسکریپت را در ویرایشگر Apps Script باز می‌کند. ویرایشگر به عنوان یک تب جدید در مرورگر وب پیش‌فرض شما اجرا می‌شود.

clasp open-script

در پروژه متن‌باز clasp مشارکت کنید

در گیت‌هاب به clasp کمک کنید.

اسکریپت CI/CD برای برنامه‌ها با clasp و GitHub Actions

این راهنما، راه‌اندازی linting خودکار، آزمایش و استقرار برای پروژه‌های Google Apps Script با استفاده از clasp و GitHub Actions را پوشش می‌دهد.

۱. پیش‌نیازها

قبل از شروع، مراحل راه‌اندازی را در بخش «الزامات» تکمیل کنید.

شما همچنین نیاز دارید به:

• یک مخزن گیت‌هاب.
• API اسکریپت برنامه‌ها در script.google.com/home/usersettings فعال شده است.

۲. احراز هویت در CI

از آنجایی که کاربران CI نمی‌توانند مرورگر را برای OAuth باز کنند، شما اعتبارنامه‌ها را به عنوان GitHub Secrets ذخیره می‌کنید:

توکن refresh در فایل .clasprc.json به پروژه‌های Apps Script شما دسترسی می‌دهد. آن را به عنوان یک اعتبارنامه حساس در نظر بگیرید و به صورت دوره‌ای آن را تغییر دهید.

.clasprc.json و .clasp.json را به .gitignore خود اضافه کنید. این فایل‌ها حاوی اطلاعات احراز هویت هستند و هرگز نباید commit شوند.

۳. گردش کار CI - Lint و Test روی PRها

.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

۴. گردش کار CD - استقرار در هنگام ادغام

.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)"

پرچم --force کد ریموت را بدون تأیید بازنویسی می‌کند. پس از راه‌اندازی این خط لوله، از ویرایش دستی در ویرایشگر Apps Script خودداری کنید - مخزن به تنها منبع حقیقت تبدیل می‌شود.

۵. استقرار چند محیطی

برای محیط‌های توسعه/مرحله‌بندی/تولید جداگانه، برای هر کدام یک پروژه Apps Script مجزا ایجاد کنید و پیکربندی‌های آنها را به عنوان رمزهای جداگانه ( CLASP_JSON_DEV ، CLASP_JSON_STAGING ، CLASP_JSON_PROD ) ذخیره کنید. در گردش کار، رمز مناسب را بر اساس شاخه‌ای که مستقر می‌شود، در .clasp.json بنویسید.

عیب‌یابی

مطالعه بیشتر

• مستندات اقدامات گیت‌هاب