Produtos suportados
Requer um dos seguintes produtos ou superior.
Content HubEnterprise
Última modificação: 8 de outubro de 2025
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"]
}
}
}
chave | Type | Description |
---|
runtime | String | O 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. |
version | String | Versão do esquema de função sem servidor do HubSpot. (Versão atual 1.0) |
environment | Objeto | Variá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. |
secrets | Matriz | Uma 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. |
endpoints | Objeto | Os 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.
chave | Type | Description |
---|
method | String ou array de strings | Método HTTP ou métodos compatíveis com o endpoint. Assume o padrão GET. |
file | String | Caminho 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:
Parameter | Description |
---|
domainName | O 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/path | O nome ou caminho do ponto de extremidade especificado no arquivo serverless.json . |
hubId | Seu 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.
Parameter | Description |
---|
accountId | O ID da conta da HubSpot que contém a função. |
body | Preenchido se a solicitação for enviada como POST com um tipo de conteúdo de application/json . |
contact | Se 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.
|
headers | Contém cabeçalhos enviados do cliente que acessa seu endpoint. |
params | Preenchido 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 |
limits | Retorna 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çalho | Description |
---|
accept | Indica os tipos de conteúdo expressos como tipos MIME que o cliente entende. Consulte a MDN. |
accept-encoding | Indica o conteúdo de codificação que o cliente entende. Consulte a MDN. |
accept-language | Indica qual idioma e localização são preferidos pelo usuário. Consulte a MDN. |
cache-control | Mantém diretivas para armazenamento em cache. Consulte a MDN. |
connection | Indica se a conexão de rede permanece aberta. Consulte a MDN. |
cookie | Contém os cookies enviados pelo cliente. Consulte a MDN. |
host | Indica o nome do domínio e o número da porta TCP de um servidor em modo de escuta. Consulte a MDN. |
true-client-ip | O endereço IP do usuário final. Consulte Cloudflare true-client-ip. |
upgrade-insecure-requests | Indica a preferência dos clientes por uma resposta criptografada e autenticada. Consulte a MDN. |
user-agent | String definida pelo fornecedor que identifica o aplicativo, o sistema operacional, o fornecedor do aplicativo e a versão. Consulte a MDN. |
x-forwarded-for | Identifica 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 secrets
contendo 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.
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:
- Clone ou copie seu arquivo de função.
- 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.