Como os projetos do Apps Script residem no Google Drive, os desenvolvedores podem importar e exportar o código-fonte do Apps Script usando a API Google Drive. Não confunda com o serviço do Drive no Apps Script.
Por exemplo, um desenvolvedor pode criar um novo código do Apps Script na máquina local com o editor de código que mais gosta e usar um sistema de controle de versões, como o Git, para colaborar com outros desenvolvedores. Quando uma versão é finalizada, ela pode fazer upload (importação) dos arquivos para o Google Drive usando a API REST, em que podem ser usados como qualquer outro projeto do Apps Script.
É possível fazer alterações de código nas versões locais e sincronizar com o projeto do Apps Script usando a API Google Drive. É possível fazer o download dos projetos existentes (exportados) do Google Drive para uma máquina local.
Recursos e limitações
Se você quiser usar a API Google Drive para importar ou exportar projetos, esteja ciente do seguinte:
- Os arquivos de script do lado do servidor devem terminar com ".gs". Você pode desenvolver localmente usando arquivos .js, mas lembre-se de renomear para incluir uma extensão .gs antes de importar para o Google Drive.
- Os arquivos de script do lado do cliente precisam terminar com ".html". Isso inclui arquivos .html, .js ou .css do lado do cliente. Novamente, é possível desenvolver localmente usando outras extensões, mas é importante ter a extensão .html antes de importar para o Google Drive.
- Quando você importa arquivos do projeto para o Google Drive, todos os dados existentes neles serão substituídos. Não é possível anexar ou inserir texto parcial. O arquivo inteiro precisa ser atualizado.
- Os arquivos de script do lado do servidor precisam conter JavaScript válido. Se houver erros nos arquivos .js do servidor, a chamada de atualização da API Google Drive falhará com um erro 5xx. É possível evitar isso realizando uma inspeção no seu código antes da importação.
- Não é possível importar arquivos vazios. A chamada de atualização da API Google Drive falhará com um erro 5xx se você tentar fazer upload de um arquivo vazio.
- Somente scripts independentes podem ser importados ou exportados. Os scripts vinculados a contêiner não podem ser acessados usando a API Google Drive.
- Somente código-fonte pode ser importado ou exportado. Recursos como propriedades ou registros do projeto também não são expostos pela API Google Drive. Não é possível realizar ações como controle de versões, publicação ou execução do script usando a API Google Drive.
- Você não está limitado a um único arquivo
Code.gs
de servidor. É possível espalhar o código do servidor em vários arquivos para facilitar o desenvolvimento. Todos os arquivos do servidor são carregados no mesmo namespace global. Portanto, use classes JavaScript quando quiser oferecer encapsulamento seguro.
API Drive
Com a API Google Drive, os desenvolvedores podem acessar arquivos no Google Drive de maneira programática. Essa API usa GET
para fazer o download de arquivos e PUT/POST
para fazer upload
de arquivos. Consulte a página Visão geral da API Google Drive para ver a documentação detalhada e os guias de início rápido.
Este guia se concentra em listar e mover arquivos com o recurso Files usando estas chamadas:
Autorização
Todas as solicitações para a API Google Drive precisam ser autorizadas por um usuário autenticado por meio do protocolo OAuth 2.0. Para mais detalhes, consulte a documentação de autorização da API Google Drive.
Além dos outros escopos que um aplicativo pode precisar
(como https://www.googleapis.com/auth/drive
), todos os aplicativos que tentam
importar ou exportar projetos do Google Apps Script precisam solicitar o escopo especial:
https://www.googleapis.com/auth/drive.scripts
Listar projetos atuais
Se você quiser listar todos os projetos do Apps Script no Drive, use o recurso Files
para consultar arquivos com o tipo MIME application/vnd.google-apps.script
.
Para filtrar a resposta e incluir apenas arquivos que pertencem a você, inclua o parâmetro de pesquisa 'me' in owners
.
Veja a seguir um exemplo de solicitação e resposta que mostra uma matriz de projetos do Apps Script retornados por uma resposta 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 } ] }
Se você sabe o ID do arquivo de um projeto do Apps Script, pode buscá-lo diretamente com a seguinte chamada de API:
GET https://www.googleapis.com/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz
Authorization: Bearer ya29.fakebearerstring
Exportar projetos do Drive
Depois de receber um recurso File
da API,
a propriedade exportLinks
terá um URL a ser buscado para acessar o conteúdo do
projeto como dados JSON. Veja um exemplo de como esse URL pode ser:
https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json
Faça uma solicitação para este URL para recuperar o conteúdo do próprio projeto.
Inclua um cabeçalho Authorization
com o mesmo token OAuth Bearer
Veja um exemplo de solicitação e resposta:
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" } ] }
O exemplo acima inclui o código para um app da Web simples do guia de Serviço HTML. Observe
que você recebe uma matriz de Files
, cada uma com estas quatro propriedades:
id |
Identificador interno de um arquivo em um projeto, necessário para fazer referência a esse arquivo durante as atualizações. |
name |
O nome do arquivo sem extensões, conforme exibido no Editor de scripts. |
type |
Os dois tipos de arquivo são server_js e html. |
source |
O código-fonte codificado contido no arquivo. |
Importar projetos para o Drive
Para atualizar um projeto, faça uma chamada HTTP PUT
para a API de arquivo
update
com o fileId
apropriado.
O exemplo abaixo mostra uma transação de amostra para a parte de upload de mídia. Usando
uma das bibliotecas de cliente, seu aplicativo pode incluir facilmente
metadados e a mídia na mesma chamada de upload. Observe que o
cabeçalho Content-Type
especifica o tipo de conteúdo enviado nesse caso.
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" } ] }
Criar novos arquivos em um projeto
Para criar um novo arquivo em um projeto, envie uma solicitação PUT
para um arquivo sem a propriedade id
. Se você incluir um arquivo com um identificador desconhecido, o sistema
gerará uma mensagem de erro.
Excluir arquivos de um projeto
Para excluir um arquivo de um projeto, envie uma solicitação PUT
que não inclua
esse arquivo, mas que inclua todos os outros arquivos do projeto. Qualquer arquivo que não seja enviado de volta durante o processo de importação será excluído do servidor.
Renomear arquivos em um projeto
Para renomear um arquivo em um projeto, envie uma solicitação PUT
com o id
existente,
mas um novo name
. O servidor ignora todas as tentativas de mudança para type
.
Criar projeto
Para criar um novo projeto, envie uma solicitação POST
para a API de arquivo
insert
. Assim como na chamada update
, é possível usar uma biblioteca de cliente para incluir metadados, como o nome e a descrição do projeto.
Veja um exemplo de transação do upload de mídia. Isso criará um projeto
chamado "Untitled" no Drive. O parâmetro convert
no URL é obrigatório.
Assim como na chamada update
, o cabeçalho Content-Type
é obrigatório.
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" } ] }