サポートされる製品
次のいずれかの製品またはそれ以上が必要です。
Content HubContent HubEnterprise
最終更新日: 2025年8月28日

注:

このページには、デザインマネージャーを使用して作成されたサーバーレス関数のリファレンス情報が含まれています。これはCMSページのサーバーレス関数を作成する従来の方法であり、現在もサポートされています。ただし、今後はHubSpot開発者プロジェクトを使ったサーバーレス関数の作成とデプロイが推奨されます。プロジェクトベースのサーバーレス関数には、サードパーティーの依存関係を含めることができ、非公開のアプリアクセストークンを介した認証により直接アクセスできます。
この記事では、サーバーレスの.functionsフォルダー内にあるファイルと、サーバーレス関数で使用できるCLIコマンドについて説明します。 サーバーレス関数の概要については、サーバーレス関数の概要をご確認ください。 JavaScriptのレンダリングされたモジュールとパーシャルのプロジェクトを使用してサーバーレス関数を作成する方法の詳細については、開発者プロジェクトのドキュメントをご参照ください。

Serverless.json

.functionsフォルダーのserverless.jsonファイルには、サーバーレス関数構成が保存されます。これは必須ファイルであり、これによって関数がAPIエンドポイントにマッピングされます。
{
  "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"]
    }
  }
}
キー説明
runtime文字列ランタイム環境。Node.js v20(nodejs20.x)をサポートします。
version文字列HubSpotサーバーレス関数スキーマバージョン(現在のバージョンは1.0)
environmentオブジェクト関数の実行時に環境変数として渡される構成用の変数。環境変数に基づいて、実際のAPIの代わりにテストバージョンを使用するロジックを追加する場合などに使用します。
secrets配列サーバーレス関数が認証に使用するシークレットの名前を含む配列。このファイルにはシークレット値を直接格納するのではなく、シークレット名の参照だけを格納してください。
endpointsオブジェクトAPIエンドポイントは、公開されるパスと、functionsフォルダー内の特定のJavaScriptファイルへのそれらのパスのマッピングを定義します。詳しくはAPIエンドポイントをご参照ください。
HubSpotは2025年10月1日でNode 18のサポートを終了します。同日以降、ランタイムがv20未満のサーバーレス関数はデプロイできなくなります。\

注:

シークレットと環境変数に同じ名前を割り当てないでください。同じ名前を割り当てると、関数で値が返されるときに競合が発生します。

APIエンドポイント

各APIエンドポイントには独自の環境変数とシークレットを設定できます。APIエンドポイント外で指定した変数は、全ての関数とAPIエンドポイントに適用する設定として使用されます。
"events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "configKey": "some-other-value"
      },
      "secrets": ["googleAPIKeyName","otherKeyName"]
    }
キー説明
method文字列または文字列の配列このAPIエンドポイントでサポートされているHTTPメソッド(複数可)。デフォルトではGETです。
file文字列APIエンドポイントの実装を含むJavaScript関数ファイルへのパス。
エンドポイントを呼び出すには、HubSpotアカウントに接続されたドメインのいずれか(デフォルトの.hs-sites.comサブドメインを含む)で以下のURL構造のURLを呼び出します。 https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}
パラメーター説明
domainNameHubSpotアカウントに接続されているドメイン。
/_hcms/api/サーバーレス関数用に予約されたパス。全てのAPIエンドポイントは、このパスに存在しています。
endpoint-name/pathserverless.jsonファイルで指定したAPIエンドポイントの名前またはパス。
portalidHubSpotアカウントIDを含む任意のクエリーパラメーター。これをリクエストに含めることで、モジュールとテンプレートのプレビュー時に関数のテストを行えます。
例えば、website.comsubdomain.brand.comの両方がアカウントに接続されている場合、https://website.com/_hcms/api/{endpoint-name/path}またはhttps://subdomain.brand.com/_hcms/api/{endpoint-name/path}を使用して関数を呼び出すことができます。

関数ファイル

serverless.json構成ファイルに加え、.functionsフォルダーには関数を定義するNode.js JavaScriptファイルが格納されます。Requestライブラリーを利用して、HubSpot APIや他のAPIへのHTTPリクエストを行うこともできます。 以下に例を示します。
// 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 });
};

コンテキストオブジェクト

コンテキストオブジェクトには、次のパラメーターに格納された、関数の実行に関するコンテキスト情報が含まれています。
パラメーター説明
accountId関数が含まれているHubSpotアカウントのID。
bodyapplication/jsonのコンテンツタイプを持つPOSTリクエストが送信された場合に取り込まれます。
contactリクエストがCookieにひも付けられたコンタクトから送信された場合、contactオブジェクトには一連の基本的なコンタクトプロパティーに加え、以下の情報が格納されます。
  • vid:コンタクトの訪問者ID。
  • isLoggedIn:CMSメンバーシップ(アクセス権設定)を使用している場合、コンタクトがドメインにログインすると、この値がtrueに設定されます。
  • listMemberships:当該コンタクトがメンバーとなっているコンタクトリストIDの配列。
headersAPIエンドポイントに対してクライアントから送信されたヘッダーが含まれます。
paramsクエリー文字列値、およびHTMLフォームによるPOST値が取り込まれます。文字列によるキーと文字列の配列による値のマップとして構成されます。context.params.yourvalue
limitsサーバーレス関数のレート制限にどの程度近づいているかに関する情報を返します。
  • executionsRemaining:1分当たりの残っている実行数。
  • timeRemaining:残っている実行可能時間。

ヘッダー

APIエンドポイントにアクセスしているクライアントのヘッダーを把握する必要がある場合は、context.bodyを使用して情報にアクセスする場合と同じ方法で、context.headersを使用して該当するヘッダーにアクセスできます。 以下の表に、HubSpotが提供する一般的なヘッダーの一部を記載します。完全なリストについては、MDNのHTTPヘッダーのドキュメントをご参照ください。
ヘッダー説明
acceptクライアント側で処理できるコンテンツタイプをMIMEタイプとして示します。詳しくはMDNをご参照ください。
accept-encodingクライアント側で処理できるコンテンツエンコーディングを示します。詳しくはMDNをご参照ください。
accept-language使用される言葉とロケールを示します。詳しくはMDNをご参照ください。
cache-controlキャッシュ用のディレクティブを保持します。詳しくはMDNをご参照ください。
connectionネットワーク接続が開いたままかどうかを示します。詳しくはMDNをご参照ください。
cookieクライアントから送信されたCookieが格納されます。詳しくはMDNをご参照ください。
hostリスニングサーバーのドメイン名とTCPポート番号を示します。詳しくはMDNをご参照ください。
true-client-ipエンドユーザーのIPアドレス。詳しくはCloudflare true-client-ipをご参照ください。
upgrade-insecure-requestsレスポンスの暗号化と認証について、クライアント側の設定を示します。詳しくはMDNをご参照ください。
user-agentアプリケーション、オペレーティングシステム、アプリケーションベンダー、バージョンを識別するためのベンダー定義文字列。詳しくはMDNをご参照ください。
x-forwarded-forプロキシーまたはロードバランサーを通過するクライアントの発信元IPアドレスを識別します。詳しくはMDNをご参照ください。

ヘッダーの送信によるリダイレクト

「location」ヘッダーと301 statusCodeを含むレスポンスを送信することで、サーバーレス関数からリダイレクトを実行できます。
sendResponse({
  statusCode: 301,
  headers: {
    Location: 'https://www.example.com',
  },
});

APIエンドポイントからCookieを設定する

サーバーレス関数によって、クライアント(ウェブブラウザー)にCookieを設定するように指示できます。
exports.main = (context, sendResponse) => {
    sendResponse({
      body: { ... },
      'Set-Cookie': 'myCookie1=12345; expires=...; Max-Age=...',
      statusCode: 200
    });
  }

1つのヘッダーに複数の値を設定する

複数の値をサポートするヘッダーには、multiValueHeadersを使用して値を渡すことができます。例えば、ブラウザーに複数のCookieを設定するように指示できます。
exports.main = (context, sendResponse) => {
  sendResponse({
    body: { ... },
    multiValueHeaders: {
      'Set-Cookie': [
        'myCookie1=12345; expires=...; Max-Age=...',
        'myCookie2=56789; expires=...; Max-Age=...'
       ]
    },
    statusCode: 200
  });
}

シークレット

サーバーレス関数リクエストを認証する必要がある場合は、シークレットを使用して、APIキーや非公開アプリのアクセストークンなどの値を保存します。CLIを使用して、それらの値を保存するシークレットをHubSpotアカウントに追加することができます。その後でこれらの値にアクセスするには、環境変数(process.env.secretName)を使用します。シークレットの管理には、HubSpot CLIで以下のコマンドを使用します。 CLIを使用して追加されたシークレットは、そのシークレット名を含むsecrets配列を追加することで、関数で使用できるようになります。これにより、関数コードをバージョン管理に保存し、シークレットを公開せずに使用できるようになります。ただし、コンソールログを使用して、またはレスポンスとして、シークレットの値を返してはいけません。そうした場合、ログや、サーバーレス関数を呼び出すフロントエンドページでシークレットが公開されてしまいます。

注:

キャッシュ保存のため、更新されたシークレット値が表示されるまでに1分ほどかかる場合があります。シークレットを更新したばかりで、まだ古い値が表示されている場合は、1分ほどしてからもう一度ご確認ください。

フォーム要素からサーバーレス関数を使用する

サーバーレス関数の送信時には、JavaScriptを使ってフォーム送信を処理し、リクエストに"contentType" : "application/json"ヘッダーを使用します。<form>要素のaction属性は使用しないでください。

CORS

CORS(オリジン間リソース共有)はブラウザーのセキュリティー機能です。ブラウザーではデフォルトで、JavaScriptによって開始されたクロスオリジンリクエストが制限されます。これにより、異なるドメイン間で有害コードが実行され、貴社のサイトに影響を与えることを防止します。これは同一オリジンポリシーと呼ばれます。他のサーバーとのデータの送受信が必要な場合には、ブラウザーからの情報の読み取りをどのオリジン(発信元)に許可するかを示すHTTPヘッダーが外部サーバーから提供されることがあります。 HubSpot内にホスティングされたページでのサーバーレス関数の呼び出しにおいては、CORSの問題は発生しません。発生する場合、正しいプロトコルを使用していることを確認してください。
次のCORSエラーが発生している場合「発信元<リクエスト元ページ>から<関数URL>へのフェッチアクセスが、CORSポリシーによってブロックされました:プリフライトリクエストへのレスポンスが、アクセス制御検査に合格しません:要求されたリソースにはAccess-Control-Allow-Originヘッダーがありません。複雑なレスポンスを使用する場合は、リクエストのモードをno-corsに設定して、CORSが無効化されたリソースを取得してください」リクエストの送信元が呼び出し元サイトと異なるのはどのようなときですか?
  • ドメイン名が異なる場合が該当します。
  • 使用しているプロトコル(http、https)が異なる場合も該当します。
使用しているプロトコルが異なる場合は、プロトコルが一致するように変更するだけで解決します。現時点では、HubSpotのAccess-Control-Allow-Originヘッダーを変更することはできません。CORSエラーのトラブルシューティングに関する詳細はMDNを参照してください。

GETリクエスト

クライアントによっては、GETリクエストをCORSリクエストにすることが可能な場合があります。GETリクエストでは書き込みを行わないで、データを返すだけにしてください。

事前に読み込まれるパッケージ

現在、HubSpotのサーバーレス関数には、以下の事前読み込みパッケージがあります。 サポートされる最新バージョンの事前読み込み済みパッケージ、または新たに追加されたパッケージを使用するには、以下の操作を行います。
  1. 関数ファイルを複製またはコピーします。
  2. serverless.jsonファイル内の関数のAPIエンドポイントを変更して、新しい関数ファイルを指すようにします。旧バージョンは問題なく削除できます。
事前に読み込まれる一連のパッケージには含まれないパッケージをインクルードするには、webpackを使用してノードモジュールを結合し、バンドルされたファイルを関数ファイルとして使用します。

上限

サーバーレス関数は、高速の特定用途を対象として設計されています。迅速な呼び出しとレスポンスを可能にするために、HubSpotのサーバーレス関数には、次のような制限があります。
  • 1アカウントあたり50件のシークレット。
  • 128MBのメモリー。
  • HubSpotアカウントあたり100件以下のエンドポイント。
  • 関数の呼び出しにはcontentType application/jsonを使用する必要があります。
  • サーバーレス関数ログの保存期間は90日。
  • AWS Lambda呼び出しでのペイロードは6MB。
実行制限
  • 各関数の実行時間は最大10秒に制限されます。
  • 各アカウントでは、1分あたりの実行時間が合計600秒に制限されます。
つまり、次のいずれかのような状況での利用が可能です。
  • 10秒で完了する関数を60回実行する。
  • 100ミリ秒で完了する関数を6,000回実行する。
これらの制限を超える関数は、エラーになります。実行数と時間の制限に関しては、429レスポンスが返されます。各関数の実行時間は、サーバーレス関数ログに記録されます。 上記の制限を回避できるよう、実行中に自動で制限データが関数コンテキストに提供されます。その情報に基づいて、アプリケーションを制限内にとどめるような調整を行うことができます。例えばアプリケーションからAPIエンドポイントへのポーリングが必要な場合、ポーリング頻度を調整するための変数をデータと共に返すことができます。これにより、トラフィックの増大時にも制限に到達しないようにポーリング速度を抑え、トラフィックの減少後に元に戻すことが可能になります。