Aplicativos da Web

Publique o script como um app da Web se você criar uma interface do usuário para ele. Por exemplo, um script que permite aos usuários agendar compromissos com membros de uma equipe de suporte é melhor apresentado como um app da Web para que os usuários acessem diretamente pelo navegador.

Scripts independentes e scripts vinculados a aplicativos do Google Workspace podem ser transformados em apps da Web, desde que atendam aos requisitos a seguir.

Requisitos para apps da Web

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

Parâmetros de solicitação

Quando um usuário acessa um app ou um programa envia uma solicitação HTTP GET ao app, o Google Apps Script executa a função doGet. Quando um programa envia uma solicitação HTTP POST ao app, o Apps Script executa doPost. Nos dois 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 a seguir:

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 que têm 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 POST

text/csv
e.postData.contents

O texto de conteúdo do corpo POST

Alice,21
e.postData.name

Sempre o valor "postData"

postData

Transmita parâmetros como username e age para um URL como este:

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

Mostre os parâmetros desta forma:

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

No exemplo anterior, doGet retorna a seguinte saída:

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

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 Ativar configurações de tipos de implantação > App da Web.
  3. Insira as informações sobre o app da Web nos campos em "Configuração de implantação".
  4. Clique em Implantar.

Compartilhe o URL do aplicativo da Web com as pessoas que você quer que usem o app, desde que você tenha concedido acesso a elas.

Os apps da Web implantados em um domínio deixam de funcionar se a propriedade for alterada para um drive compartilhado ou uma conta em um domínio diferente. Isso pode ser corrigido se o novo proprietário ou colaborador reimplantar 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 começará a funcionar novamente para esse domínio sem precisar 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. No URL do aplicativo da Web, clique em Copiar.

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

    Esse URL termina em /dev e só pode ser acessado por usuários que têm acesso de edição ao script. Essa instância do app sempre executa o código salvo mais recentemente e só é destinada a testes durante o desenvolvimento.

Para testar o recurso granular do OAuth no app da Web, verifique se o projeto já tem algumas autorizações. Para invalidar as autorizações atuais, use ScriptApp.invalidateAuth. Para apps da Web que já estão implantados e em execução na identidade do usuário ativo, modifique o campo executeAs JSON no manifesto para USER_DEPLOYING.

Ao implantar apps da Web para serem executados como o desenvolvedor, tenha muito cuidado ao processar tokens OAuth obtidos pelo 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 app da Web variam dependendo de como você escolhe executar o 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.

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

Colabore em apps da Web usando o 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á proprietário do script).

Incorporar o app da Web no Google Sites {:#embed-web-app}

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 não estiver 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 Sites, ele precisa ser implantado primeiro. Você também precisa do URL implantado na caixa de diálogo Implantar.

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

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

O app da Web aparece em um frame na visualização da página. Ao publicar a página, os visitantes do site talvez precisem autorizar o app da Web 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

Para simular um aplicativo de várias páginas ou um com uma interface dinâmica controlada usando parâmetros de URL, defina um objeto de estado para representar a interface ou a página do app e envie o estado para o histórico do navegador à medida que o usuário navega pelo app. Ouça eventos de histórico para que o app da Web 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 tempo de carregamento, faça com que o 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 a criar apps da Web vinculados ao histórico do navegador:

  • google.script.history oferece métodos para permitir a resposta dinâmica a mudanças no histórico do navegador. Isso inclui: envio de estados (objetos simples definidos) 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 do listener para responder a mudanças no histórico.

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

Essas APIs de histórico só estão disponíveis 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 Sites.