Aplicativos da Web

Se você criar uma interface do usuário para um script, poderá publicá-lo como um app da Web. Por exemplo, um script que permite aos usuários agendar horários com membros de uma equipe de suporte é melhor apresentado como um app da Web para que os usuários possam acessá-lo diretamente no navegador.

Tanto os scripts independentes quanto os scripts vinculados aos 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 app da Web se atender a estes requisitos:

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

Parâmetros de solicitação

Quando um usuário visita um app ou um programa envia uma solicitação HTTP GET, o Apps Script executa a função doGet(e). Quando um programa envia uma solicitação HTTP POST ao app, 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 de solicitação. Somente 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 depois de /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 tamanho 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 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 exibir os parâmetros da seguinte maneira:

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 podem ser usados em parâmetros de URL ou em corpos POST:

• c
• sid

O uso desses parâmetros pode resultar em uma resposta HTTP 405 com a mensagem de erro "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 Ativar tipos de implantação > App da Web.
3. Insira as informações sobre seu app da Web nos campos em "Configuração da implantação".
4. Clique em Implantar.

Você pode compartilhar o URL do app da Web com as pessoas que gostaria de usar seu aplicativo, desde que tenha concedido acesso a elas.

Observação :os apps da Web implantados em um domínio vão deixar de funcionar se a propriedade for alterada para um drive compartilhado ou conta em outro domínio. Para corrigir isso, peça para o novo proprietário ou colaborador implantar novamente o app da Web no novo domínio. Como alternativa, se o app da Web for movido de volta para o domínio original, ele vai começar a funcionar novamente nesse domínio sem ser reimplantado.

Testar uma implantação de app da Web

Para testar o 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 Ativar tipos de implantação > App da Web.
3. Abaixo do URL do app da Web, clique em Copiar.

4. Cole o URL no navegador e teste seu app da Web.

   Esse 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 é destinada apenas para testes durante o desenvolvimento.

Aviso :ao implantar apps da Web para serem executados como desenvolvedor, tenha muito cuidado ao processar os tokens OAuth recebidos por meio de ScriptApp.getOAuthToken(). Esses tokens podem conceder acesso aos seus dados a outros aplicativos, nunca transmiti-los ao cliente.

Permissões

As permissões para um app da Web variam dependendo de como você executa o app:

• Executar o app como eu: nesse caso, o script sempre é executado como você, o proprietário do script, independentemente de quem acessa o app da Web.
• Executar o app como o usuário acessa o app da Web: nesse caso, o script é executado com a 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 autorizar o acesso.

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

Observação: é possível colaborar em apps da Web usando um drive compartilhado. Quando um app da Web em um compartilhado é implantado, a opção "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 ao Google Sites

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

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

Siga estas etapas para incorporar um app da Web a uma página Sites:

1. Abra a página "Sites" à qual você quer adicionar o app da Web.
2. Selecione Inserir > Incorporar URL.
3. Cole o URL do app da Web e clique em ADICIONAR.

O app da Web é exibido em um frame na visualização da página. Quando você publica a página, talvez os visualizadores do seu site precisem autorizar o app da Web antes que ele seja executado normalmente. Apps da Web não autorizados apresentam solicitações de autorização ao usuário.

Histórico de apps da Web e do navegador

É recomendável que um app da Web do Apps Script simule um aplicativo de várias páginas ou que tenha uma IU dinâmica controlada por parâmetros de URL. Para fazer isso bem, você pode definir um objeto de estado para representar a IU ou a página do app e enviar o estado para o histórico de navegação à medida que o usuário navega pelo app. Também é possível detectar eventos do histórico para que o app da Web exiba a IU 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 tempo de carregamento, o app cria dinamicamente a IU com base nesses parâmetros, permitindo que o usuário inicie o app em um estado específico.

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

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

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

Essas APIs de histórico estão disponíveis apenas para apps da Web. Elas 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 em um Google Sites.