Zum Hauptinhalt springen

Unterstützte Produkte

Erfordert eines der folgenden Produkte oder höher.
Content HubContent Hub -Enterprise
Letzte Änderung: 10. Oktober 2025

Hinweis:

Diese Seite enthält Referenzinformationen für serverlose Funktionen, die mit dem Design-Manager erstellt wurden. Dies war bisher die Methode, um serverlose Funktionen für Ihre CMS-Seiten zu erstellen, und wird immer noch unterstützt. In Zukunft wird jedoch empfohlen, serverlose Funktionen mit HubSpot-Entwicklerprojekten zu erstellen und bereitzustellen. Projektbasierte serverlose Funktionen können Abhängigkeiten von Drittanbietern umfassen und über Zugriffstoken von privaten Apps direkteren Zugriff auf die Authentifizierung haben.
In diesem Artikel erfahren Sie mehr über die Dateien, die sich in einem serverlosen .functions-Ordner befinden, und die CLI-Befehle, die Sie mit serverlosen Funktionen verwenden können. Einen umfassenden Überblick über serverlose Funktionen finden Sie in der Übersicht über serverlose Funktionen. Weitere Informationen zum Erstellen serverloser Funktionen mit Projekten für JavaScript gerenderte Module und Partials finden Sie in der Dokumentation zu Entwicklerprojekten.

Serverless.json

Im .functions-Ordner speichert die serverless.json-Datei die Konfiguration der serverlosen Funktion. Dies ist eine erforderliche Datei und sie ordnet Ihre Funktionen ihren Endpunkten zu.
{
  "runtime": "nodejs20.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"
      ]
    }
  }
}
SchlüsselTypBeschreibung
runtimeStringDie Laufzeitumgebung. Unterstützt Node.js v20 (nodejs20.x).
versionZeichenfolgeSchema-Version der serverlosen Funktion von HubSpot. (Aktuelle Version 1.0)
environmentObjektKonfigurationsvariablen, die zur Laufzeit als Umgebungsvariablen an die ausführende Funktion übergeben werden. Sie könnten dies verwenden, um eine Logik für die Verwendung einer Testversion einer API anstelle der echten Version auf der Grundlage einer Umgebungsvariablen hinzuzufügen.
secretsArrayEin Array mit den Namen der Geheimnisse, die Ihre serverlose Funktion für die Authentifizierung verwendet. Speichern Sie Geheimniswerte nicht direkt in dieser Datei, sondern verweisen Sie nur auf die Geheimnisnamen.
endpointsObjektEndpunkte definieren die Pfade, die zugänglich gemacht werden, und ihre Zuordnung zu bestimmten JavaScript-Dateien in Ihrem Funktionsordner. Erfahren Sie mehr über Endpunkt.
HubSpot wird Node 18 ab dem 1. Oktober 2025 nicht mehr unterstützen. Nach diesem Datum können serverlose Funktionen mit einer Laufzeit unter v20 nicht mehr bereitgestellt werden.

Hinweis:

Weisen Sie Ihren Geheimnissen und Umgebungsvariablen nicht denselben Namen zu. Andernfalls kommt es zu Konflikten bei der Rückgabe ihrer Werte in der Funktion.

Endpunkte

Jeder Endpunkt kann seine eigenen Umgebungsvariablen und Geheimnisse haben. Außerhalb von Endpunkten angegebene Variablen sollten für Konfigurationseinstellungen verwendet werden, die für alle Funktionen und Endpunkte gelten.
"events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "configKey": "some-other-value"
      },
      "secrets": ["googleAPIKeyName","otherKeyName"]
    }
SchlüsselTypBeschreibung
methodZeichenfolge oder ein Array von ZeichenfolgenHTTP-Methode oder -Methoden, die der Endpunkt unterstützt. Die Standardeinstellung ist GET.
fileZeichenfolgePfad zur JavaScript-Funktionsdatei mit der Implementierung für den Endpunkt.
Der Endpunkt kann durch den Aufruf einer URL auf einer der mit dem HubSpot-Account verbundenen Domains, einschließlich der standardmäßigen .hs-sites.com-Subdomains, mit der folgenden URL-Struktur aufgerufen werden: https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}.
ParameterBeschreibung
domainNameEine Domain, die mit dem HubSpot-Account verknüpft ist.
/_hcms/api/Der für serverlose Funktionen reservierte Pfad. Alle Endpunkte befinden sich innerhalb dieses Pfades.
endpoint-name/pathDer Endpunktname oder -pfad, den Sie in der serverless.json-Datei angegeben haben.
portalidEin optionaler Abfrageparameter, der Ihre HubSpot-Account-ID enthält. Wenn Sie dies in der Anfrage angeben, können Sie Ihre Funktionen in Modul- und Vorlagenvorschauen testen.
Wenn z. B. sowohl website.com als auch subdomain.brand.com mit dem Account verknüpft ist, können Sie die Funktion entweder über https://website.com/_hcms/api/{endpoint-name/path} oder https://subdomain.brand.com/_hcms/api/{endpoint-name/path} aufrufen.

Funktionsdatei

Neben der serverless.json-Konfigurationsdatei enthält der Ordner .functions-Ordner auch eine Node.js-JavaScript-Datei, die die Funktion definiert. Sie können die Bibliothek der Anfragen auch verwenden, um HTTP-Anfragen an HubSpot-APIs und andere APIs durchzuführen. Zum Beispiel:
// 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 });
};

Kontextobjekt

Das Kontextobjekt enthält Kontextinformationen über die Ausführung der Funktion, die in den folgenden Parametern gespeichert sind.
ParameterBeschreibung
accountIdDie HubSpot-Account-ID, die die Funktion enthält.
bodyWird ausgefüllt, wenn die Anfrage als POST mit dem Inhaltstyp application/json gesendet wird.
contactWenn die Anfrage von einem Kontakt mit einem gesetzten Cookie stammt, wird das Kontaktobjekt mit einer Reihe von grundlegenden Kontakteigenschaften mit den folgenden Informationen gefüllt:
  • vid: Die Besucher-ID des Kontakts.
  • isLoggedIn: Bei Verwendung von CMS-Zugriffsberechtigungen ist dies true, wenn der Kontakt in der Domain angemeldet ist.
  • listMemberships: ein Array von Kontaktlisten-IDs, in denen dieser Kontakt Mitglied ist.
headersEnthält die Header, die vom Client gesendet werden, der Ihren Endpunkt erreicht.
paramsGefüllt mit Abfragezeichenfolgenwerten zusammen mit allen HTML-Formular-POST-Werten. Diese sind als Zuordnung mit Zeichenfolgen als Schlüssel und einem Array von Zeichenfolgen für jeden Wert strukturiert.context.params.yourvalue
limitsGibt zurück, wie nah Sie dem Limit der Ratenbeschränkungen für serverlose Funktionen sind.
  • executionsRemaining: wie viele Ausführungen pro Minute noch übrig sind.
  • timeRemaining: wie viel erlaubte Ausführungszeit noch übrig ist.
Wenn Sie die Header des Clients, der Ihren Endpunkt erreicht, in Erfahrung bringen müssen, können über context.headers auf diese zugreifen, ähnlich wie Sie über context.body auf Informationen zugreifen würden. Im Folgenden finden Sie einige der gängigen Header, die HubSpot bereitstellt. Eine vollständige Liste finden Sie in der HTTP-Header-Dokumentation von MDN.
HeaderBeschreibung
acceptTeilt mit, welche Inhaltstypen, ausgedrückt als MIME-Typen, der Client versteht. Siehe MDN.
accept-encodingTeilt die Inhaltskodierung mit, die der Client versteht. Siehe MDN.
accept-languageTeilt mit, welche menschliche Sprache und welches Gebietsschema bevorzugt wird. Siehe MDN.
cache-controlEnthält Richtlinien für die Zwischenspeicherung. Siehe MDN.
connectionTeilt mit, ob die Netzwerkverbindung offen bleibt. Siehe MDN.
cookieEnthält Cookies, die der Client gesendet hat. Siehe MDN.
hostÜbermittelt den Domain-Namen und die TCP-Portnummer eines überwachenden Servers. Siehe MDN.
true-client-ipIP-Adresse des Endbenutzers. Siehe Cloudflare true-client-ip.
upgrade-insecure-requestsTeilt mit, dass die Clients eine verschlüsselte und authentifizierte Antwort wünschen. Siehe MDN.
user-agentVom Hersteller definierte Zeichenfolge zur Identifizierung der Anwendung, des Betriebssystems, des Anwendungsherstellers und der Version. Siehe MDN.
x-forwarded-forIdentifiziert die ursprüngliche IP-Adresse eines Clients durch einen Proxy oder Load Balancer. Siehe MDN.

Weiterleitung durch Senden eines Headers

Sie können eine Weiterleitung von Ihrer serverlosen Funktion durchführen, indem Sie eine Antwort mit einem Standort-Header und 301-statusCode senden.
sendResponse({
  statusCode: 301,
  headers: {
    Location: 'https://www.example.com',
  },
});

Cookies von Ihrem Endpunkt aus setzen

Über Ihre serverlose Funktion können Sie dem Client (Webbrowser) mitteilen, dass er ein Cookie setzen soll.
exports.main = (context, sendResponse) => {
    sendResponse({
      body: { ... },
      'Set-Cookie': 'myCookie1=12345; expires=...; Max-Age=...',
      statusCode: 200
    });
  }

Mehrere Werte für einen einzigen Header festlegen

Für Header, die mehrere Werte unterstützen, können Sie multiValueHeaders verwenden, um die Werte zu übergeben. Zum Beispiel können Sie den Browser anweisen, mehrere Cookies zu setzen.
exports.main = (context, sendResponse) => {
  sendResponse({
    body: { ... },
    multiValueHeaders: {
      'Set-Cookie': [
        'myCookie1=12345; expires=...; Max-Age=...',
        'myCookie2=56789; expires=...; Max-Age=...'
       ]
    },
    statusCode: 200
  });
}

Geheimnisse

Wenn Sie eine Anfrage der serverlosen Funktionen authentifizieren müssen, verwenden Sie Geheimnisse, um Werte wie API-Schlüssel oder private App-Zugriffstoken zu speichern. Mit dem CLI können Sie Ihrem HubSpot-Account Geheimnisse hinzufügen, um diese Werte zu speichern, auf die Sie später über Umgebungsvariablen (process.env.secretName) zugreifen können. Geheimnisse werden über die HubSpot-Befehlszeile mit den folgenden Befehlen verwaltet: Sobald Geheimnisse über das CLI hinzugefügt wurden, können sie Funktionen zur Verfügung gestellt werden, indem ein secrets-Array mit dem Namen des Geheimnisses hinzugefügt wird. Auf diese Weise können Sie Ihren Funktionscode in der Versionskontrolle speichern und Geheimnisse verwenden, ohne sie preiszugeben. Sie sollten jedoch niemals den Wert Ihres Geheimnisses durch Konsolenprotokollierung oder als Antwort zurückgeben, da dies das Geheimnis in Protokollen oder auf Frontend-Seiten preisgibt, die Ihre serverlose Funktion aufrufen.

Hinweis:

Aufgrund der Zwischenspeicherung kann es etwa eine Minute dauern, bis aktualisierte geheime Werte angezeigt werden. Wenn Sie gerade ein Geheimnis aktualisiert haben, aber immer noch den alten Wert sehen, überprüfen Sie es nach etwa einer Minute erneut.

Verwendung von serverlosen Funktionen mit dem form-Element

Bei der Übermittlung von serverlosen Funktionen verwenden Sie JavaScript, um die Formulareinsendung zu verarbeiten, und verwenden Sie den "contentType" : "application/json"-Header in Ihrer Anfrage. Verwenden Sie nicht das <form>-Attribut action-Elemente.

CORS

Cross Origin Resource Sharing (CORS) ist eine Sicherheitsfunktion des Browsers. Standardmäßig schränken Browser durch JavaScript initiierte herkunftsübergreifende Anfragen ein. Dadurch wird verhindert, dass bösartiger Code, der auf einer anderen Domain läuft, Ihre Website beeinträchtigt. Dies wird als Same-Origin-Policy bezeichnet. Da das Senden und Abrufen von Daten von anderen Servern manchmal notwendig ist, kann der externe Server HTTP-Header bereitstellen, die mitteilen, welche Herkunft die Informationen von einem Browser lesen darf. Sie sollten keine CORS-Probleme haben, wenn Sie Ihre serverlose Funktion innerhalb Ihrer von HubSpot gehosteten Seiten aufrufen. Wenn dies doch der Fall ist, vergewissern Sie sich, dass Sie das richtige Protokoll verwenden.
Erhalten Sie diesen CORS-Fehler? „Access to fetch at [Ihre Funktions-URL] from origin [Seite, die die Anfrage stellt] 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“Geht Ihre Anfrage an einen anderen Ursprung als die aufrufende Seite?
  • Wenn der Domain-Name anders ist, ja.
  • Bei Verwendung eines anderen Protokolls (http, https), ja.
Wenn Sie ein anderes Protokoll verwenden, ändern Sie einfach das Protokoll, und das Problem ist behoben.Sie können den Access-Control-Allow-Origin von HubSpot derzeit nicht ändern.Siehe MDN für weitere detaillierte CORS-Fehlerbehebung.

GET-Anfragen

GET-Anfragen können je nach Client auch CORS-Anfragen stellen. Bei GET-Anfragen wird nichts geschrieben, sondern nur Daten zurückgegeben.

Vorinstallierte Pakete

Serverlose HubSpot-Funktionen werden derzeit mit den folgenden Paketen vorinstalliert: So nutzen Sie die neueste unterstützte Version eines vorinstallierten Pakets bzw. so nutzen Sie ein neu hinzugefügtes Paket:
  1. Klonen oder kopieren Sie Ihre Funktionsdatei.
  2. Ändern Sie den Endpunkt Ihrer Funktion in der serverless.json-Datei, um auf Ihre neue Funktionsdatei zu verweisen. Sie können die alte Version bedenkenlos löschen.
Wenn Sie Pakete außerhalb des vorinstallierten Paketsatzes einbinden möchten, können Sie webpack verwenden, um Ihre Node-Module zu kombinieren und Ihre gebündelten Dateien als Funktionsdateien zu verwenden.

Beschränkungen

Serverlose Funktionen sollen schnell sein und einen engen Fokus haben. Um schnelle Aufrufe und Antworten zu ermöglichen, unterliegen die serverlosen Funktionen von HubSpot folgenden Beschränkungen:
  • 50 Geheimnisse pro Account
  • 128 MB Speicher
  • Nicht mehr als 100 Endpunkte pro HubSpot-Account
  • Sie müssen contentType application/json beim Aufrufen einer Funktion verwenden.
  • Protokolle der serverlosen Funktionen werden 90 Tage lang gespeichert.
  • 6 MB in einer AWS Lambda-Aufruf-Payload
Ausführungslimits
  • Jede Funktion hat eine maximale Ausführungszeit von 10 Sekunden.
  • Jeder Account ist auf insgesamt 600 Ausführungssekunden pro Minute beschränkt.
Das bedeutet, dass jedes dieser Szenarien eintreten kann:
  • 60 Funktionsausführungen, die jeweils 10 Sekunden in Anspruch nehmen
  • 6.000 Funktionsausführungen, die 100 Millisekunden dauern
Funktionen, die diese Limits überschreiten, lösen einen Fehler aus. Ausführungsanzahl und Zeitlimits geben eine 429-Antwort zurück. Die Ausführungszeit jeder Funktion wird in den Protokollen der serverlosen Funktionen berücksichtigt. Um diese Beschränkungen zu umgehen, werden dem Funktionskontext während der Ausführung automatisch Daten für Obergrenzen zur Verfügung gestellt. Sie können dies nutzen, um Ihre Anwendung so zu beeinflussen, dass sie innerhalb dieser Obergrenzen bleibt. Wenn Ihre Anwendung beispielsweise die Abfrage Ihres Endpunkts erfordert, können Sie mit Ihren Daten eine Variable zurückgeben, um die Häufigkeit der Abfrage zu beeinflussen. Auf diese Weise können Sie bei hohem Traffic die Abrufrate verlangsamen, um ein Überschreiten der Obergrenzen zu vermeiden, und sie dann bei geringem Traffic wieder erhöhen.
I