Référence relative aux fonctions sans serveur

Last updated:
APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

Dans cet article, découvrez les fichiers contenus dans un dossier .functions sans serveur ainsi que les commandes d'ILC que vous pouvez utiliser avec les fonctions sans serveur.

Pour un aperçu de haut niveau des fonctions sans serveur, consultez la présentation des fonctions sans serveur.

Remarque : Les fichiers de fonctions sans serveur doivent être téléchargés localement à l'aide de l'ICL HubSpot.

Serverless.json

Votre fichier serverless.json stocke vos paramètres de configuration pour les fonctions à l'intérieur de votre dossier .functions. Ce fichier est nécessaire pour que les fonctions sans serveur fonctionnent. Ce fichier associe vos fonctions à leurs points de terminaison.

// 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
cléTypeDescription
runtime
obligatoire
String

L'environnement d'exécution. Prend en charge la version 14 de Node.js (nodejs14.x). 

Remarque : La version 12 de Node.js (nodejs12.x) n'est plus prise en charge.

 

version
obligatoire
String

Version du schéma de la fonction sans serveur HubSpot. (Version actuelle 1.0)

endpoints
obligatoire
Object

Les points de terminaison définissent les chemins qui sont exposés et leur correspondance avec des fichiers JavaScript spécifiques dans votre dossier de fonctions.

environment
Object

Variables de configuration transmises à la fonction d'exécution en tant que variables d'environnement au moment de l'exécution. Vous pouvez utiliser cela pour ajouter une logique permettant d'utiliser une version de test d'une API au lieu de la véritable API, en fonction d'une variable d'environnement.

secrets
array

Une clé d'API est un secret. Les secrets dans le fichier de configuration font référence au nom du secret et non à sa valeur. Ne placez pas les secrets directement dans ce fichier. Indiquez seulement leurs noms.

Remarque : N'attribuez pas le même nom à vos secrets et à vos variables d'environnement. Cela entraînera des conflits lors du renvoi de leurs valeurs dans la fonction.

Points de terminaison

Chaque point de terminaison peut avoir ses propres variables d'environnement et secrets. Les variables spécifiées en dehors des points de terminaison doivent être utilisées pour les paramètres de configuration qui s'appliquent à toutes les fonctions et à tous les points de terminaison.

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

Les points de terminaison ont deux clés uniques.

Use this table to describe parameters / fields
cléTypeDescription
method
String or array of strings

La ou les méthodes HTTP que le point de terminaison prend en charge. La valeur par défaut est GET.

file
obligatoire
String

Chemin d'accès au fichier de fonction JavaScript avec l'implémentation pour le point de terminaison.

Les fonctions sans serveur sont exposées via un chemin d'accès au domaine de votre compte CMS Hub. Cela inclut les sous-domaines .hs-sites.com par défaut.

Vous pouvez accéder à ces fonctions à l'URL suivante : 

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

Ci-dessous, découvrez chaque composant de l'URL :

Use this table to describe parameters / fields
ParameterDescription
domainName

Le nom de votre domaine.

/_hcms/api/

Le chemin d'accès réservé aux fonctions sans serveur. Tous les points de terminaison se trouvent à l'intérieur de ce chemin.

endpoint-name/path

Le nom ou le chemin d'accès du point de terminaison que vous avez spécifié dans le fichier serverless.json.

hubId

Votre HubID. En fournissant ces informations dans la demande, vous pourrez tester vos fonctions dans les aperçus de modules et de modèles.

Fichier de fonction

Chaque fonction est créée en tant que fichier JavaScript Node.js dans un dossier se terminant par .functions. En plus de la bibliothèque standard Node.js, les fonctions peuvent utiliser la bibliothèque de requêtes pour effectuer des requêtes HTTP vers les API de HubSpot et d'autres API. 

Un fichier serverless-function.js de base ressemble à ceci :

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

Clés d'objet contextuel

Clés d'objet contextuel
ParameterDescription
accountId

L'ID du compte HubSpot contenant la fonction.

body

L'élément body est renseigné si la demande est envoyée comme une demande POST avec un type de contenu application/json.

contact

Si la demande provient d'un contact intégré dans des cookies, l'objet de contact sera présent avec un ensemble de propriétés de contact de base. Ces propriétés supplémentaires seront également disponibles :

  • vid : l'ID visiteur du contact.
  • isLoggedIn : lorsque vous utilisez le contrôle de l'accès au CMS, la valeur sera true si le contact est connecté au domaine.
  • listMemberships : un tableau d'ID de listes de contacts dont le contact est membre.
headers

Contient les en-têtes envoyés par le client qui atteint votre point de terminaison. Consultez les en-têtes.

params

L'élément params est renseigné avec les valeurs de la chaîne de requête et les valeurs HTML Form-POST. Celles-ci sont structurées comme une carte avec des chaînes de caractères comme clés et un tableau de chaînes de caractères pour chaque valeur. context.params.yourvalue

limits

Renvoie le degré de rapprochement quant aux limites associées aux fonctions sans serveur.

  • executionsRemaining – Nombre d'exécutions par minute restantes.
  • timeRemaining – Temps d'exécution autorisé restant.

En-têtes

Parfois, il peut être utile d'avoir les en-têtes du client qui atteint votre point de terminaison. Nous fournissons les en-têtes suivants via context.headers. Cette méthode est similaire à celle utilisée pour accéder aux informations par le biais de context.body.

Use this table to describe parameters / fields
En-têteDescription
accept

Indique quels types de contenu, exprimés en types MIME, le client comprend.Consultez MDN.

accept-encoding

Communique le codage du contenu que le client comprend. Consultez MDN.

accept-language

Indique la langue et les paramètres régionaux préférés. Consultez MDN.

cache-control

Contient des directives pour la mise en cache. Consultez MDN.

connection

Indique si la connexion réseau reste ouverte. Consultez MDN.

cookie

Contient les cookies envoyés par le client. Consultez MDN.

host

Communique le nom de domaine et le numéro de port TCP d'un serveur en écoute. Consultez MDN.

true-client-ip

Adresse IP de l'utilisateur final. Consultez Cloudflare true-client-ip.

upgrade-insecure-requests

Communique la préférence du client pour une réponse chiffrée et authentifiée. Consultez MDN.

user-agent

Chaîne définie par le fournisseur identifiant l'application, le système d'exploitation, le fournisseur de l'application et la version. Consultez MDN.

x-forwarded-for

Identifie l'adresse IP d'origine d'un client via un proxy ou un équilibreur de charge. Consultez MDN.

Rediriger en envoyant un en-tête

Vous pouvez effectuer une redirection depuis votre fonction sans serveur en envoyant une réponse avec un en-tête de localisation et un code de statut 301.

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

Définir des cookies à partir de votre point de terminaison

Depuis votre fonction sans serveur, vous pouvez indiquer au client (navigateur web) de définir un cookie.

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

Définir plusieurs valeurs pour un seul en-tête

Pour les en-têtes qui prennent en charge plusieurs valeurs, vous pouvez utiliser multiValueHeaders pour transmettre les valeurs. Par exemple, vous pouvez demander au navigateur d'installer plusieurs cookies.

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

Secrets

Les clés d'API et les informations d'authentification sont appelées secrets. Une fois ajoutées, elles sont accessibles par le biais de variables d'environnement (process.env.secretName). Vous pouvez attribuer des secrets disponibles pour des points de terminaison spécifiques à utiliser en ajoutant la clé "secrets" à votre fichier serverless.json. Les secrets sont gérés via l'ILC de HubSpot à l'aide des commandes suivantes :

Ne renvoyez pas la valeur de votre secret par le biais du journal de la console ou comme réponse. En faisant cela, vous diffuseriez vos secrets dans vos journaux ou dans les interfaces qui exécutent votre fonction sans serveur.

Utilisation de fonctions sans serveur avec l'élément de formulaire

Lors de la soumission des fonctions sans serveur, utilisez JavaScript pour gérer la soumission du formulaire et utilisez l'en-tête "contentType" : "application/json" dans votre requête. N'utilisez pas l'attribut action des éléments <form>.

CORS

Le partage des ressources entre origines multiples (CORS) est une fonction de sécurité du navigateur. Par défaut, les navigateurs limitent les demandes d'origines multiples initiées par JavaScript. Cela permet d'éviter qu'un code malveillant exécuté sur un autre domaine n'affecte votre site. Il s'agit de la règle d'origine unique. Comme l'envoi et la récupération de données à partir d'autres serveurs sont parfois nécessaires, le serveur externe peut fournir des en-têtes HTTP qui indiquent les origines autorisées à lire les informations dans un navigateur.

Vous ne devriez pas rencontrer de problèmes CORS en appelant votre fonction sans serveur dans vos pages hébergées par HubSpot. Si c'est le cas, vérifiez que vous utilisez le bon protocole.

Vous rencontrez cette erreur CORS ?
"Access to fetch at [your function url] from origin [page making request] has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled."

Votre demande a-t-elle une origine différente de celle du site qui l'appelle ?

  • Si le nom de domaine est différent, oui.
  • Si vous utilisez un protocole différent (http, https), oui.

Si vous utilisez un protocole différent, il suffit de modifier le protocole en conséquence et le problème sera résolu. 

Pour l'instant, vous ne pouvez pas modifier l'en-tête Access-Control-Allow-Origin de HubSpot.

Consultez MDN pour obtenir des informations plus détaillées sur la résolution des erreurs CORS.

Demandes GET

Les demandes GET peuvent effectuer des demandes CORS selon le client. Les requêtes GET n'écrivent rien, elles ne font que renvoyer des données.

Packs préchargés

Les fonctions sans serveur de HubSpot sont actuellement préchargées avec les packs suivants :

Pour utiliser la dernière version prise en charge d'un pack préchargé ou pour utiliser un pack nouvellement ajouté :

  1. Clonez ou copiez votre fichier de fonction.
  2. Modifiez le point de terminaison de votre fonction dans le fichier serverless.json pour qu'il pointe vers votre nouveau fichier de fonction. Vous pouvez supprimer l'ancienne version en toute sécurité.

Si vous souhaitez inclure des packs en dehors de l'ensemble de packs préchargés, vous pouvez utiliser webpack pour combiner vos modules de nœud et faire en sorte que vos fichiers groupés soient vos fichiers de fonction.

Limites d'utilisation

Les fonctions sans serveur sont destinées à être rapides avec un objectif restreint. Pour permettre des appels et des réponses rapides, les fonctions sans serveur de HubSpot sont limitées à :

  • 50 secrets par compte.
  • 128 Mo de mémoire.
  • Pas plus de 100 points de terminaison par compte HubSpot.
  • Le type de contenu application/json doit être utilisé lors de l'appel d'une fonction.
  • Les journaux des fonctions sans serveur sont conservés pendant 90 jours.
  • 6 Mo sur une charge utile d'invocation AWS Lambda.

Limites d'exécution

  • Chaque fonction a un temps d'exécution maximum de 10 secondes.
  • Chaque compte est limité à 600 secondes d'exécution totale par minute.

Cela signifie que l'une ou l'autre de ces situations peut se produire :

  • 60 exécutions de fonctions qui prennent chacune 10 secondes à être terminées.
  • 6 000 exécutions de fonctions qui prennent 100 millisecondes à être terminées.

Les fonctions qui dépassent ces limites de temps envoient un message d'erreur. Le nombre d'exécutions et les limites de temps renverront une réponse 429. Le temps d'exécution de chaque fonction est inclus dans les journaux des fonctions sans serveur.

Pour éviter d'atteindre ces limites, les données relatives aux limites sont fournies automatiquement selon le contexte de la fonction pendant l'exécution. Vous pouvez vous en servir pour influencer votre demande afin de respecter ces limites. Par exemple, si votre application exige que votre point de terminaison soit interrogé, vous pouvez renvoyer avec vos données une variable pour influencer la fréquence de l'interrogation. Ainsi, lorsque le trafic est élevé, vous pouvez ralentir le taux d'interrogation pour éviter de dépasser les limites, puis le réaugmenter lorsque le trafic est faible.

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.