שימוש בממשק שורת הפקודה עם clasp

כדי לפתח ולנהל פרויקטים של Google Apps Script מהטרמינל ולא מהכלי לעריכת סקריפטים של Apps Script, אפשר להשתמש בכלי clasp בקוד פתוח.

ב-clasp codelab יש סקירה כללית של כל התכונות של clasp.

תכונות

‫clasp כולל את התכונות הבאות:

פיתוח באופן מקומי

‫clasp מאפשר לכם לפתח את פרויקטי Apps Script באופן מקומי. לכתוב קוד במחשב ולהעלות אותו ל-Apps Script כשמסיימים. אפשר גם להוריד פרויקטים קיימים ב-Apps Script כדי לערוך אותם במצב אופליין. אפשר להשתמש בכלי הפיתוח המועדפים עליכם, כמו git, כשיוצרים פרויקטים של Apps Script.

ניהול גרסאות הפריסה

יצירה, עדכון והצגה של כמה פריסות של הפרויקט.

קוד מבנה

‫clasp מאפשר לארגן את הקוד בספריות, שנשמרות כשמעלים אותן אל script.google.com. לדוגמה:

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

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

סוגי פרויקטים

אפשר להשתמש ב-clasp כדי לנהל פרויקטים של סקריפטים עצמאיים ופרויקטים של סקריפטים שמשויכים למאגר.

פרויקטים עצמאיים

פרויקט עצמאי מופיע כקובץ נפרד ב-Google Drive. אפשר ליצור סקריפט חדש ועצמאי באמצעות הפקודה clasp create.

פרויקטים שמשויכים למאגר

פרויקט שקשור למאגר נתונים מצורף לקובץ ב-Google Docs, ב-Sheets, ב-Slides או ב-Google Forms. אפשר ליצור סקריפט חדש שמשויך לקובץ חדש באמצעות הפקודה clasp create. אפשר גם לצרף סקריפט חדש לקובץ קיים באמצעות הדגל --parentId.

סוגי פרויקטים אחרים

‫clasp תומך גם ביצירת סקריפטים לאפליקציות ולאתרי אינטרנט.

דרישות

‫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 בחשבון Google שלכם. אחרי שמריצים אותו, מתבקשים להיכנס לחשבון Google שבו מאוחסנים פרויקטים של Apps Script.

clasp login

יציאה

פקודה זו מוציאה אתכם מכלי שורת הפקודה. צריך להתחבר מחדש באמצעות clasp login כדי לבצע אימות מחדש ב-Google לפני שממשיכים להשתמש ב-clasp.

clasp logout

יצירת פרויקט חדש ב-Apps Script

הפקודה הזו יוצרת סקריפט חדש בספרייה הנוכחית עם שם סקריפט אופציונלי.

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

הפקודה הזו כוללת את הפרמטרים האופציונליים הבאים:

• ‫scriptTitle: השם של פרויקט ה-Apps Script.
• ‫--type <projectType>: סוג הפרויקט שרוצים ליצור. הערכים המותרים הם standalone,‏ docs,‏ sheets,‏ slides,‏ forms,‏ webapp ו-api.
• ‫--parentId <parentId>: המזהה של הקובץ הקיים ב-Google Drive (Docs,‏ Sheets,‏ Slides או Forms) שאליו צריך לקשר את פרויקט הסקריפט החדש.

הפקודה הזו יוצרת גם שני קבצים בספרייה הנוכחית:

• קובץ .clasp.json שבו מאוחסן מזהה הסקריפט.
• קובץ מניפסט של פרויקט appsscript.json שמכיל מטא-נתונים של הפרויקט.

שכפול פרויקט קיים

הפקודה הזו משכפלת פרויקט קיים בספרייה הנוכחית. הסקריפט צריך להיות משותף עם חשבון Google שלכם או שאתם צריכים ליצור אותו בעצמכם. מציינים את פרויקט הסקריפט לשכפול על ידי הזנת מזהה הסקריפט. אפשר לשכפל פרויקטים עצמאיים ופרויקטים שמשויכים למאגר תגים.

כדי למצוא את מזהה הסקריפט של הפרויקט:

1. פותחים את פרויקט Apps Script.
2. בצד ימין, לוחצים על הגדרות הפרויקט settings.

3. בקטע מזהים, מעתיקים את מזהה הסקריפט.

   שכפול של אבזם

הורדת פרויקט של סקריפט

הפקודה הזו מורידה את פרויקט Apps Script מ-Google Drive למערכת הקבצים במחשב.

clasp pull

העלאת פרויקט סקריפט

הפקודה הזו מעלה את כל הקבצים של פרויקט סקריפט מהמחשב ל-Drive.

clasp push

הצגת רשימת גרסאות של פרויקט

הפקודה הזו מציגה את המספר והתיאור של כל אחת מהגרסאות של פרויקט סקריפט.

clasp versions

פריסת פרויקט שפורסם

פריסת פרויקטים של סקריפטים כאפליקציות אינטרנט, כתוספים ל-Google Workspace או כקבצים הפעלה. יוצרים פריסות ב<term>הכלי לעריכת סקריפטים</term>, במניפסט של ה<term>פרויקט</term> או באמצעות clasp.

כדי לפרוס פרויקט באמצעות clasp, קודם צריך ליצור גרסה שלא ניתן לשנות של פרויקט Apps Script. גרסה היא "תמונת מצב" של פרויקט 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 ב-GitHub.

‫CI/CD ל-Apps Script באמצעות clasp ו-GitHub Actions

במדריך הזה נסביר איך מגדירים בדיקת קוד (linting), בדיקה ופריסה אוטומטיות לפרויקטים של Google Apps Script באמצעות clasp ו-GitHub Actions.

1. דרישות מוקדמות

לפני שמתחילים, צריך להשלים את שלבי ההגדרה שמפורטים בקטע דרישות.

צריך גם:

• מאגר ב-GitHub.
• ‫Apps Script API הופעל ב-script.google.com/home/usersettings.

2. אימות ב-CI

מכיוון ש-CI runners לא יכולים לפתוח דפדפן ל-OAuth, צריך לאחסן את פרטי הכניסה כGitHub Secrets:

טוקן הרענון ב-.clasprc.json מעניק גישה לפרויקטים שלכם ב-Apps Script. חשוב להתייחס אליו כאל פרטי כניסה רגישים ולעדכן אותו מעת לעת.

הוספת .clasprc.json ו.clasp.json ל-.gitignore. הם מכילים פרטי כניסה ואסור לשמור אותם.

3. תהליך עבודה של CI – בדיקת Lint ובדיקה בבקשות למשיכת שינויים

.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. תהליך עבודה של 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 – המאגר הופך למקור הקובע.

5. פריסה בסביבות מרובות

כדי ליצור סביבות פיתוח, סביבות ביניים וסביבות ייצור נפרדות, צריך ליצור פרויקט Apps Script נפרד לכל אחת מהן ולאחסן את ההגדרות שלהן כסודות נפרדים (CLASP_JSON_DEV, ‏CLASP_JSON_STAGING, ‏CLASP_JSON_PROD). בתהליך העבודה, כותבים את הסוד המתאים ל-.clasp.json בהתאם לענף שפורסים.

פתרון בעיות

קריאה נוספת

• מסמכי GitHub Actions