Última modificação: 12 de setembro de 2025
‘Crie sua primeira função sem servidor no HubSpot CMS e obtenha uma resposta.’; As funções sem servidor fornecem uma maneira de executar o JavaScript através da HubSpot no lado do servidor, impedindo que ele seja exposto ao cliente. Isso pode ser especialmente importante para fazer solicitações de API que contêm informações confidenciais, como um Chave de API ou outras credenciais. Quando a função é invocada, a HubSpot executa a função em seu back-end, o que também significa que você não precisa fornecer seus próprios servidores back-end para fazer solicitações para seu site CMS. As funções sem servidor da HubSpot usam o tempo de execução do NodeJS. Neste guia, você criará uma função simples sem servidor que obtém um menção de um serviço de terceiros e exibirá esse menção em um página do site. Para construir e implantar a função sem servidor em sua conta, você usará um projeto de desenvolvedor HubSpot. Para uma visão geral de alto nível das funções sem servidor, consulte a visão geral das funções sem servidor. Você também pode verificar o Canal do YouTube dos desenvolvedores do HubSpot para um passo a passo da utilização de funções sem servidor em um projeto CMS.

​
Pré-requisitos

Antes de iniciar este tutorial, você precisará de:

​
1. Criar um projeto localmente

Comece criando um projeto localmente para que você possa compilá-lo e implantá-lo em sua conta.
  • No terminal, navegue para o diretório onde você armazenará seu projeto usando o comando cd.
cd Documents/Dev/serverless-function-project
  • Execute hs project create para criar um novo projeto.
hs project create
  • Siga os prompts de terminal para criar seu projeto. Para o modelo, selecione Criar um projeto vazio (sem modelo).
Opção de prompt de terminal para a criação de um projeto vazio sem modelo
  • Navegue até o novo diretório do projeto usando o comando cd. Por exemplo, se você nomeou seu projeto meu novo projeto:
cd my-new-project

​
2. Adicione uma função sem servidor ao projeto

Depois que o projeto tiver sido criado, abra-o no editor de sua preferência, como Código VS. A HubSpot terá criado automaticamente um diretório de projeto com um diretório vazio src e um arquivo de configuração hsproject.json. Para adicionar uma função sem servidor ao projeto, crie um diretório app dentro do diretório src e adicione os seguintes diretórios e arquivos dentro dele:
  • app/app.json: o arquivo de configuração do aplicativo.
  • app/app.functions: o diretório da função sem servidor. Você pode usar qualquer nome desejado, desde que termine em .functions.
  • app/app.functions/function.js: o código JavaScript que será executado quando a função for chamada.
  • app/app.functions/serverless.json: o arquivo de configuração da função sem servidor.
  • app/app.functions/package.json: inclui as dependências necessárias.
Estrutura do projeto após adicionar os arquivos e pastas acima ao diretório do projeto
  • Copie o código de exemplo abaixo para o seus respectivos arquivos locais app.json, function.js, serverless.json e package.json. Em cada bloco de código .json, você também encontrará uma tabela contendo definições de campo.
{
  "name": "Serverless function app",
  "description": "This app runs a serverless function to fetch a quote using the Zen Quotes API.",
  "scopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
  "uid": "serverless-function-app",
  "public": false
}
CampoTipoDescrição
nameStringO nome do aplicativo, que será exibido na interface do usuário da HubSpot.
descriptionStringA descrição do aplicativo, que será exibida na interface do usuário da HubSpot.
scopesMatrizOs escopos aos quais o aplicativo tem acesso para solicitações de autenticação com o token de acesso do aplicativo privado. Os dois escopos acima são os escopos mínimos necessários. Nenhum escopo adicional foi adicionado a este tutorial, pois você não precisará usar o token de acesso de aplicativo privado para a solicitação que você fará.
uidStringO identificador exclusivo do aplicativo. Isso pode ser qualquer string, mas deve identificar significativamente o aplicativo. A HubSpot identificará o aplicativo por esta ID para que você possa alterar o name do app localmente ou na HubSpot sem remover dados históricos ou de estado, como logs.
publicStringDefinir como false para aplicativos privados.
  • Depois de adicionar o código acima, salve suas alterações.

​
3. Carregar o projeto na HubSpot

Com as alterações salvas, você pode carregar o projeto na HubSpot para compilar e implantar o aplicativo e a função sem servidor.
  • No terminal, execute hs project upload.
hs project upload
  • Confirme se deseja criar o projeto na conta. Você não precisará confirmar novamente isso após a criação inicial. O terminal exibirá o status atual das etapas de compilação e implantação à medida que avançarem.
  • Quando o upload for concluído, execute hs project open para exibir o projeto na HubSpot.
hs project open
Na HubSpot, você pode exibir os detalhes do projeto, criar e implantar logs, logs de funções sem servidor, gerenciar o projeto e o aplicativo e muito mais. Saiba mais sobre como gerenciar projetos na HubSpot.

​
4. Testar a função

Com a função sem servidor implantada, você pode chamá-la acessando seu URL público. As funções sem servidor construídas com projetos de desenvolvedor têm a seguinte estrutura de URL pública: https://<domain>/hs/serverless/<endpoint-path-from-config>.
  • <domain>: você pode usar qualquer domínio conectado à conta. Por exemplo, se website.com e subdomain.brand.com estiverem conectados à conta, você poderá chamar a função usando https://website.com/hs/serverless/<path> ou https://subdomain.brand.com/hs/serverless/<path>.
  • <endpoint-path-from-config>: o valor no campo path em serverless.json.
Com base no código de exemplo fornecido neste tutorial, o URL público para chamar a função será: https://<domain>/hs/serverless/fetch-quote. Para exibir a saída da função, navegue até esse URL no navegador, substituindo o domínio por um dos domínios hospedados na HubSpot. Se você não conectou um domínio personalizado, poderá usar um dos domínios padrão fornecidos pela HubSpot: <hubId>.hs-sites.com (por exemplo, 123456.hs-sites.com). Seu navegador deve exibir os dados retornados pela API Zen Quotes. Navegador exibindo os dados retornados pela API Zen Quotes

​
5. Invocar a função de um página do site

Agora que você criou a função sem servidor e confirmou que ela retorna dados, implemente-a em uma página para ver os dados retornados em um contexto mais realista. Para este tutorial, você criará um modelo de página contendo alguns JavaScript e HTML personalizados para executar a função e exibir os dados de resposta. Primeiro, crie um novo modelo de página:
  • No ambiente local, crie um novo diretório para conter o modelo de página. Para os propósitos deste tutorial, crie este diretório fora do diretório do projeto criado por hs project create.
  • No terminal, navegue até esse diretório usando o comando cd. 
cd Documents/Dev/serverless-page
  • Execute hs create template "serverless-template" para criar um novo modelo chamado serverless-template.
hs create template "serverless-template"
  • Selecione o tipo de modelo da página.
  • Abra o arquivo de modelo de página recém-criado no editor e substitua o código de formatação pelo código abaixo. Certifique-se de substituir <domain> no URL do endpoint da função (fetch('http://<domain>/hs/serverless/fetch-quote')) com um domínio conectado à sua conta HubSpot.
<!--
    templateType: page
    label: Serverless function example template
    isAvailableForNewContent: true
-->
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>{{ content.html_title }}</title>
    <meta name="description" content="{{ content.meta_description }}" />
    {{ standard_header_includes }}
  </head>
  <body>
    {% module "page_template_logo" path="@hubspot/logo" label="Logo" %}
    <!-- Button to fetch quote via serverless function -->
    <div class="serverless-container">
      <h2>Get quote</h2>
      <p class="subtitle">Click the button to fetch and display a quote.</p>
      <button id="data-button" type="button">Get quote!</button>
      <div id="data-container">
        <p class="data"></p>
      </div>
    </div>
    <!-- End button section -->

    {{ standard_footer_includes }}

    <!-- JavaScript that invokes the serverless function
     and adds returned data into the "data" text element -->
    <script>
      const dataButton = document.getElementById('data-button');
      const dataContainer = document.getElementById('data-container');

      dataButton.addEventListener('click', function (e) {
        console.log('Button clicked!');

        // Show loading state
        dataContainer.innerText = 'Loading...';
        // Replace <domain> with your own domain
        fetch('http://<domain>/hs/serverless/fetch-quote')
          .then((response) => {
            if (!response.ok) {
              throw new Error(`HTTP error! Status: ${response.status}`);
            }
            // Parse the JSON response
            return response.json();
          })

          .then((data) => {
            console.log('Raw data received:', data);

            // Clear container
            dataContainer.innerText = '';

            // Create the paragraph element
            const newDataElement = document.createElement('p');
            newDataElement.innerText = `"${data.q}" — ${data.a}`;
            dataContainer.appendChild(newDataElement);
          });
      });
    </script>
  </body>
</html>
  • Salve o arquivo e execute hs upload para carregá-lo na HubSpot. Siga os prompts de terminal para selecionar o caminho local de origem e destino. Para este tutorial, você pode apenas pressionar Inserir para cada prompt para usar os caminhos padrão.
Em seguida, crie uma nova página a partir do modelo na HubSpot.
  • Navegue até o página do site da sua conta HubSpot executando o hs open website-pages.
hs open website-pages
  • No navegador, clique em Criar no canto superior direito para criar uma nova página.
  • Na caixa de diálogo, selecione um domínio para usar, depois atribua um Nome da página. O domínio da página precisará corresponder ao domínio que você está usando para chamar a função sem servidor para evitar erros de origem cruzada (CORS). Você pode selecionar esse domínio no menu suspenso ou atualizar o URL do endpointno código de modelo de página (fetch('http://<domain>/hs/serverless/fetch-quote')) para usar o domínio selecionado nesta etapa.
  • Clique em Criar página.
  • Na tela de seleção de modelo, procure o novo modelo. Você pode usar o rótulo ou o nome do arquivo para pesquisar o modelo (por exemplo, “Página de exemplo da função sem servidor”). O modelo aparecerá em Outros modelos, pois não faz parte de um tema.
Outra seção de modelos mostrando o modelo de página recém-criado
  • Clique em Selecionar modelo.
  • No editor de página, clique em Visualizar na parte superior direita.
Botão de visualização do editor de página
  • Clique em Abrir em uma nova guia.
Na nova guia, você agora deve ser capaz de clicar no botão para buscar e exibir cotações. Demonstração do botão de exemplo que obtém e exibe cotações da API Zen Quotes

​
Próximas etapas

Agora que você criou e implementou uma função sem servidor que interage com uma API de terceiros, há algumas maneiras de continuar aumentando o uso da função sem servidor, como:
  • Incluir autenticação em uma solicitação para fazer chamadas para APIs HubSpot ou outras APIs autenticadas de terceiros.
  • Implementar o botão e o código JavaScript em um módulo em vez de inseri-los no modelo de página. Isso lhe daria uma opção mais portátil, permitindo que a função fosse chamada de qualquer página à qual o módulo fosse adicionado. Para fazer isso, crie um módulo e adicione o HTML ao module.html e o JavaScript no arquivo module.js.
<div class="serverless-container">
  <h2>Get quote</h2>
  <p class="subtitle">Click the button to fetch and display a quote.</p>
  <button id="data-button" type="button">Get quote!</button>
  <div id="data-container">
    <p class="data"></p>
  </div>
</div>