استخدام واجهة سطر الأوامر مع clasp

لتطوير مشاريع "برمجة تطبيقات Google" وإدارتها من نافذة الأوامر بدلاً من أداة تعديل النصوص البرمجية في "برمجة تطبيقات Google"، استخدِم الأداة المفتوحة المصدر clasp.

تقدّم تجربة الترميز clasp نظرة عامة على جميع ميزات clasp.

الميزات

تتضمّن خدمة clasp الميزات التالية:

التطوير محليًا

تتيح لك أداة clasp تطوير مشاريع "برمجة تطبيقات Google" محليًا. كتابة الرمز على جهاز الكمبيوتر الخاص بك وتحميله إلى برمجة تطبيقات عند الانتهاء يمكنك أيضًا تنزيل مشاريع "برمجة تطبيقات Google" الحالية لتعديلها بلا إنترنت. استخدِم أدوات التطوير المفضّلة لديك، مثل git عند إنشاء مشاريع برمجة تطبيقات.

إدارة نُسخ عمليات النشر

إنشاء عمليات نشر متعددة لمشروعك وتعديلها وعرضها

رمز البنية

تتيح لك 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 أو جداول بيانات Google أو العروض التقديمية من Google أو نماذج Google. يمكنك إنشاء نص برمجي جديد مرتبط بحاوية ومرفق بملف جديد باستخدام الأمر clasp create. يمكنك أيضًا إرفاق نص برمجي جديد بملف حالي باستخدام العلامة --parentId.

أنواع المشاريع الأخرى

تتيح clasp أيضًا إنشاء نصوص برمجية لتطبيقات الويب وواجهات برمجة التطبيقات.

المتطلبات

clasp مكتوب بلغة Node.js ويتم توزيعه باستخدام الأداة npm. قبل استخدام clasp، يجب أن يكون لديك الإصدار 20.0.0 أو إصدار أحدث من Node.js مثبّتًا. يتطلب تثبيت Node.js امتيازات المشرف.

تثبيت

بعد تثبيت Node.js، استخدِم الأمر npm التالي لتثبيت clasp:

npm install @google/clasp -g

بعد التثبيت، استخدِم الأمر clasp من أي دليل على جهاز الكمبيوتر.

استخدام clasp

استخدِم clasp للتعامل مع مجموعة متنوعة من المهام من سطر الأوامر. يوضّح هذا القسم العمليات الشائعة التي يجب استخدامها عند التطوير باستخدام clasp.

تسجيل الدخول

يسجّل هذا الأمر الدخول ويمنح الإذن بإدارة مشاريع برمجة تطبيقات في حسابك على Google. بعد تشغيلها، سيُطلب منك تسجيل الدخول إلى حساب Google حيث يتم تخزين مشاريعك على "برمجة تطبيقات Google".

clasp login

تسجيل الخروج

يؤدي هذا الأمر إلى تسجيل الخروج من أداة سطر الأوامر. أعِد تسجيل الدخول باستخدام clasp login لإعادة المصادقة مع Google قبل مواصلة استخدام clasp.

clasp logout

إنشاء مشروع جديد في "برمجة تطبيقات Google"

ينشئ هذا الأمر نصًا برمجيًا جديدًا في الدليل الحالي مع عنوان اختياري للنص البرمجي.

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

يستخدم هذا الأمر المَعلمات الاختيارية التالية:

• ‫scriptTitle: عنوان مشروع النص البرمجي
• --type <projectType>: نوع المشروع الذي تريد إنشاءه القيم المسموح بها هي standalone وdocs وsheets وslides وforms وwebapp وapi.
• --parentId <parentId>: معرّف ملف Google Drive الحالي (مستندات Google أو جداول بيانات Google أو العروض التقديمية من Google أو نماذج Google) الذي يجب ربط مشروع البرنامج النصي الجديد به.

ينشئ هذا الأمر أيضًا ملفَين في الدليل الحالي:

• ملف .clasp.json يخزّن رقم تعريف النص البرمجي
• ملف بيان مشروع appsscript.json يحتوي على البيانات الوصفية للمشروع

استنساخ مشروع حالي

ينسخ هذا الأمر مشروعًا حاليًا في الدليل الحالي. يجب إنشاء النص البرمجي أو مشاركته مع حسابك على Google. يمكنك تحديد مشروع البرنامج النصي الذي تريد استنساخه من خلال تقديم معرّف البرنامج النصي. يمكنك استنساخ المشاريع المستقلة والمشاريع المرتبطة بحاوية.

للعثور على معرّف النص البرمجي للمشروع، اتّبِع الخطوات التالية:

1. افتح مشروع برمجة تطبيقات.
2. على يمين الصفحة، انقر على إعدادات المشروع settings.

3. ضمن المعرّفات، انسخ معرّف النص البرمجي.

   نسخة طبق الأصل من المشبك

تنزيل مشروع نص برمجي

ينزّل هذا الأمر مشروع برمجة تطبيقات من Google Drive إلى نظام الملفات على جهاز الكمبيوتر.

clasp pull

تحميل مشروع نص برمجي

يحمّل هذا الأمر جميع ملفات مشروع نص برمجي من جهاز الكمبيوتر إلى Drive.

clasp push

عرض قائمة بإصدارات المشروع

يعرض هذا الأمر رقم ووصف كل إصدار من إصدارات مشروع البرنامج النصي.

clasp versions

تفعيل مشروع منشور

نشر مشاريع النصوص البرمجية كتطبيقات ويب أو إضافات Google Workspace أو ملفات تنفيذية يمكنك إنشاء عمليات نشر في أداة تعديل النصوص البرمجية أو في ملف البيان الخاص بالمشروع أو باستخدام clasp.

لنشر مشروع باستخدام clasp، عليك أولاً إنشاء إصدار غير قابل للتغيير من مشروع "برمجة تطبيقات Google". الإصدار هو "لقطة" لمشروع نص برمجي، وهو يشبه إصدارًا متفرّعًا للقراءة فقط.

clasp version [description]

يعرض هذا الأمر رقم الإصدار الذي تم إنشاؤه حديثًا. استخدِم هذا الرقم لنشر وإلغاء نشر مثيلات مشروعك:

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

يعدّل هذا الأمر عملية نشر حالية بإصدار ووصف جديدَين:

clasp redeploy <deploymentId> <version> <description>

إدراج عمليات النشر

يسرد هذا الأمر معرّفات عمليات نشر مشروع النص البرمجي وإصداراته وأوصافها.

clasp deployments

فتح المشروع في محرِّر برمجة تطبيقات

يفتح هذا الأمر مشروع نص برمجي في أداة تعديل النصوص البرمجية. يتم تشغيل المحرِّر كعلامة تبويب جديدة في متصفّح الويب التلقائي.

clasp open-script

المساهمة في مشروع clasp المفتوح المصدر

يمكنك المساهمة في clasp على GitHub.

التكامل المستمر والتسليم المستمر في برمجة تطبيقات باستخدام clasp وGitHub Actions

يغطّي هذا الدليل عملية إعداد عمليات آلية للتحليل باستخدام أداة Lint والاختبار والتفعيل لمشاريع "برمجة تطبيقات Google" باستخدام clasp وGitHub Actions.

1. المتطلبات الأساسية

قبل البدء، أكمِل خطوات الإعداد في المتطلبات.

عليك أيضًا استيفاء ما يلي:

• مستودع GitHub
• تم تفعيل واجهة برمجة التطبيقات "برمجة التطبيقات" في script.google.com/home/usersettings.

2. المصادقة في CI

بما أنّ برامج تشغيل التكامل المستمر لا يمكنها فتح متصفّح لبروتوكول OAuth، يمكنك تخزين بيانات الاعتماد على أنّها أسرار GitHub:

يمنح الرمز المميز لإعادة التحميل في .clasprc.json إذن الوصول إلى مشاريعك في "برمجة تطبيقات Google". تعامَل معها كبيانات اعتماد حساسة وغيِّرها بشكل دوري.

أضِف .clasprc.json و.clasp.json إلى .gitignore. وتحتوي هذه الملفات على بيانات اعتماد ويجب عدم إضافتها إلى المستودع.

3- سير عمل CI — التدقيق والاختبار في طلبات السحب

.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 الرمز البرمجي عن بُعد بدون تأكيد. بعد إعداد مسار العمل هذا، تجنَّب إجراء تعديلات يدوية في محرّر برمجة تطبيقات، لأنّ المستودع يصبح المصدر الوحيد الموثوق به.

5- النشر في بيئات متعددة

بالنسبة إلى بيئات التطوير/الاختبار/الإنتاج المنفصلة، أنشئ مشروعًا منفصلاً في "برمجة تطبيقات Google" لكل بيئة وخزِّن إعداداتها كأسرار منفصلة (CLASP_JSON_DEV وCLASP_JSON_STAGING وCLASP_JSON_PROD). في سير العمل، اكتب السر المناسب في .clasp.json استنادًا إلى الفرع الذي يتم نشره.

تحديد المشاكل وحلّها

محتوى إضافي للقراءة

• مستندات GitHub Actions