Referencia de funciones sin servidor

Last updated:
APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

En este artículo, aprende sobre los archivos que se encuentran dentro de una carpeta .functions sin servidor y los comandos CLI que puedes utilizar con las funciones sin servidor.

Para obtener un resumen general de las funciones sin servidor, consulta la descripción general de las funciones sin servidor.

Nota: los archivos de las funciones sin servidor deben cargarse localmente utilizando la CLI de HubSpot.

Serverless.json

Tu archivo serverless.json almacena tus ajustes de configuración para las funciones dentro de tu carpeta .functions. Este archivo es necesario para que las funciones sin servidor funcionen. Este archivo asigna tus funciones a tus puntos de terminación.

// serverless.json { "runtime": "nodejs14.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"] } } }
Use this table to describe parameters / fields
ClaveTypeDescription
runtime
obligatorio
String

El entorno de ejecución. Admite la versión 14 de Node.js(nodejs14.x). 

Nota: La versión 12 de Node.js (nodejs12.x) ya no es compatible.

 

version
obligatorio
String

Versión del esquema de funciones sin servidor de HubSpot. (Versión actual 1.0)

endpoints
obligatorio
Object

Los puntos de terminación definen las rutas que se exponen y tu asignación a archivos JavaScript específicos, dentro de tu carpeta de funciones.

environment
Object

Variables de configuración pasadas a la función ejecutante como variables de entorno en tiempo de ejecución. Puedes usar esto para agregar una lógica para usar una versión de prueba de una API en lugar de la real basada en una variable de entorno.

secrets
array

Una clave API es un secreto. Los secretos en el archivo de configuración se refieren al nombre del secreto, no a su valor. No pongas los secretos directamente en este archivo, solo haz referencia a los nombres de los secretos.

Nota: no asignes el mismo nombre a tus secretos y variables de entorno. Si lo haces, se producirán conflictos al devolver tus valores en la función.

Puntos de terminación

Cada punto de terminación puede tener sus propias variables de entorno y secretos. Las variables especificadas fuera de los puntos de terminación deben utilizarse para los ajustes de configuración que se aplican a todas las funciones y puntos de terminación.

"events/update": { "method": "POST", "file": "action2.js", "environment": { "configKey": "some-other-value" }, "secrets": ["googleAPIKeyName","otherKeyName"] }

Los puntos de terminación tienen un par de claves únicas.

Use this table to describe parameters / fields
ClaveTypeDescription
method
String or array of strings

Método o métodos HTTP que admite el punto de terminación. El valor predeterminado es GET.

file
obligatorio
String

Ruta al archivo de la función JavaScript con la implementación para el punto de terminación.

Las funciones sin servidor se exponen a través de una ruta en el dominio de tu cuenta de HubSpot CMS. Esto incluye los subdominios predeterminados .hs-sites.com.

Puedes acceder a estas funciones en la siguiente URL: 

https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}.

A continuación, conoce cada uno de los componentes de la URL:

Use this table to describe parameters / fields
ParameterDescription
domainName

Tu nombre de dominio.

/_hcms/api/

La ruta reservada para las funciones sin servidor. Todos los puntos de terminación existen dentro de esta ruta.

endpoint-name/path

El nombre del punto de terminación o la ruta que especificaste en el archivo serverless.json.

hubId

Tu ID de Hub Proporcionar esto en la solicitud te permitirá probar tus funciones dentro de las vistas previas de módulos y plantillas.

Archivo de funciones

Cada función se crea como un archivo JavaScript Node.js en una carpeta que termina en .functions. Además de la biblioteca estándar de Node.js, las funciones pueden aprovechar la biblioteca de solicitudes para realizar peticiones HTTP a las API de HubSpot y a otras API. 

Un archivo básico serverless-function.js tiene el siguiente aspecto:

// 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}); };

Claves de objeto de contexto

Claves de objeto de contexto
ParameterDescription
accountId

El ID de la cuenta de HubSpot que contiene la función.

body

el cuerpo está lleno si la solicitud se envía como POST con un tipo de contenido application/json

contact

Si la solicitud proviene de un contacto con cookies, el objeto contacto estará presente con un conjunto de propiedades básicas del contacto. Estas propiedades adicionales también estarán disponibles:

  • vid: El identificador de visitante del contacto
  • isLoggedIn: cuando se utiliza CMS Memberships, esto será verdadero si el contacto está registrado en el dominio
  • listMemberships: una matriz de ids de listas de contactos de las que este contacto es miembro
headers

Contiene las cabeceras enviadas por el cliente que llega a tu punto de terminación. Consulta encabezados.

params

params se rellena con los valores de la cadena de consulta más los valores de los formularios HTML-POST. Se estructuran como un mapa con cadenas como claves y una matriz de cadenas para cada valor. context.params.yourvalue

limits

Devuelve lo cerca que estás de alcanzar los límites de velocidad de las funciones sin servidor.

  • executionsRemaining: cuántas ejecuciones por minuto quedan.
  • timeRemaining: cuánto tiempo de ejecución permitido queda.

Encabezados

A veces puede ser útil tener los encabezados del cliente que llega a tu punto de terminación. Proporcionamos los siguientes encabezados a través de context.headers. Esto es similar a cómo se accede a la información a través de context.body.

Use this table to describe parameters / fields
encabezadoDescription
accept

Comunica qué tipos de contenido, expresados como tipos MIME, entiende el cliente. Consulta MDN.

accept-encoding

Comunica la codificación del contenido que el cliente entiende. Consulta MDN.

accept-language

Comunica qué idioma humano y localización se prefiere. Consulta MDN.

cache-control

Contiene directivas para el almacenamiento en caché. Consulta MDN.

connection

Comunica si la conexión de red permanece abierta. Consulta MDN.

cookie

Contiene las cookies enviadas por el cliente. Consulta MDN.

host

Comunica el nombre de dominio y el número de puerto TCP de un servidor de escucha. Consulta MDN.

true-client-ip

Dirección IP del usuario final. Consulta Cloudflare true-client-ip.

upgrade-insecure-requests

Comunica la preferencia del cliente por una respuesta cifrada y autentificada. Consulta MDN.

user-agent

Cadena definida por el proveedor que identifica la aplicación, el sistema operativo, el proveedor de la aplicación y la versión. Consulta MDN.

x-forwarded-for

Identifica la dirección IP de origen de un cliente a través de un proxy o equilibrador de carga. Consulta MDN.

Redirigir enviando una encabezado

Puedes realizar una redirección desde tu función sin servidor enviando una respuesta con un encabezado location y un statusCode 301.

sendResponse({ statusCode: 301, headers: { "Location": "https://www.example.com" } });

Establecer las cookies desde tu punto de terminación

Desde tu función sin servidor puedes decirle al cliente (navegador web) que establezca una cookie.

exports.main = (context, sendResponse) => { sendResponse({ body: { ... }, 'Set-Cookie': 'myCookie1=12345; expires=...; Max-Age=...', statusCode: 200 }); }

Establecer varios valores para un solo encabezado

En el caso de los encabezados que admiten múltiples valores, puedes utilizar multiValueHeaders, para pasar los valores. Por ejemplo: puedes decirle al navegador que establezca varias cookies.

exports.main = (context, sendResponse) => { sendResponse({ body: { ... }, multiValueHeaders: { 'Set-Cookie': [ 'myCookie1=12345; expires=...; Max-Age=...', 'myCookie2=56789; expires=...; Max-Age=...' ] }, statusCode: 200 }); }

Secretos

Las claves de la API y la información de autenticación se denominan secretos. Una vez agregados son accesibles a través de variables de entorno (process.env.secretName). Puedes asignar secretos disponibles para el uso de puntos de terminación específicos agregando la clave "secrets" a tu archivo serverless.json. Los secretos se gestionan a través de la CLI de HubSpot utilizando los siguientes comandos:

No devuelvas el valor de tu secreto a través del registro de la consola o como respuesta. Hacerlo expondría tus secretos en tus registros o en las páginas del front-end que llaman a tu función sin servidor.

Uso de funciones sin servidor con el elemento de formulario

Al enviar funciones sin servidor, utiliza javascript para manejar el envío del formulario y utiliza el encabezado "contentType" : "application/json" en tu solicitud. No utilices el atributo action de los elementos <form>.

CORS

Intercambio de recursos de origen cruzado (CORS) es una función de seguridad del navegador. Por opción predeterminada, los navegadores restringen las solicitudes de origen cruzado iniciadas por javascript. Esto evita que el código malicioso que se ejecuta en un dominio diferente, afecte a tu sitio. Esto se denomina política del mismo origen. Dado que el envío y la recuperación de datos de otros servidores es a veces una necesidad, el servidor externo, puede suministrar encabezados HTTP que comunican qué orígenes están autorizados a leer la información de un navegador.

No deberías tener problemas de CORS al llamar a tu función sin servidor dentro de tus páginas alojadas en HubSpot. Si lo haces, verifica que estás utilizando el protocolo correcto.

¿Recibes este error CORS?
"El acceso a la obtención en [tu url de función] desde el origen [página que realiza la solicitud] ha sido bloqueado por la política CORS: La respuesta a la solicitud de verificación previa no pasa la comprobación de control de acceso: El recurso solicitado no contiene el encabezado "Access-Control-Allow-Origin". Si una respuesta opaca sirve a tus necesidades, establece el modo de la solicitud como 'no-cors' para obtener el recurso con CORS desactivado"

¿Tu solicitud se dirige a un origen diferente al del sitio que la llama?

  • Si el nombre de dominio es diferente, sí.
  • Si utilizas un protocolo diferente (http, https), sí.

Si utilizas un protocolo diferente, simplemente cambia el protocolo para que coincida y eso lo arreglará. 

En este momento no se puede modificar el encabezado Access-Control-Allow-Origin de HubSpot.

Consulta el MDN para obtener más detalles sobre la solución de errores de CORS.

Solicitudes Get

Las solicitudes Get pueden hacer solicitudes CORS dependiendo del cliente. No hagas que las peticiones GET escriban nada, solo que devuelvan datos.

Paquetes precargados

Las funciones sin servidor de HubSpot vienen actualmente precargadas con los siguientes paquetes:

Para utilizar la última versión compatible de un paquete precargado, o para utilizar un paquete recién agregado:

  1. Clona o copia tu archivo de funciones.
  2. Cambia el punto de terminación de tu función en el archivo serverless.json para que apunte a tu nuevo archivo de función. Puedes eliminar la versión antigua con seguridad.

Si quieres incluir paquetes fuera del conjunto de paquetes precargados, puedes usar webpack para combinar tus módulos de node y hacer que tus archivos agrupados sean tus archivos de función.

Límites

Las funciones sin servidor están previstas para ser rápidas y tener un enfoque limitado. Para permitir llamadas y respuestas rápidas, las funciones sin servidor de HubSpot se limitan a:

  • 50 secretos por cuenta.
  • 128 MB de memoria.
  • No más de 100 puntos de terminación por cuenta de HubSpot.
  • Debes usar contentType application/json cuando se llama a una función.
  • los registros de las funciones sin servidor se almacenan durante 90 días.
  • 6MB en una carga útil de invocación de AWS Lambda.

Límites de ejecución

  • Cada función tiene un tiempo máximo de ejecución de 10 segundos
  • Cada cuenta está limitada a un total de 600 segundos de ejecución por minuto.

Esto significa que cualquiera de estos escenarios puede ocurrir:

  • 60 ejecuciones de funciones que tardan 10 segundos cada una en completarse.
  • 6000 ejecuciones de funciones que tardan 100 milisegundos en completarse.

Las funciones que superen esos límites arrojarán un error. El recuento de ejecuciones y los límites de tiempo devolverán una respuesta 429. El tiempo de ejecución de cada función se incluye en los registros de funciones sin servidor.

Para ayudar a evitar estos límites, los datos de los límites se proporcionan automáticamente al contexto de la función durante la ejecución. Puedes utilizarlo para influir en tu solicitud para mantenerse dentro de esos límites. Por ejemplo, si tu aplicación requiere sondear tu punto de terminación, entonces puedes devolver con tus datos una variable para influir en la frecuencia del sondeo. De este modo, cuando el tráfico es elevado, se puede reducir el ritmo de sondeo para evitar que se alcancen los límites, y luego volver a aumentarlo cuando el tráfico sea escaso.


¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.