サポートされる製品
次のいずれかの製品またはそれ以上が必要です。
最終更新日: 2025年8月28日
注:
このページには、デザインマネージャーを使用して作成されたサーバーレス関数のリファレンス情報が含まれています。これはCMSページのサーバーレス関数を作成する従来の方法であり、現在もサポートされています。ただし、今後はHubSpot開発者プロジェクトを使ったサーバーレス関数の作成とデプロイが推奨されます。プロジェクトベースのサーバーレス関数には、サードパーティーの依存関係を含めることができ、非公開のアプリアクセストークンを介した認証により直接アクセスできます。.functions
フォルダー内にあるファイルと、サーバーレス関数で使用できるCLIコマンドについて説明します。
サーバーレス関数の概要については、サーバーレス関数の概要をご確認ください。
JavaScriptのレンダリングされたモジュールとパーシャルのプロジェクトを使用してサーバーレス関数を作成する方法の詳細については、開発者プロジェクトのドキュメントをご参照ください。
Serverless.json
.functions
フォルダーのserverless.json
ファイルには、サーバーレス関数構成が保存されます。これは必須ファイルであり、これによって関数がAPIエンドポイントにマッピングされます。
キー | 型 | 説明 |
---|---|---|
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エンドポイントに適用する設定として使用されます。キー | 型 | 説明 |
---|---|---|
method | 文字列または文字列の配列 | このAPIエンドポイントでサポートされているHTTPメソッド(複数可)。デフォルトではGETです。 |
file | 文字列 | APIエンドポイントの実装を含むJavaScript関数ファイルへのパス。 |
.hs-sites.com
サブドメインを含む)で以下のURL構造のURLを呼び出します。
https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}
パラメーター | 説明 |
---|---|
domainName | HubSpotアカウントに接続されているドメイン。 |
/_hcms/api/ | サーバーレス関数用に予約されたパス。全てのAPIエンドポイントは、このパスに存在しています。 |
endpoint-name/path | serverless.json ファイルで指定したAPIエンドポイントの名前またはパス。 |
portalid | HubSpotアカウントIDを含む任意のクエリーパラメーター。これをリクエストに含めることで、モジュールとテンプレートのプレビュー時に関数のテストを行えます。 |
website.com
とsubdomain.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リクエストを行うこともできます。
以下に例を示します。
コンテキストオブジェクト
コンテキストオブジェクトには、次のパラメーターに格納された、関数の実行に関するコンテキスト情報が含まれています。パラメーター | 説明 |
---|---|
accountId | 関数が含まれているHubSpotアカウントのID。 |
body | application/json のコンテンツタイプを持つPOST リクエストが送信された場合に取り込まれます。 |
contact | リクエストがCookieにひも付けられたコンタクトから送信された場合、contactオブジェクトには一連の基本的なコンタクトプロパティーに加え、以下の情報が格納されます。
|
headers | APIエンドポイントに対してクライアントから送信されたヘッダーが含まれます。 |
params | クエリー文字列値、およびHTMLフォームによるPOST値が取り込まれます。文字列によるキーと文字列の配列による値のマップとして構成されます。context.params.yourvalue |
limits | サーバーレス関数のレート制限にどの程度近づいているかに関する情報を返します。
|
ヘッダー
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を含むレスポンスを送信することで、サーバーレス関数からリダイレクトを実行できます。
APIエンドポイントからCookieを設定する
サーバーレス関数によって、クライアント(ウェブブラウザー)にCookieを設定するように指示できます。1つのヘッダーに複数の値を設定する
複数の値をサポートするヘッダーには、multiValueHeaders
を使用して値を渡すことができます。例えば、ブラウザーに複数のCookieを設定するように指示できます。
シークレット
サーバーレス関数リクエストを認証する必要がある場合は、シークレットを使用して、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)が異なる場合も該当します。
Access-Control-Allow-Origin
ヘッダーを変更することはできません。CORSエラーのトラブルシューティングに関する詳細はMDNを参照してください。GETリクエスト
クライアントによっては、GETリクエストをCORSリクエストにすることが可能な場合があります。GETリクエストでは書き込みを行わないで、データを返すだけにしてください。事前に読み込まれるパッケージ
現在、HubSpotのサーバーレス関数には、以下の事前読み込みパッケージがあります。- @hubspot/api-client:1.0.0-beta以降
- axios:0.19.2以降
- request:2.88.0以降
- requests:0.2.2以降
- 関数ファイルを複製またはコピーします。
serverless.json
ファイル内の関数のAPIエンドポイントを変更して、新しい関数ファイルを指すようにします。旧バージョンは問題なく削除できます。
上限
サーバーレス関数は、高速の特定用途を対象として設計されています。迅速な呼び出しとレスポンスを可能にするために、HubSpotのサーバーレス関数には、次のような制限があります。- 1アカウントあたり50件のシークレット。
- 128MBのメモリー。
- HubSpotアカウントあたり100件以下のエンドポイント。
- 関数の呼び出しには
contentType
application/json
を使用する必要があります。 - サーバーレス関数ログの保存期間は90日。
- AWS Lambda呼び出しでのペイロードは6MB。
- 各関数の実行時間は最大10秒に制限されます。
- 各アカウントでは、1分あたりの実行時間が合計600秒に制限されます。
- 10秒で完了する関数を60回実行する。
- 100ミリ秒で完了する関数を6,000回実行する。
429
レスポンスが返されます。各関数の実行時間は、サーバーレス関数ログに記録されます。
上記の制限を回避できるよう、実行中に自動で制限データが関数コンテキストに提供されます。その情報に基づいて、アプリケーションを制限内にとどめるような調整を行うことができます。例えばアプリケーションからAPIエンドポイントへのポーリングが必要な場合、ポーリング頻度を調整するための変数をデータと共に返すことができます。これにより、トラフィックの増大時にも制限に到達しないようにポーリング速度を抑え、トラフィックの減少後に元に戻すことが可能になります。