Nhập và xuất dự án

Vì các dự án Apps Script nằm trên Google Drive, nên nhà phát triển có thể nhập và xuất mã nguồn Apps Script bằng API Google Drive (không nhầm lẫn với Dịch vụ Drive trong Apps Script).

Ví dụ: nhà phát triển có thể tạo mã Apps Script mới trên máy cục bộ bằng trình chỉnh sửa mã mà cô ấy yêu thích và sử dụng hệ thống kiểm soát phiên bản như Git để cộng tác với các nhà phát triển khác. Khi hoàn tất một phiên bản, cô ấy có thể tải (nhập) các tệp lên Google Drive bằng REST API. Tại đây, các tệp này có thể được dùng như mọi dự án Apps Script khác.

Bạn có thể thực hiện các thay đổi về mã trên phiên bản cục bộ và đồng bộ hoá với dự án Apps Script bằng Google Drive API. Bạn có thể tải (xuất) các dự án hiện có từ Google Drive xuống thiết bị cục bộ.

Tính năng và hạn chế

Nếu bạn muốn sử dụng Google Drive API để nhập hoặc xuất dự án, hãy lưu ý những điều sau:

  1. Các tệp kịch bản phía máy chủ dự kiến sẽ có đuôi ".gs". Bạn có thể muốn phát triển cục bộ bằng cách sử dụng tệp .js, nhưng hãy nhớ đổi tên để có đuôi .gs trước khi nhập vào Google Drive.
  2. Tệp tập lệnh phía máy khách phải có đuôi ".html". Trong đó có các tệp .html, .js hoặc .css phía máy khách. Một lần nữa, bạn có thể phát triển cục bộ bằng các tiện ích khác, nhưng điều quan trọng là phải có tiện ích .html trước khi nhập vào Google Drive.
  3. Khi bạn nhập tệp dự án vào Google Drive, tất cả dữ liệu hiện có trong các tệp đó sẽ bị ghi đè. Bạn không thể thêm hoặc chèn một phần văn bản; bạn phải cập nhật toàn bộ tệp.
  4. Tệp tập lệnh phía máy chủ phải chứa JavaScript hợp lệ. Nếu có lỗi trong các tệp .js trên máy chủ, lệnh gọi cập nhật Google Drive API sẽ không thành công và trả về lỗi 5xx. Bạn có thể ngăn chặn điều này bằng cách kiểm tra mã trước khi nhập.
  5. Không thể nhập tệp trống. Lệnh gọi cập nhật Google Drive API sẽ gặp lỗi 5xx nếu bạn cố gắng tải một tệp trống lên.
  6. Bạn chỉ có thể nhập hoặc xuất các tập lệnh độc lập. Không thể truy cập vào tập lệnh liên kết với vùng chứa thông qua API Google Drive.
  7. Bạn chỉ có thể nhập hoặc xuất mã nguồn. Các tài nguyên như nhật ký hoặc thuộc tính dự án cũng không được hiển thị thông qua Google Drive API. Bạn không thể thực hiện các thao tác như tạo phiên bản tập lệnh, xuất bản hoặc thực thi tập lệnh thông qua API Google Drive.
  8. Bạn không bị giới hạn ở một tệp Code.gs duy nhất trên máy chủ. Bạn có thể trải rộng mã máy chủ trên nhiều tệp để dễ dàng phát triển. Tất cả các tệp máy chủ đều được tải vào cùng một không gian tên chung, vì vậy, hãy sử dụng các lớp JavaScript khi bạn muốn cung cấp tính năng đóng gói an toàn.

API Drive

Google Drive API cho phép nhà phát triển truy cập vào các tệp trong Google Drive theo cách lập trình. API này dùng GET để tải tệp xuống và PUT/POST để tải tệp lên. Vui lòng tham khảo trang Tổng quan về Google Drive API để biết tài liệu chi tiết và hướng dẫn nhanh.

Hướng dẫn này sẽ tập trung vào việc liệt kê và di chuyển tệp bằng Tài nguyên tệp bằng các lệnh gọi sau:

Ủy quyền

Tất cả các yêu cầu đối với Google Drive API phải được người dùng đã xác thực cấp phép thông qua giao thức OAuth 2.0. Để biết thêm thông tin chi tiết, vui lòng tham khảo tài liệu uỷ quyền Google Drive API.

Ngoài các phạm vi khác mà một ứng dụng có thể cần (chẳng hạn như https://www.googleapis.com/auth/drive), tất cả các ứng dụng cố gắng nhập hoặc xuất dự án Google Apps Script đều phải yêu cầu phạm vi đặc biệt:

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

Liệt kê các dự án hiện có

Để liệt kê tất cả các dự án Apps Script trong Drive, hãy sử dụng Tài nguyên tệp để truy vấn các tệp có loại MIME là application/vnd.google-apps.script. Để lọc phản hồi chỉ bao gồm các tệp bạn sở hữu, hãy thêm tham số tìm kiếm 'me' in owners.

Sau đây là yêu cầu và phản hồi mẫu cho thấy một mảng các dự án Apps Script được trả về thông qua phản hồi 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
  }
 ]
}

Nếu biết mã nhận dạng tệp của một dự án Apps Script, bạn có thể tìm nạp trực tiếp dự án đó bằng lệnh gọi API sau:

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

Xuất dự án từ Drive

Sau khi bạn nhận được tài nguyên File từ API, thuộc tính exportLinks sẽ chứa một URL để tìm nạp nhằm lấy nội dung của dự án dưới dạng dữ liệu JSON. Sau đây là ví dụ về URL này:

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

Đưa ra yêu cầu đến URL này để truy xuất nội dung của chính dự án. Đảm bảo rằng bạn thêm một tiêu đề Authorization có cùng mã thông báo OAuth Bearer

Sau đây là yêu cầu và phản hồi mẫu:

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"
    }
  ]
}

Ví dụ trên có chứa mã cho một ứng dụng web đơn giản trong hướng dẫn HTMLService. Xin lưu ý rằng bạn sẽ nhận được một mảng Files, mỗi mảng có 4 thuộc tính sau:

id Giá trị nhận dạng nội bộ của một tệp trong dự án, cần thiết để tham chiếu tệp này trong quá trình cập nhật.
name Tên của tệp không có đuôi, như xuất hiện trong Trình chỉnh sửa kịch bản.
type Hai loại tệp này là server_js và html.
source Mã nguồn được mã hoá có trong tệp.

Nhập dự án vào Drive

Để cập nhật một dự án hiện có, hãy thực hiện lệnh gọi HTTP PUT đến API update của tệp bằng fileId thích hợp. Ví dụ bên dưới cho thấy một giao dịch mẫu cho phần tải nội dung nghe nhìn lên. Khi sử dụng một trong các thư viện ứng dụng, ứng dụng của bạn có thể dễ dàng đưa siêu dữ liệu và nội dung nghe nhìn vào cùng một lệnh gọi tải lên. Xin lưu ý rằng tiêu đề Content-Type chỉ định loại nội dung được tải lên trong trường hợp này.

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"
    }
  ]
}

Tạo tệp mới trong một dự án

Để tạo một tệp mới trong dự án, hãy gửi yêu cầu PUT cho một tệp không có thuộc tính id. Nếu bạn thêm một tệp có mã nhận dạng không xác định, hệ thống sẽ đưa ra thông báo lỗi.

Xoá tệp trong dự án

Để xoá một tệp khỏi dự án, hãy gửi một yêu cầu PUT không bao gồm tệp đó (nhưng bao gồm tất cả các tệp khác trong dự án). Mọi tệp không được gửi lại trong quá trình nhập sẽ bị xoá khỏi máy chủ.

Đổi tên tệp trong dự án

Để đổi tên một tệp trong dự án, hãy gửi yêu cầu PUT bằng id hiện có nhưng có name mới. Xin lưu ý rằng máy chủ sẽ bỏ qua mọi nỗ lực thay đổi thành type.

Tạo dự án mới

Để tạo một dự án mới, hãy gửi yêu cầu POST đến tệp insert API. Tương tự như lệnh gọi update, bạn có thể sử dụng một thư viện ứng dụng để thêm siêu dữ liệu, chẳng hạn như tên và nội dung mô tả dự án.

Sau đây là một giao dịch mẫu về việc tải tệp đa phương tiện lên. Thao tác này sẽ tạo một dự án có tên "Chưa có tiêu đề" trong Drive của bạn. Bạn phải thêm tham số convert vào URL. Giống như lệnh gọi update, bạn phải có tiêu đề 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"
    }
  ]
}