HubSpotのサーバーレス関数:はじめに
CMS Hub
- Enterprise
サーバーレス関数を使用すると、HubSpotやサードパーティーのサービスをAPI経由で操作できるサーバーサイドコードを作成できます。認証が必要なAPIでは資格情報が表示されるため、ウェブサイトのフロントエンドでの使用には適していません。
サーバーレス関数は、認証を必要とするフロントエンドサービスとバックエンドサービスの間で仲介処理として機能します。サーバーレス関数を使用する場合、開発者が新たにサーバーを構築、管理する必要がありません。サーバーレス関数はオーバーヘッド(間接的な負荷)が小さいため、ビジネスの成長に合わせて拡大することも容易です。このチュートリアルを実施する前に、HubSpotのサーバーレス関数とその概要を参照しておいてください。
このチュートリアルでは、初めてサーバーレス関数を作成する際の流れを説明します。
サーバーレス関数フォルダーの作成から、設定フォルダーの設定、関数の作成、レスポンスの取得までを行います。
このチュートリアルの前に必要な作業
- CMS Hub EnterpriseアカウントまたはCMS開発者用サンドボックスアカウントへのアクセス。
- サーバーレス関数の概念に関する、少なくとも基本的な理解。
- サーバーレス関数との連携に必要なHubSpotローカル開発ツールの使用経験。
- HubSpotローカル開発ツールの最新バージョン。
- 自分のHubSpotアカウントによって認証されたローカル開発ツール。
hubspot.config.yml
ファイルを開き、defaultPortal
がCMS開発者用サンドボックスアカウントか、CMS Hub Enterpriseのアカウントのいずれかに設定されていることを確かめます。
自分のコンピューターのhubspot.config.yml
ファイルが含まれるフォルダーの中に、serverless-tutorial
フォルダーを作成します。このフォルダーに、関数自体とその関数を使用するテンプレートの両方を含む全てのファイルを格納します。
ターミナルで、watchコマンドを実行します。
以降、このフォルダーで何らかの編集を行うと、デザインマネージャーにアップロードされます。現在このフォルダーには中身がないため、このコマンドは単に、Watcherの準備ができていて監視中であることを示すだけです。
serverless-tutorial
フォルダーの内部に、my-first-function.functions
フォルダーを作成します。
末尾が.module
のカスタム モジュール フォルダーと同様に、.functions
はフォルダーにサーバーレス関数が含まれることを示します。このフォルダーに格納されているファイルは公開されません。
このフォルダーは現在空なので、実行中のwatch
コマンドでは、デザインマネージャーの中にこのフォルダーがまだ作成されません。
my-first-function.functions
フォルダーにserverless.json
という名前の新しいファイルを作成します。serverless.json
は.functions
フォルダー内の必須ファイルです。これはサーバーレス関数の設定ファイルとして機能します。ランタイム環境、サーバーレス関数のバージョン、利用可能なエンドポイントを定義します。このファイルの詳細な定義については、サーバーレスリファレンスを参照してください。
空のファイルを作成して保存した場合、空のserverless.json
ファイルはアップロードできないというエラーメッセージがターミナルに表示されます。これは無視しても問題ありません。以下のコードを追加して保存すれば、新たなアップロードが起動されて正常に完了するためです。
以下のコードをserverless.jsonに貼り付けます。
ファイルを保存します。
このファイルはコードエディター上に開いたままにします。後で再度使用します。
watch
を実行中なので、デザインマネージャーを再読み込みすると、serverless-tutorial
とmy-first-function.functions
の各フォルダーと、新しいserverless.json
ファイルが表示されます。
my-first-function.functionsフォルダーにcongratulation.jsという名前の新しいファイルを作成します。
これが、タスクを処理する実行可能な関数ファイルの本体です。
以下のコードを貼り付けます。
このサーバーレス関数を実行すると、"Congrats!You just deployed a Serverless Function."
(サーバーレス関数がデプロイされました)という文字列と、成功を示すステータスコード200
が返されます。
実際には、APIを使用したり、非公開の計算を実行したりするケースが考えられます。こうした計算結果を返すか、APIトランザクションの成否に基づくシンプルなステータスコードを返すことになります。
まだ終了ではありません。この関数を実行する方法がまだありません。
もう一度serverless.json
ファイルを開きます。このファイル内のendpoints
オブジェクトを検索します。
このオブジェクトを次のように変更します。
endointsオブジェクトにはcongratulation
オブジェクトが含まれています。congratulation
が、今作成しているエンドポイントです。サーバーレス関数を呼び出すために使用するパスは、エンドポイントの名前によって定義されます。
サーバーレス関数は、HubSpot CMSアカウントのドメインのパスを通して公開されます。
この関数には、次のようにアクセスできます。
<https://www.example.com>/_hcms/api/<endpoint-name/path>
今回作成したcongratulationエンドポイントの場合は次のようになります。
<https://www.example.com>/_hcms/api/congratulation
このため、エンドポイントには通常、関数ファイルの名前と同じように名前を付けることが適切です。両方に、その情報に対して実行される処理ではなく、処理の対象となる情報に基づいて名前を付けるようにしてください。その情報に対して実行する処理タイプを伝送するHTTPメソッドを使用してください。関数によってサポートするHTTPメソッドは、methodパラメーターを使用して定義します。関数によってサポートされるメソッドを示す単一の文字列か、文字列の配列です。
サーバーレス関数に対するGET
リクエストをテストする最も簡単な方法は、ブラウザーで直接エンドポイントのURLにアクセスすることです。
https://your-domain.com/_hcms/api/congratulation
your-domain.comは、実際のHubSpotサイトのドメインで置き換えます。
次のように表示されます:"Congrats!You just deployed a serverless function"
(サーバーレス関数がデプロイされました)。
正常に完了しました。
このレスポンスがない場合は、チュートリアルの最初から各ステップを確かめるとともに、コードを確認してください。ステップ4または5の手順が正しく行われなかったことが考えられます。
新しいターミナルウィンドウを開き、cd
を使用してserverless-tutorial
フォルダーに切り替えます。
ターミナルで次のコマンドを実行します。
これにより、test-function.html
ファイルが作成されます。コードエディターでこのファイルを開きます。
</head>
タグの上に<script></script>
を追加します。
以下のJavaScriptをコピーします。
HubSpotサーバーレス関数でサポートされるコンテンツタイプは、application/json
のみです。これを省略すると、「サポートされていないメディアタイプ」のエラーになります。
前の手順で作成したスクリプトタグ内に、コピーしたJavaScriptコードを貼り付けます。
www.example.com
を実際のアカウントのドメインに変更します。
ファイルを保存します。
デザインマネージャーでtest-function.html
ファイルを見つけます(場合によっては再読み込みが必要)。
ファイルを右クリックし、[ページを作成]を選択します。
ページに「Test Function」と名前を付けます。ページを作成します。
プレビューをクリックし、新しいウィンドウでプレビューします。
ページ上で右クリックしてから、[検査]を選択することによって、ページの検査を実行します。
全ての手順を正しく行った場合は、正常にメッセージが表示されます。
Congratulations, you've called your serverless function from within a HubSpot CMS page.(HubSpotのCMSページ内からサーバーレス関数が呼び出されました。)
このチュートリアルでは、テンプレート上でサーバーレス関数を呼び出していますが、サーバーレス関数は、CMS上のサイトでJavaScriptを追加できるどのような場所からでも呼び出すことが可能です。最も一般的な場所は、カスタムモジュール内です。
この段階で、サーバーレス関数が正常に動作しているはずです。関数が複雑化すると、トラブルシューティングは困難になります。ブラウザー内のコンソールがフロントエンドでのJavaScriptのデバッグに役立つように、hsログ
ではサーバーレス関数に関する同様のログを取得できます。このコマンドの詳細については、ローカル開発のリファレンスをご覧ください。
ここまでに実行したこと
サーバーレス関数フォルダーとserverless.jsonの設定ファイル、さらにcongratulation.js
という名前の関数ファイルを作成しました。GETを使用して、サーバーレス関数から正常な呼び出し完了のテキストを取得しました。JavaScriptを使用することにより、HubSpotのCMSからサーバーレス関数を呼び出しました。
設定ファイル、関数ファイル、.functions
フォルダーの関係性を理解できたので、以降は便利なCLIを使用して、短時間で関数を作成できるようになります。
この関数では、.functions
フォルダー、serverless.json
ファイルおよび指定した名前の関数ファイルが作成されます。
- HubSpot CMSのサーバーレス関数の概要。
- サーバーレス関数のさまざまな部分に関するサーバーレスリファレンス
- HubSpot APIの概要に関するアカデミーコース(英語)。
- GitHubでのCI(継続的インテグレーション)
貴重なご意見をありがとうございました。