Produtos suportados
Requer um dos seguintes produtos ou superior.
Content HubContent HubEnterprise
Última modificação: 28 de agosto de 2025

Observação:

Se estiver criando uma função sem servidor como parte de um projeto de desenvolvedor, visite a documentação para desenvolvedores sobre a função sem servidor em projetos. A documentação abaixo é destinada a criação de funções sem servidor fora da plataforma do projeto do desenvolvedor.
Neste artigo, saiba sobre os arquivos encontrados dentro de uma pasta .functions sem servidor e os comandos da CLI que você pode usar com funções sem servidor. Para uma visão geral de alto nível das funções sem servidor, consulte a visão geral das funções sem servidor. Para obter mais informações sobre como criar funções sem servidor com projetos para módulos renderizados e parciais em JavaScript, consulte a documentação para desenvolvedores sobre projetos.

Serverless.json

Na pasta .functions, o arquivo serverless.json armazena a configuração da função sem servidor. Este é um arquivo obrigatório e mapeia as funções aosendpoints.
// serverless.json
{
  "runtime": "nodejs18.x",
  "version": "1.0",
  "environment": {
    "globalConfigKey": "some-value"
  },
  "secrets": ["secretName"],
  "endpoints": {
    "events": {
      "file": "function1.js",
      "method": "GET"
    },
    "events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "CONFIG_KEY": "some-other-value"
      },
      "secrets": ["googleKeyName", "otherkeyname"]
    }
  }
}
chaveTypeDescription
runtimeStringO ambiente de tempo de execução. Suporta as seguintes versões do Node.js:
  • Node 20 (nodejs20.x) (recomendado)
  • Node 18 (nodejs18.x)
Observe que a HubSpot deixará de oferecer suporte ao Node 16 a partir de 12 de julho de 2024.
versionStringVersão do esquema de função sem servidor do HubSpot. (Versão atual 1.0)
environmentObjetoVariáveis de configuração passadas para a função em execução como variáveis de ambiente no tempo de execução. Você pode usar isso para adicionar uma lógica que permita usar uma versão de teste de uma API em vez da versão real, com base em uma variável de ambiente.
secretsMatrizUma matriz que contém os nomes dos segredos que sua função sem servidor usará para autenticação. Não armazene segredos diretamente neste arquivo, apenas faça referência aos nomes.
endpointsObjetoOs endpoints definem os caminhos que são expostos e seu mapeamento a arquivos JavaScript específicos, dentro da pasta de funções. Saiba mais sobre os endpoints abaixo.

Observação:

Não atribua os mesmos nomes aos seus segredos e variáveis de ambiente. Se você fizer isso, poderá haver conflitos ao retornar os valores na função.

Endpoints

Cada endpoint pode ter suas próprias variáveis de ambiente e segredos. As variáveis especificadas fora dos endpoints devem ser usadas para definições de configuração que se aplicam a todas as funções e endpoints.
"events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "configKey": "some-other-value"
      },
      "secrets": ["googleAPIKeyName","otherKeyName"]
    }
Os endpoints têm algumas chaves exclusivas.
chaveTypeDescription
methodString ou array de stringsMétodo HTTP ou métodos compatíveis com o endpoint. Assume o padrão GET.
fileStringCaminho para o arquivo de função JavaScript com a implementação do endpoint.
As funções sem servidor são expostas por meio de um caminho no domínio da sua conta do HubSpot CMS. Inclui os subdomínios padrão .hs-sites.com. Você pode acessar essas funções no seguinte URL: https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}. Abaixo, saiba mais sobre cada componente do URL:
ParameterDescription
domainNameO nome do seu domínio.
/_hcms/api/O caminho reservado para funções sem servidor. Todos os pontos de extremidade existem dentro deste caminho.
endpoint-name/pathO nome ou caminho do ponto de extremidade especificado no arquivo serverless.json.
hubIdSeu Hub ID. Fornecer essa informação na solicitação permitirá testar as funções nas visualizações de módulos e modelos.

Arquivo de funções

Além do arquivo de configuraçãoserverless.json, a pasta .functions também conterá um arquivo JavaScript Node.js que define a função. Você também pode aproveitar a biblioteca de solicitações para fazer solicitações HTTP para APIs da HubSpot, entre outras. Por exemplo:
// Require axios library, to make API requests.
const axios = require('axios');
// Environment variables from your serverless.json
// process.env.globalConfigKey

exports.main = (context, sendResponse) => {
  // your code called when the function is executed

  // context.params
  // context.body
  // context.accountId
  // context.limits

  // secrets created using the CLI are available in the environment variables.
  // process.env.secretName

  //sendResponse is what you will send back to services hitting your serverless function.
  sendResponse({ body: { message: 'my response' }, statusCode: 200 });
};

Objeto de contexto

O objeto de contexto contém informações contextuais sobre a execução da função, armazenadas nos parâmetros a seguir.
ParameterDescription
accountIdO ID da conta da HubSpot que contém a função.
bodyPreenchido se a solicitação for enviada como POST com um tipo de conteúdo de application/json.
contactSe a solicitação for de um contato com cookie, o objeto de contato será preenchido com um conjunto de propriedades básicas, juntamento com as seguintes informações:
  • vid: o ID de visitante do contato.
  • isLoggedIn: ao usar associações do CMS, isso será true se o contato estiver logado no domínio.
  • listMemberships: uma matriz de IDs de listas de contatos das quais este contato é membro.
headersContém cabeçalhos enviados do cliente que acessa seu endpoint.
paramsPreenchido com valores de string de consulta, juntamente com quaisquer valores de formulário HTML via POST. São estruturados como um mapa, tendo strings como chaves e uma matriz de strings para cada valor.context.params.yourvalue
limitsRetorna o quão perto você está de atingir os limites de funções sem servidor.
  • executionsRemaining: o número restante de execuções por minuto.
  • timeRemaining: o número restante de tempo de execução permitido.

Cabeçalhos

Se precisar saber os cabeçalhos do cliente que está atingindo o seu endpoint, você pode acessá-los por meio de context.headers, semelhante à forma como acessa as informações por meio de context.body. Reveja alguns dos cabeçalhos comuns fornecidos pelo HubSpot. Para obter uma lista completa, consulte a documentação de cabeçalhos HTTP da MDN.
CabeçalhoDescription
acceptIndica os tipos de conteúdo expressos como tipos MIME que o cliente entende. Consulte a MDN.
accept-encodingIndica o conteúdo de codificação que o cliente entende. Consulte a MDN.
accept-languageIndica qual idioma e localização são preferidos pelo usuário. Consulte a MDN.
cache-controlMantém diretivas para armazenamento em cache. Consulte a MDN.
connectionIndica se a conexão de rede permanece aberta. Consulte a MDN.
cookieContém os cookies enviados pelo cliente. Consulte a MDN.
hostIndica o nome do domínio e o número da porta TCP de um servidor em modo de escuta. Consulte a MDN.
true-client-ipO endereço IP do usuário final. Consulte Cloudflare true-client-ip.
upgrade-insecure-requestsIndica a preferência dos clientes por uma resposta criptografada e autenticada. Consulte a MDN.
user-agentString definida pelo fornecedor que identifica o aplicativo, o sistema operacional, o fornecedor do aplicativo e a versão. Consulte a MDN.
x-forwarded-forIdentifica o endereço IP de origem de um cliente por meio de um proxy ou balanceador de carga. Consulte a MDN.

Redirecionar enviando um cabeçalho

Você pode realizar um redirecionamento a partir de sua função sem servidor enviando uma resposta com um cabeçalho de localização e o statusCode 301.
sendResponse({
  statusCode: 301,
  headers: {
    Location: 'https://www.example.com',
  },
});

Definir cookies a partir do seu endpoint

Na sua função sem servidor, você pode instruir o cliente (navegador da web) a definir um cookie.
exports.main = (context, sendResponse) => {
    sendResponse({
      body: { ... },
      'Set-Cookie': 'myCookie1=12345; expires=...; Max-Age=...',
      statusCode: 200
    });
  }

Definir vários valores para um único cabeçalho

Para cabeçalhos compatíveis com vários valores, você pode usar multiValueHeaders para passar os valores. Por exemplo: você pode instruir o navegador a definir vários cookies.
exports.main = (context, sendResponse) => {
  sendResponse({
    body: { ... },
    multiValueHeaders: {
      'Set-Cookie': [
        'myCookie1=12345; expires=...; Max-Age=...',
        'myCookie2=56789; expires=...; Max-Age=...'
       ]
    },
    statusCode: 200
  });
}

Segredos

Se precisar autenticar uma solicitação de função sem servidor, você usará segredos para armazenar valores como chaves de API ou tokens de acesso a aplicativos privados. Usando a CLI, você pode adicionar segredos à sua conta da HubSpot para armazenar esses valores, os quais poderá acessar posteriormente por meio de variáveis de ambiente (process.env.secretName). Os segredos são gerenciados por meio da CLI da HubSpot usando os seguintes comandos: Uma vez adicionados por meio da CLI, os segredos podem ser disponibilizados para as funções ao incluir uma matriz secretscontendo o nome do segredo. Isso permite armazenar seu código de função no controle de versão e usar segredos sem expô-los. No entanto, você nunca deve retornar o valor do seu segredo por meio do registro do console ou como uma resposta, pois isso irá expor o segredo nos registos ou nas páginas de front-end que chamam a função sem servidor.

Observação:

Devido ao armazenamento em cache, pode levar cerca de um minuto para ver os valores secretos atualizados. Se você acabou de atualizar um segredo, mas ainda está vendo o valor antigo, verifique novamente após cerca de um minuto.

Usando funções sem servidor com o elemento de formulário

Ao enviar funções sem servidor, use javascript para lidar com o envio de formulário e inclua o cabeçalho "contentType" : "application/json" em sua solicitação. Não use o atributo action em elementos <form>.

CORS

Cross Origin Resource Sharing (CORS) é um recurso de segurança do navegador. Por padrão, os navegadores restringem solicitações de origem cruzada iniciadas por JavaScript. Isso evita que códigos maliciosos em execução em um domínio diferente afetem seu site. Esse processo é chamado de política de mesma origem. Como o envio e a recuperação de dados de outros servidores às vezes são uma necessidade, o servidor externo pode fornecer cabeçalhos HTTP que indiquem quais origens têm permissão para ler as informações a partir de um navegador. Você não deve ter problemas de CORS ao chamar sua função sem servidor nas páginas hospedadas pela HubSpot. Se fizer isso, verifique se está usando o protocolo correto.
Está obtendo esse erro CORS?“O acesso à busca em [URL da sua função] a partir da origem [página que fez a solicitação] foi bloqueado pela política de CORS: a resposta à solicitação de preflight não passou na verificação de controle de acesso: o cabeçalho ‘Access-Control-Allow-Origin’ não está presente no recurso solicitado. Se uma resposta opaca atender às suas necessidades, defina o modo da solicitação para ‘no-cors’ para buscar o recurso com o CORS desativado.”Sua solicitação tem uma origem diferente da do site que a chama?
  • Se o nome de domínio for diferente, sim.
  • Se estiver usando um protocolo diferente (http, https), sim.
Se estiver usando um protocolo diferente, basta alterar o protocolo para que ele corresponda e isso resolverá o problema.Não é possível modificar o cabeçalho Access-Control-Allow-Origin do HubSpot no momento.Consulte a MDN para obter mais informações detalhadas sobre a solução de problemas de erros CORS.

Solicitações GET

As solicitações GET podem ser capazes de fazer solicitações CORS dependendo do cliente. Não faça com que as solicitações GET escrevam algo, apenas retornem dados.

Pacotes predefinidos

Atualmente, as funções sem servidor da HubSpot vêm predefinidas com os seguintes pacotes: Para usar a versão compatível mais recente de um pacote predefinido ou para usar um pacote recém-adicionado:
  1. Clone ou copie seu arquivo de função.
  2. Altere o endpoint da sua função no arquivo serverless.json para direcionar para o seu novo arquivo de função. Você pode excluir com segurança a versão antiga.
Se quiser incluir pacotes que não fazem parte do conjunto de pacotes predefinidos, você pode usar o webpack para combinar seus módulos Node e fazer com que seus arquivos empacotados sejam seus arquivos de função.

Limites

As funções sem servidor destinam-se a ser rápidas e a ter foco restrito. Para permitir chamadas e respostas rápidas, as funções sem servidor da HubSpot estão limitadas a:
  • 50 segredos por conta.
  • 128 MB de memória.
  • Não mais do que 100 endpoints por conta da HubSpot.
  • Você deve usar contentType application/json ao chamar uma função.
  • Os registros de funções sem servidor são armazenados por 90 dias.
  • 6 MB em uma carga útil de invocação do AWS Lambda
Limites de execução
  • Cada função tem no máximo 10 segundos de tempo de execução
  • Cada conta é limitada a um total de 600 segundos de execução por minuto.
Isso significa que qualquer um destes cenários pode acontecer:
  • 60 execuções de funções que levam 10 segundos para serem concluídas.
  • 6.000 execuções de funções que levam 100 milissegundos para serem concluídas.
As funções que excedem esses limites geram um erro. A contagem de execução e os limites de tempo retornarão uma resposta de 429. O tempo de execução de cada função está incluído nos logs das funções sem servidor. Para ajudar a evitar esses limites, os dados de limite são fornecidos automaticamente no contexto da função durante a execução. Você pode usar esses dados para fazer com que o aplicativo permaneça dentro desses limites. Por exemplo, se seu aplicativo exige a consulta periódica de um endpoint, você pode retornar, junto com os dados, uma variável para influenciar a frequência dessa consulta. Dessa forma, quando o tráfego estiver alto, você pode diminuir a taxa de consulta, evitando atingir os limites e, em seguida, aumentá-lo novamente quando o tráfego estiver baixo.