واردات و صادرات پروژه ها

از آنجایی که پروژه‌های Apps Script در گوگل درایو قرار دارند، توسعه‌دهندگان می‌توانند کد منبع Apps Script را با استفاده از API گوگل درایو (با سرویس درایو در Apps Script اشتباه گرفته نشود) وارد و صادر کنند.

برای مثال، یک توسعه‌دهنده می‌تواند کد Apps Script جدید را روی دستگاه محلی خود با ویرایشگر کد مورد علاقه‌اش بنویسد و از یک سیستم کنترل نسخه مانند Git برای همکاری با سایر توسعه‌دهندگان استفاده کند. وقتی یک نسخه نهایی شد، او می‌تواند فایل‌ها را با استفاده از REST API در Google Drive آپلود (import) کند، جایی که می‌توان از آنها مانند هر پروژه Apps Script دیگری استفاده کرد.

تغییرات کد را می‌توان در نسخه‌های محلی انجام داد و با استفاده از API گوگل درایو با پروژه Apps Script همگام‌سازی کرد. پروژه‌های موجود را می‌توان از گوگل درایو به یک دستگاه محلی دانلود (export) کرد.

ویژگی‌ها و محدودیت‌ها

اگر می‌خواهید از API گوگل درایو برای وارد کردن یا صادر کردن پروژه‌ها استفاده کنید، موارد زیر را در نظر داشته باشید:

  1. انتظار می‌رود فایل‌های اسکریپت سمت سرور به ".gs" ختم شوند. ممکن است بخواهید با استفاده از فایل‌های .js به صورت محلی توسعه دهید، اما قبل از وارد کردن به Google Drive، مطمئن شوید که نام فایل را تغییر داده و پسوند .gs را به آن اضافه می‌کنید.
  2. فایل‌های اسکریپت سمت کلاینت باید با پسوند ".html" خاتمه یابند. این شامل فایل‌های سمت کلاینت با پسوندهای .html، .js یا .css می‌شود. باز هم، می‌توانید با استفاده از پسوندهای دیگر، به صورت محلی توسعه دهید، اما مهم است که قبل از وارد کردن به گوگل درایو، پسوند .html را داشته باشید.
  3. وقتی فایل‌های پروژه را به گوگل درایو وارد می‌کنید، تمام داده‌های موجود در آن فایل‌ها رونویسی می‌شوند. نمی‌توانید متن را اضافه یا بخشی از آن را وارد کنید؛ کل فایل باید به‌روزرسانی شود.
  4. فایل‌های اسکریپت سمت سرور باید حاوی جاوا اسکریپت معتبر باشند. اگر در فایل‌های .js سرور شما خطایی وجود داشته باشد، فراخوانی به‌روزرسانی API گوگل درایو با خطای 5xx با شکست مواجه می‌شود. می‌توانید با اصلاح کد خود قبل از وارد کردن، از این امر جلوگیری کنید.
  5. فایل‌های خالی قابل وارد کردن نیستند. اگر سعی کنید یک فایل خالی آپلود کنید، فراخوانی به‌روزرسانی API گوگل درایو با خطای 5xx با شکست مواجه می‌شود.
  6. فقط اسکریپت‌های مستقل می‌توانند وارد یا صادر شوند. اسکریپت‌های متصل به کانتینر از طریق API گوگل درایو قابل دسترسی نیستند.
  7. فقط کد منبع را می‌توان وارد یا صادر کرد. منابعی مانند ویژگی‌های پروژه یا گزارش‌ها نیز از طریق API گوگل درایو در معرض دید قرار نمی‌گیرند. اقداماتی مانند نسخه‌بندی اسکریپت، انتشار یا اجرای اسکریپت از طریق API گوگل درایو امکان‌پذیر نیست.
  8. شما محدود به یک فایل Code.gs سرور نیستید. می‌توانید کد سرور را برای سهولت توسعه، در چندین فایل پخش کنید. همه فایل‌های سرور در یک فضای نام سراسری یکسان بارگذاری می‌شوند، بنابراین وقتی می‌خواهید کپسوله‌سازی امنی ارائه دهید، از کلاس‌های جاوا اسکریپت استفاده کنید.

درایو API

API گوگل درایو به توسعه‌دهندگان اجازه می‌دهد تا به صورت برنامه‌نویسی شده به فایل‌های موجود در گوگل درایو دسترسی داشته باشند. این API از GET برای دانلود فایل‌ها و PUT/POST برای آپلود فایل‌ها استفاده می‌کند. لطفاً برای مشاهده مستندات دقیق و شروع سریع، به صفحه مرور کلی API گوگل درایو مراجعه کنید.

این راهنما بر فهرست کردن و جابجایی فایل‌ها با استفاده از منبع Files و با استفاده از این فراخوانی‌ها تمرکز خواهد کرد:

مجوز

تمام درخواست‌ها به API گوگل درایو باید توسط یک کاربر احراز هویت شده از طریق پروتکل OAuth 2.0 تأیید شوند. برای جزئیات بیشتر، لطفاً به مستندات تأیید API گوگل درایو مراجعه کنید.

علاوه بر سایر حوزه‌هایی که یک برنامه ممکن است به آنها نیاز داشته باشد (مانند https://www.googleapis.com/auth/drive )، تمام برنامه‌هایی که سعی در وارد کردن یا صادر کردن پروژه‌های اسکریپت Google Apps دارند، باید حوزه ویژه زیر را درخواست کنند:

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

فهرست پروژه‌های موجود

برای فهرست کردن تمام پروژه‌های اسکریپت برنامه‌ها در درایو خود، از منبع Files برای جستجوی فایل‌هایی با نوع MIME application/vnd.google-apps.script استفاده کنید. برای فیلتر کردن پاسخ به گونه‌ای که فقط فایل‌های متعلق به شما را شامل شود، پارامتر جستجوی 'me' in owners وارد کنید.

در اینجا یک نمونه درخواست و پاسخ وجود دارد که آرایه‌ای از پروژه‌های Apps Script را نشان می‌دهد که از طریق یک پاسخ JSON برگردانده شده‌اند.

GET https://www.googleapis.com/drive/v2/files?q=mimeType%3D'application%2Fvnd.google-apps.script'+and+'me'+in+owners
Authorization:  Bearer ya29.fakebearerstring
{
 "kind": "drive#fileList",
 "etag": "\"kjsas92/f3zGUXczKMxEB_9ZTMRFOF3d1ZU\"",
 "selfLink": "https://www.googleapis.com/drive/v2/files?q=mimeType%3D'application/vnd.google-apps.script'+and+'me'+in+owners",
 "items": [
  {
   "kind": "drive#file",
   "id": "1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D",
   "etag": "\"kjsas92/MTM3MDk3ODY5ODQyNg\"",
   "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D",
   "alternateLink": "https://script.google.com/a/google.com/d/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/edit?usp=drivesdk",
   "iconLink": "https://ssl.gstatic.com/docs/doclist/images/icon_11_script_list.png",
   "title": "Mail merge",
   "mimeType": "application/vnd.google-apps.script",
   "description": "",
   "labels": {
    "starred": false,
    "hidden": false,
    "trashed": true,
    "restricted": false,
    "viewed": true
   },
   "createdDate": "2013-06-11T19:24:45.188Z",
   "modifiedDate": "2013-06-11T19:24:58.426Z",
   "modifiedByMeDate": "2013-06-11T19:24:58.426Z",
   "lastViewedByMeDate": "2013-06-11T19:24:58.426Z",
   "parents": [
    {
     "kind": "drive#parentReference",
     "id": "0APdyIOzo7bWDUk9PVA",
     "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/parents/0APdyIOzo7bWDUk9PVA",
     "parentLink": "https://www.googleapis.com/drive/v2/files/0APdyIOzo7bWDUk9PVA",
     "isRoot": true
    }
   ],
   "exportLinks": {
    "application/json": "https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json"
   },
   "userPermission": {
    "kind": "drive#permission",
    "etag": "\"kjsas92/259X2r5DVstv1CcIQTjt_RQPSW8\"",
    "id": "me",
    "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/permissions/me",
    "role": "owner",
    "type": "user"
   },
   "quotaBytesUsed": "0",
   "ownerNames": [
    "John Doe"
   ],
   "owners": [
    {
     "kind": "drive#user",
     "displayName": "John Doe",
     "picture": {
      "url": "https://lh4.googleusercontent.com/-yd1rIb6Pe2Y/AAAAAAAAAAI/AAAAAAAAAGs/PP5vTuZonik/s64/photo.jpg"
     },
     "isAuthenticatedUser": true,
     "permissionId": "1234566789"
    }
   ],
   "lastModifyingUserName": "John Doe",
   "lastModifyingUser": {
    "kind": "drive#user",
    "displayName": "John Doe",
    "picture": {
     "url": "https://lh4.googleusercontent.com/-yd1rIb6Pe2Y/AAAAAAAAAAI/AAAAAAAAAGs/PP5vTuZonik/s64/photo.jpg"
    },
    "isAuthenticatedUser": true,
    "permissionId": "1234566789"
   },
   "editable": true,
   "writersCanShare": true,
   "shared": false,
   "explicitlyTrashed": true,
   "appDataContents": false
  }
 ]
}

اگر شناسه فایل یک پروژه Apps Script را می‌دانید، می‌توانید مستقیماً آن را با فراخوانی API زیر دریافت کنید:

GET https://www.googleapis.com/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz
Authorization:  Bearer ya29.fakebearerstring

پروژه‌ها را از Drive صادر کنید

زمانی که یک منبع File را از API دریافت کردید، ویژگی exportLinks شامل یک URL برای واکشی و دریافت محتوای پروژه به صورت داده‌های JSON خواهد بود. در اینجا نمونه‌ای از این URL را مشاهده می‌کنید:

https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json

برای بازیابی محتوای خود پروژه، یک درخواست به این URL ارسال کنید. مطمئن شوید که یک هدر Authorization با همان توکن OAuth Bearer اضافه کرده‌اید.

در اینجا یک نمونه درخواست و پاسخ آمده است:

GET https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json
Authorization:  Bearer ya29.fakebearerstring
{
  "files": [
    {
      "id":"9basdfbd-749a-4as9b-b9d1-d64basdf803",
      "name":"Code",
      "type":"server_js",
      "source":"function doGet() {\n  return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n"
    },
    {
      "id":"3asf7c0d-1afb-4a9-8431-5asdfc79e7ae",
      "name":"index",
      "type":"html",
      "source":"\u003chtml\u003e\n  \u003cbody\u003e\n    Hello, world!\n  \u003c/body\u003e\n\u003c/html\u003e"
    }
  ]
}

مثال بالا شامل کد یک برنامه وب ساده از راهنمای سرویس HTML است. توجه داشته باشید که آرایه‌ای از Files را برمی‌گردانید که هر کدام دارای 4 ویژگی زیر هستند:

id شناسه داخلی یک فایل در یک پروژه، که برای ارجاع به این فایل در هنگام به‌روزرسانی‌ها مورد نیاز است.
name نام فایل بدون پسوند، همانطور که در ویرایشگر اسکریپت نمایش داده می‌شود.
type دو نوع فایل server_js و html هستند.
source کد منبع کدگذاری شده موجود در فایل.

وارد کردن پروژه‌ها به Drive

برای به‌روزرسانی یک پروژه موجود، یک فراخوانی HTTP PUT به API update فایل با fileId مناسب انجام دهید. مثال زیر یک تراکنش نمونه برای بخش آپلود رسانه را نشان می‌دهد. با استفاده از یکی از کتابخانه‌های کلاینت ، برنامه شما می‌تواند به راحتی فراداده و رسانه را در یک فراخوانی آپلود قرار دهد. توجه داشته باشید که هدر Content-Type در این مورد نوع محتوای آپلود شده را مشخص می‌کند.

PUT https://www.googleapis.com/upload/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz
Authorization:  Bearer ya29.fakebearerestring
Content-Type:  application/vnd.google-apps.script+json
{
  "files": [
    {
      "id":"9basdfbd-749a-4as9b-b9d1-d64basdf803",
      "name":"Code",
      "type":"server_js",
      "source":"function doGet() {\n  return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n"
    },
    {
      "id":"3asf7c0d-1afb-4a9-8431-5asdfc79e7ae",
      "name":"index",
      "type":"html",
      "source":"\u003chtml\u003e\n  \u003cbody\u003e\n    New message!!\n  \u003c/body\u003e\n\u003c/html\u003e"
    }
  ]
}

ایجاد فایل‌های جدید درون یک پروژه

برای ایجاد یک فایل جدید در یک پروژه، یک درخواست PUT برای فایلی بدون مشخصه id ارسال کنید. اگر فایلی با شناسه ناشناخته را اضافه کنید، سیستم یک پیام خطا نمایش می‌دهد.

حذف فایل‌های درون یک پروژه

برای حذف یک فایل از یک پروژه، یک درخواست PUT ارسال کنید که شامل آن فایل نباشد (اما شامل تمام فایل‌های دیگر موجود در پروژه باشد). هر فایلی که در طول فرآیند وارد کردن ارسال نشود، از سرور حذف خواهد شد.

تغییر نام فایل‌ها در یک پروژه

برای تغییر نام یک فایل در یک پروژه، یک درخواست PUT با id موجود اما name جدید ارسال کنید. توجه داشته باشید که سرور هرگونه تلاش برای تغییر به type را نادیده می‌گیرد.

ایجاد پروژه جدید

برای ایجاد یک پروژه جدید، یک درخواست POST به API insert فایل ارسال کنید. بسیار شبیه به فراخوانی update ، می‌توانید از یک کتابخانه کلاینت برای درج فراداده‌هایی مانند نام و توضیحات پروژه استفاده کنید.

در اینجا یک نمونه تراکنش آپلود رسانه آورده شده است. این کار پروژه‌ای به نام "Untitled" را در Drive شما ایجاد می‌کند. پارامتر convert در URL الزامی است. همانند فراخوانی update ، هدر Content-Type نیز الزامی است.

POST https://www.googleapis.com/upload/drive/v2/files?convert=true
Authorization:  Bearer ya29.fakebearerestring
Content-Type:  application/vnd.google-apps.script+json
{
  "files": [
    {
      "name":"Code",
      "type":"server_js",
      "source":"function doGet() {\n  return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n"
    },
    {
      "name":"index",
      "type":"html",
      "source":"\u003chtml\u003e\n  \u003cbody\u003e\n    Hello, world!!\n  \u003c/body\u003e\n\u003c/html\u003e"
    }
  ]
}