Aplicativos da Web

Se você criar uma interface do usuário para um script, poderá publicar o script como um app da Web. Por exemplo, um script que permite aos usuários agendar horários com membros de uma equipe de suporte seria melhor apresentado como um app da Web para que os usuários possam acessar diretamente dos navegadores.

Tanto os scripts independentes quanto os scripts vinculados a aplicativos Google Workspace podem ser transformados em apps da Web, desde que atendam aos requisitos abaixo.

Requisitos para apps da Web

Um script pode ser publicado como um web app se atender a estes requisitos:

• Ela contém uma função doGet(e) ou doPost(e).
• A função retorna um objeto HtmlOutput do serviço HTML ou um objeto TextOutput do serviço de conteúdo.

Parâmetros de solicitação

Quando um usuário visita um app ou um programa envia uma solicitação HTTP GET para o app, o Apps Script executa a função doGet(e). Quando um programa envia ao app uma solicitação HTTP POST, o Apps Script executa doPost(e). Em ambos os casos, o argumento e representa um parâmetro de evento que pode conter informações sobre qualquer parâmetro de solicitação. A estrutura do objeto de evento é mostrada na tabela abaixo:

Campos
e.queryString	O valor da parte da string de consulta do URL ou null se nenhuma string de consulta for especificada. name=alice&n=1&n=2
e.parameter	Um objeto de pares de chave-valor que correspondem aos parâmetros da solicitação. Apenas o primeiro valor é retornado para parâmetros com vários valores. {"name": "alice", "n": "1"}
e.parameters	Um objeto semelhante a e.parameter, mas com uma matriz de valores para cada chave {"name": ["alice"], "n": ["1", "2"]}
e.pathInfo	O caminho do URL após /exec ou /dev. Por exemplo, se o caminho do URL terminar em /exec/hello, as informações do caminho serão hello.
e.contextPath	Não usado, sempre a string vazia.
e.contentLength	O comprimento do corpo da solicitação para solicitações POST ou -1 para solicitações GET. 332
e.postData.length	O mesmo que e.contentLength 332
e.postData.type	O tipo MIME do corpo da solicitação POST text/csv
e.postData.contents	O texto do conteúdo do corpo POST Alice,21
e.postData.name	Sempre o valor "postData" postData

Por exemplo, é possível transmitir parâmetros como username e age para um URL, conforme mostrado abaixo:

https://script.google.com/.../exec?username=jsmith&age=21

Em seguida, você pode mostrar os parâmetros assim:

function doGet(e) {
  var params = JSON.stringify(e);
  return ContentService.createTextOutput(params).setMimeType(ContentService.MimeType.JSON);
}

No exemplo acima, doGet(e) retorna a seguinte saída:

{
  "queryString": "username=jsmith&age=21",
  "parameter": {
    "username": "jsmith",
    "age": "21"
  },
  "contextPath": "",
  "parameters": {
    "username": [
      "jsmith"
    ],
    "age": [
      "21"
    ]
  },
  "contentLength": -1
}

Aviso: os nomes de parâmetro a seguir são reservados pelo sistema e não devem ser usados em parâmetros de URL ou corpos POST:

• c
• sid

O uso desses parâmetros pode resultar em uma resposta HTTP 405 com a mensagem de erro "Desculpe, o arquivo solicitado não existe". Se possível, atualize o script para usar nomes de parâmetros diferentes.

Implantar um script como um app da Web

Para implantar um script como um app da Web, siga estas etapas:

1. No canto superior direito do projeto de script, clique em Implantar > Nova implantação.
2. Ao lado de "Selecionar tipo", clique em Habilitar tipos de implantação > Aplicativo da Web.
3. Insira as informações sobre seu web app nos campos em "Configuração de implantação".
4. Clique em Implantar.

Você pode compartilhar o URL do web app com quem quiser usar seu app, desde que tenha concedido acesso a essas pessoas.

Observação: os apps da Web implantados em um domínio deixam de funcionar se a propriedade deles mudar para uma unidade compartilhada ou conta em um domínio diferente. Para corrigir isso, o novo proprietário ou colaborador precisa implantar novamente o web app no novo domínio. Como alternativa, se o web app for movido de volta para o domínio original, ele vai começar a funcionar novamente para esse domínio sem precisar ser reimplantado.

Testar a implantação de um app da Web

Para testar seu script como um app da Web, siga as etapas abaixo:

1. No canto superior direito do projeto de script, clique em Implantar > Testar implantações.
2. Ao lado de "Selecionar tipo", clique em Habilitar tipos de implantação > Web app.
3. Abaixo do URL do web app, clique em Copiar.

4. Cole o URL no navegador e teste o web app.

   O URL termina em /dev e só pode ser acessado por usuários com acesso de edição ao script. Essa instância do app sempre executa o código salvo mais recentemente e destina-se apenas a testes durante o desenvolvimento.

Aviso: ao implantar apps da Web para serem executados como o desenvolvedor, tome muito cuidado ao processar tokens OAuth obtidos com ScriptApp.getOAuthToken(). Esses tokens podem conceder a outros aplicativos acesso aos seus dados. Nunca os transmita ao cliente.

Permissões

As permissões de um web app variam de acordo com a forma de execução do app:

• Executar o app como eu: nesse caso, o script sempre é executado como você, o proprietário do script, não importa quem acesse o app da Web.
• Executar o app como usuário que acessa o app da Web: nesse caso, o script é executado na identidade do usuário ativo que usa o app da Web. Essa abordagem de permissão faz com que o app da Web mostre o e-mail do proprietário do script quando o usuário autoriza o acesso.

Aviso: para evitar abusos, o Apps Script impõe limites à taxa em que novos usuários podem autorizar um web app que é executado como o usuário. Esses limites dependem, entre outros fatores, de a conta de publicação fazer parte de um domínio Google Workspace.

Observação: você pode colaborar em apps da Web usando um drive compartilhado. Quando um app da Web em um drive compartilhado é implantado, escolher "executar como você" faz com que o app da Web seja executado sob a autoridade do usuário que o implantou (já que não há um proprietário do script).

Incorporar seu app da Web no Google Sites

Aviso: os apps da Web incorporados ainda estão sujeitos a permissões de acesso para evitar uso malicioso. Se o web app incorporado não estiver funcionando, verifique se as permissões definidas pelo proprietário do web app e pelo administrador do domínio permitem o uso dele.

Para incorporar um web app no Google Sites, ele precisa ser implantado primeiro. Você também precisa do URL implantado da caixa de diálogo Deploy.

Para incorporar um app da Web em uma página do Sites, siga estas etapas:

1. Abra a página do Sites onde você quer adicionar o web app.
2. Selecione Inserir > Incorporar URL.
3. Cole o URL do web app e clique em ADICIONAR.

O web app aparece em um frame na prévia da página. Quando você publica a página, os leitores do site precisam autorizar o web app antes que ele seja executado normalmente. Os apps da Web não autorizados apresentam solicitações de autorização ao usuário.

Apps da Web e histórico do navegador

Pode ser interessante ter um web app do Apps Script simulando um aplicativo de várias páginas ou um com uma interface dinâmica controlada por parâmetros de URL. Para fazer isso bem, defina um objeto de estado para representar a interface ou página do app e envie o estado para o histórico do navegador à medida que o usuário navega pelo app. Você também pode detectar eventos de histórico para que o web app mostre a interface correta quando o usuário navegar para frente e para trás com os botões do navegador. Ao consultar os parâmetros de URL no momento do carregamento, você pode fazer com que seu app crie dinamicamente a interface com base nesses parâmetros, permitindo que o usuário inicie o app em um estado específico.

O Apps Script oferece duas APIs JavaScript assíncronas do lado do cliente para ajudar na criação de apps da Web vinculados ao histórico do navegador:

• google.script.history fornece métodos para permitir uma resposta dinâmica a mudanças no histórico do navegador. Isso inclui: envio de estados (objetos simples que você pode definir) para o histórico do navegador, substituição do estado superior na pilha de histórico e definição de uma função de callback de listener para responder a mudanças no histórico.

• google.script.url fornece os meios para recuperar os parâmetros de URL e o fragmento de URL da página atual, se estiverem presentes.

Essas APIs de histórico estão disponíveis apenas para apps da Web. Eles não são compatíveis com barras laterais, caixas de diálogo ou complementos. Essa funcionalidade também não é recomendada para uso em apps da Web incorporados a um site do Google.