サーバーレス関数リファレンス

APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

この記事では、サーバーレスの.functionsフォルダー内にあるファイルと、サーバーレス関数で使用できるCLIコマンドについて説明します。

サーバーレス関数の概略については、サーバーレス関数の概要をご確認ください。

注：HubSpot CLIを使用して、サーバーレス関数ファイルをローカル環境からアップロードする必要があります。

serverless.json

serverless.jsonファイルには、.functionsフォルダー内の関数についての設定を格納します。サーバーレス関数が機能するにはこのファイルが必要です。このファイルによって、関数がエンドポイントにマッピングされます。

// serverless.json { "runtime": "nodejs12.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
キーTypeDescription
runtime
必須
String

ランタイム環境。現在、nodejs12.x（Node.jsバージョン12）がサポートされています。

version
必須
String

HubSpotサーバーレス関数スキーマバージョン。（現在のバージョン1.0）

endpoints
必須
Object

エンドポイントでは、functionsフォルダーにおいて、公開されるパスおよび特定のJavaScriptファイルへのマッピングが定義されます。

environment
Object

実行環境で、実行される関数に環境変数として渡される設定用変数。環境変数に基づいて、実際のAPIの代わりにテストバージョンを使用するロジックを追加する場合などに使用します。

secrets
array

APIキーはシークレットです。設定ファイル内のシークレットとは、シークレットの値ではなく名前を指します。このファイルにはシークレットを直接入力しないで、シークレット名の参照にとどめてください。

注：シークレットと環境変数に同じ名前を付けないでください。関数内の値を返すときに競合が発生します。

エンドポイント

各エンドポイントには独自の環境変数とシークレットを設定できます。エンドポイント外で指定した変数は、全ての関数とエンドポイントに適用する設定として使用されます。

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

エンドポイントにはいくつかの固有のキーがあります。

Use this table to describe parameters / fields
キーTypeDescription
method
String or array of strings

このエンドポイントによってサポートされるHTTPメソッド（複数可）。既定ではGETです。

file
必須
String

エンドポイントの実装があるJavaScript関数ファイルへのパス。

サーバーレス関数は、HubSpotにてご使用のCMSアカウントのドメインのパスを通して公開されます。これには、既定の.hs-sites.comサブドメインも含まれます。

このような関数には、次のURLでアクセスできます。 

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

ここでは、各URLコンポーネントについて説明します。

Use this table to describe parameters / fields
ParameterDescription
domainName

自分のドメイン名。

/_hcms/api/

サーバーレス関数用に予約済みのパス。このパスに、全てのエンドポイントを置きます。

endpoint-name/path

serverless.jsonファイル内に指定したエンドポイント名またはパス。

hubId

自分のHub ID。これをリクエストに含めることにより、モジュールおよびテンプレートのプレビュー時に関数をテストできます。

関数ファイル

各関数は、.functionsで終わるフォルダー内のNode.js JavaScriptファイルとして作成されます。関数では、Node.jsの標準ライブラリーに加えてrequestライブラリーを利用してHubSpot APIや他のAPIへのHTTPリクエストを行うことも可能です。 

基本的なserverless-function.jsファイルの例を示します。

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

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

コンテキスト オブジェクト キー
ParameterDescription
accountId

関数が含まれているHubSpotアカウントのID。

body

本文は、コンテンツタイプapplication/jsonのPOSTリクエストとして送信する場合に入力します。

contact

Cookieに紐付けられたコンタクトから送信されたリクエストの場合、基本的なコンタクトプロパティーが含まれたコンタクトオブジェクトになります。また、以下のプロパティーも使用できます。

  • vid：コンタクトの訪問者ID。
  • isLoggedIn：CMSのアクセス権設定（メンバーシップ機能）を使用した状態で、コンタクトがドメインにログインしている場合はtrueになります。
  • listMemberships：このコンタクトがメンバーとして含まれる、コンタクトリストIDの配列。
headers

エンドポイントに対してクライアントから送信されたヘッダーが含まれます。ヘッダーを参照してください。

params

paramsには、クエリー文字列値、およびHTMLフォームによるPOST値（存在する場合）が入ります。文字列によるキーと、文字列の配列による値から成るマップとして構成されます。context.params.yourvalue

limits

サーバーレス関数のレート制限にどの程度近づいているかを返します。

  • executionsRemaining：残っている実行数（1分あたり）。
  • timeRemaining：残っている実行可能時間。

ヘッダー

エンドポイントに対するクライアントからのヘッダーがあると、役立つ場合があります。context.headerでは以下のヘッダーを提供しています。これは、context.bodyによる情報の取得と同様です。

Use this table to describe parameters / fields
ヘッダーDescription
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ヘッダーとstatusCode 301を含むレスポンスを送信することで、サーバーレス関数からリダイレクトを実行できます。

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

エンドポイントから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キーおよび認証情報はシークレットと呼ばれます。一度追加されると、環境変数（process.env.secretName）としてアクセス可能になります。serverless.jsonファイルにsecretsキーを追加することで、特定のエンドポイント用のシークレットを割り当てることができます。シークレットの管理には、HubSpot CLIで以下のコマンドを使用します。

コンソールログを使用して、またはレスポンスとしてシークレットの値を返さないでください。ログやサーバーレス関数を呼び出すフロントエンドページでシークレットが漏洩するおそれがあるためです。

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

サーバーレス関数の送信時には、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ファイル内の関数のエンドポイントを変更して、新しい関数ファイルを指すようにします。旧バージョンは問題なく削除できます。

事前に読み込まれる一連のパッケージには含まれないパッケージをインクルードするには、webpackを使用してノードモジュールを結合し、バンドルされたファイルを関数ファイルとして使用します。

制限

サーバーレス関数は、高速の特定用途を対象として設計されています。迅速な呼び出しとレスポンスを可能にするために、HubSpotのサーバーレス関数には次のような制限があります。

  • 1アカウントあたり50個のシークレット
  • 128MBのメモリー
  • HubSpotアカウントあたり100個以下のエンドポイント
  • 関数の呼び出しにはcontentType application/jsonを使用する必要があります。
  • サーバーレス関数のログは90日間保存されます。
  • AWS Lambda呼び出しでのペイロードは6MB。

実行制限

  • 各関数の実行時間は最大10秒に制限されます。
  • 各アカウントでは、1分あたり合計600秒の実行時間に制限されます。

つまり、次のいずれかのような状況での利用が可能です。

  • 10秒で完了する関数を60回実行する。
  • 100ミリ秒で完了する関数を6,000回実行する。

これらの制限を超える関数は、エラーになります。実行数と時間の制限の場合は、429のレスポンスが返されます。各関数の実行時間は、サーバーレス関数ログに記録されます。

上記の制限を回避できるよう、実行中に自動で制限データが関数コンテキストに提供されます。その情報に基づいて、アプリケーションを制限内にとどめるような調整を行うことができます。例えばアプリケーションからエンドポイントへのポーリングが必要な場合、ポーリング頻度を調整するための変数をデータと共に返すことができます。これにより、トラフィックの増大時にも制限に到達しないようにポーリング速度を抑え、トラフィックの減少後に元に戻すことが可能になります。

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。