Импорт и экспорт проектов

Поскольку проекты Google Apps Script размещаются на Google Drive, разработчики могут импортировать и экспортировать исходный код Apps Script, используя API Google Drive (не путать со службой Drive в Apps Script).

Например, разработчик может создавать новый код Apps Script на своем локальном компьютере с помощью любимого редактора кода и использовать систему контроля версий, такую ​​как Git, для совместной работы с другими разработчиками. После завершения работы над версией она может загрузить (импортировать) файлы на Google Drive с помощью REST API, где их можно использовать как любой другой проект Apps Script.

Изменения в коде можно вносить в локальные версии и синхронизировать с проектом Apps Script с помощью API Google Drive. Существующие проекты можно загрузить (экспортировать) из Google Drive на локальный компьютер.

Особенности и ограничения

Если вы хотите использовать API Google Drive для импорта или экспорта проектов, обратите внимание на следующее:

  1. Файлы серверных скриптов должны заканчиваться на ".gs". Вы можете разрабатывать локально, используя файлы .js, но обязательно переименуйте их, добавив расширение .gs, перед импортом в Google Диск.
  2. Скриптовые файлы на стороне клиента должны заканчиваться на ".html". Это относится и к клиентским файлам .html, .js или .css. Конечно, вы можете разрабатывать локально, используя другие расширения, но важно иметь расширение .html перед импортом в Google Диск.
  3. При импорте файлов проекта в Google Диск все существующие данные в этих файлах будут перезаписаны. Вы не можете добавлять или вставлять части текста; необходимо обновить весь файл.
  4. Скриптовые файлы на стороне сервера должны содержать корректный JavaScript. Если в ваших серверных файлах .js есть ошибки, вызов обновления API Google Drive завершится с ошибкой 5xx. Этого можно избежать, проверив код на наличие ошибок перед импортом.
  5. Импорт пустых файлов невозможен. При попытке загрузки пустого файла вызов обновления API Google Drive завершится ошибкой 5xx.
  6. Импортировать и экспортировать можно только автономные скрипты. Доступ к скриптам , привязанным к контейнеру, через API Google Drive невозможен.
  7. Импортировать и экспортировать можно только исходный код. Ресурсы, такие как свойства проекта или журналы, также не предоставляются через API Google Drive. Действия, такие как версионирование скриптов, публикация или выполнение скриптов, невозможны с использованием API Google Drive.
  8. Вы не ограничены одним файлом Code.gs для сервера. Вы можете распределить код сервера по нескольким файлам для упрощения разработки. Все файлы сервера загружаются в одно глобальное пространство имен, поэтому используйте классы JavaScript, если хотите обеспечить безопасную инкапсуляцию.

API для управления дисками

API Google Drive позволяет разработчикам программно получать доступ к файлам в Google Drive. Для загрузки файлов используется GET , а для выгрузки — PUT/POST . Подробную документацию и краткие инструкции см. на странице «Обзор API Google Drive» .

В этом руководстве основное внимание уделяется перечислению и перемещению файлов с помощью ресурса Files, используя следующие вызовы:

Авторизация

Все запросы к API Google Drive должны быть авторизованы аутентифицированным пользователем с использованием протокола OAuth 2.0. Для получения более подробной информации обратитесь к документации по авторизации API Google Drive .

В дополнение к другим областям действия, которые могут потребоваться приложению (например, https://www.googleapis.com/auth/drive ), все приложения, пытающиеся импортировать или экспортировать проекты Google Apps Script, должны запросить специальную область действия:

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

Для проверки следующих примеров запросов используйте токен носителя OAuth 2.0, полученный из OAuth 2.0 Playground .

Список существующих проектов

Чтобы отобразить список всех проектов Apps Script на вашем Диске, используйте ресурс «Файлы» для поиска файлов с 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

Идентификатор файла проекта не совпадает с ключом проекта. Идентификатор файла — это буквенно-цифровая строка в URL-адресе проекта.

Экспорт проектов из 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 , вы можете использовать клиентскую библиотеку для включения метаданных, таких как название и описание проекта.

Вот пример транзакции загрузки медиафайлов. В результате в вашем Google Диске будет создан проект под названием "Без названия". Параметр 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"
    }
  ]
}