サーバーレス関数リファレンス
CMS Hub
- Enterprise
この記事では、サーバーレスの.functions
フォルダー内にあるファイルと、サーバーレス関数で使用できるCLIコマンドについて説明します。
サーバーレス関数の概略については、サーバーレス関数の概要をご確認ください。
注:HubSpot CLIを使用して、サーバーレス関数ファイルをローカル環境からアップロードする必要があります。
serverless.json
ファイルには、.functions
フォルダー内の関数についての設定を格納します。サーバーレス関数が機能するにはこのファイルが必要です。このファイルによって、関数がエンドポイントにマッピングされます。
キー | Type | Description |
---|---|---|
runtime
必須
| String | ランタイム環境。現在、nodejs12.x(Node.jsバージョン12)がサポートされています。 |
version
必須
| String | HubSpotサーバーレス関数スキーマバージョン。(現在のバージョン1.0) |
endpoints
必須
| Object | エンドポイントでは、functionsフォルダーにおいて、公開されるパスおよび特定のJavaScriptファイルへのマッピングが定義されます。 |
environment
| Object | 実行環境で、実行される関数に環境変数として渡される設定用変数。環境変数に基づいて、実際のAPIの代わりにテストバージョンを使用するロジックを追加する場合などに使用します。 |
secrets
| array | APIキーはシークレットです。設定ファイル内のシークレットとは、シークレットの値ではなく名前を指します。このファイルにはシークレットを直接入力しないで、シークレット名の参照にとどめてください。 |
注:シークレットと環境変数に同じ名前を付けないでください。関数内の値を返すときに競合が発生します。
各エンドポイントには独自の環境変数とシークレットを設定できます。エンドポイント外で指定した変数は、全ての関数とエンドポイントに適用する設定として使用されます。
エンドポイントにはいくつかの固有のキーがあります。
サーバーレス関数は、HubSpotにてご使用のCMSアカウントのドメインのパスを通して公開されます。これには、既定の.hs-sites.com
サブドメインも含まれます。
このような関数には、次のURLでアクセスできます。
https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}
ここでは、各URLコンポーネントについて説明します。
Parameter | Description |
---|---|
domainName
| 自分のドメイン名。 |
/_hcms/api/
| サーバーレス関数用に予約済みのパス。このパスに、全てのエンドポイントを置きます。 |
endpoint-name/path
|
|
hubId
| 自分のHub ID。これをリクエストに含めることにより、モジュールおよびテンプレートのプレビュー時に関数をテストできます。 |
各関数は、.functions
で終わるフォルダー内のNode.js JavaScriptファイルとして作成されます。関数では、Node.jsの標準ライブラリーに加えてrequestライブラリーを利用してHubSpot APIや他のAPIへのHTTPリクエストを行うことも可能です。
基本的なserverless-function.js
ファイルの例を示します。
Parameter | Description |
---|---|
accountId
| 関数が含まれているHubSpotアカウントのID。 |
body
| 本文は、コンテンツタイプapplication/jsonのPOSTリクエストとして送信する場合に入力します。 |
contact
| Cookieに紐付けられたコンタクトから送信されたリクエストの場合、基本的なコンタクトプロパティーが含まれたコンタクトオブジェクトになります。また、以下のプロパティーも使用できます。
|
headers
| エンドポイントに対してクライアントから送信されたヘッダーが含まれます。ヘッダーを参照してください。 |
params
| paramsには、クエリー文字列値、およびHTMLフォームによるPOST値(存在する場合)が入ります。文字列によるキーと、文字列の配列による値から成るマップとして構成されます。 |
limits
| サーバーレス関数のレート制限にどの程度近づいているかを返します。
|
エンドポイントに対するクライアントからのヘッダーがあると、役立つ場合があります。context.header
では以下のヘッダーを提供しています。これは、context.body
による情報の取得と同様です。
ヘッダー | Description |
---|---|
accept
| |
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
を含むレスポンスを送信することで、サーバーレス関数からリダイレクトを実行できます。
複数の値をサポートするヘッダーには、multiValueHeaders
を使用して値を渡すことができます。例えば、ブラウザーに複数のCookieを設定することを指示できます。
APIキーおよび認証情報はシークレットと呼ばれます。一度追加されると、環境変数(process.env.secretName)としてアクセス可能になります。serverless.json
ファイルにsecretsキーを追加することで、特定のエンドポイント用のシークレットを割り当てることができます。シークレットの管理には、HubSpot CLIで以下のコマンドを使用します。
コンソールログを使用して、またはレスポンスとしてシークレットの値を返さないでください。ログやサーバーレス関数を呼び出すフロントエンドページでシークレットが漏洩するおそれがあるためです。
CORS(オリジン間リソース共有)はブラウザーのセキュリティー機能です。ブラウザーでは既定で、JavaScriptによって開始されたクロスオリジンリクエストが制限されます。これにより、異なるドメイン間で有害コードが実行され、貴社のサイトに影響を与えることを防止します。これは同一オリジンポリシーと呼ばれます。他のサーバーとのデータの送受信が必要な場合には、ブラウザーからの情報の読み取りをどのオリジン(発信元)に許可するかを示すHTTPヘッダーが外部サーバーから提供されることがあります。
HubSpot内にホスティングされたページでのサーバーレス関数の呼び出しにおいては、CORSの問題は発生しません。発生する場合、正しいプロトコルを使用していることを確認してください。
次のCORSエラーが発生している場合
「発信元[リクエスト元ページ]から[関数URL]へのフェッチ(取得)アクセスが、CORSポリシーによってブロックされました:プリフライトリクエストへのレスポンスが、アクセス制御検査に合格しません:要求されたリソースにはAccess-Control-Allow-Originヘッダーがありません。複雑なレスポンスを使用する場合は、リクエストのモードをno-corsに設定して、CORSが無効化されたリソースを取得してください。」
呼び出し元サイトとは異なるオリジンへのリクエストとは?
- ドメイン名が異なる場合は、該当します。
- 使用しているプロトコル(http、https)が異なる場合は、該当します。
使用しているプロトコルが異なる場合は、プロトコルを合わせて変更するだけで解決します。
現時点では、HubSpotのAccess-Control-Allow-Origin
ヘッダーを変更することはできません。
現在、HubSpotのサーバーレス関数には、以下の事前読み込みパッケージがあります。
- @hubspot/api-client:1.0.0-beta以降
- axios:0.19.2以降
- request:2.88.0以降
- requests:0.2.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
のレスポンスが返されます。各関数の実行時間は、サーバーレス関数ログに記録されます。
上記の制限を回避できるよう、実行中に自動で制限データが関数コンテキストに提供されます。その情報に基づいて、アプリケーションを制限内にとどめるような調整を行うことができます。例えばアプリケーションからエンドポイントへのポーリングが必要な場合、ポーリング頻度を調整するための変数をデータと共に返すことができます。これにより、トラフィックの増大時にも制限に到達しないようにポーリング速度を抑え、トラフィックの減少後に元に戻すことが可能になります。
貴重なご意見をありがとうございました。