HubSpotのサーバーレス関数：はじめに

APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

サーバーレス関数を使用すると、HubSpotやサードパーティーのサービスをAPI経由で操作できるサーバーサイドコードを作成できます。認証が必要なAPIでは資格情報が表示されるため、ウェブサイトのフロントエンドでの使用には適していません。

 サーバーレス関数は、認証を必要とするフロントエンドサービスとバックエンドサービスの間で仲介処理として機能します。サーバーレス関数を使用する場合、開発者が新たにサーバーを構築、管理する必要がありません。サーバーレス関数はオーバーヘッド（間接的な負荷）が小さいため、ビジネスの成長に合わせて拡大することも容易です。このチュートリアルを実施する前に、HubSpotのサーバーレス関数とその概要を参照しておいてください。

このチュートリアルでは、初めてサーバーレス関数を作成する際の流れを説明します。

サーバーレス関数フォルダーの作成から、設定フォルダーの設定、関数の作成、レスポンスの取得までを行います。

このチュートリアルの前に必要な作業

1. プロジェクトフォルダーを作成する

hubspot.config.ymlファイルを開き、defaultPortalがCMS開発者用サンドボックスアカウントか、CMS Hub Enterpriseのアカウントのいずれかに設定されていることを確かめます。

自分のコンピューターのhubspot.config.ymlファイルが含まれるフォルダーの中に、serverless-tutorialフォルダーを作成します。このフォルダーに、関数自体とその関数を使用するテンプレートの両方を含む全てのファイルを格納します。 

ターミナルで、watchコマンドを実行します。

hs watch serverless-tutorial serverless-tutorial

以降、このフォルダーで何らかの編集を行うと、デザインマネージャーにアップロードされます。現在このフォルダーには中身がないため、このコマンドは単に、Watcherの準備ができていて監視中であることを示すだけです。

2. 関数フォルダーを作成する

serverless-tutorialフォルダーの内部に、my-first-function.functionsフォルダーを作成します。
末尾が.moduleのカスタム モジュール フォルダーと同様に、.functionsはフォルダーにサーバーレス関数が含まれることを示します。このフォルダーに格納されているファイルは公開されません。

このフォルダーは現在空なので、実行中のwatchコマンドでは、デザインマネージャーの中にこのフォルダーがまだ作成されません。

3. 設定ファイルを作成する

my-first-function.functionsフォルダーにserverless.jsonという名前の新しいファイルを作成します。serverless.jsonは.functionsフォルダー内の必須ファイルです。これはサーバーレス関数の設定ファイルとして機能します。ランタイム環境、サーバーレス関数のバージョン、利用可能なエンドポイントを定義します。このファイルの詳細な定義については、サーバーレスリファレンスを参照してください。

空のファイルを作成して保存した場合、空のserverless.jsonファイルはアップロードできないというエラーメッセージがターミナルに表示されます。これは無視しても問題ありません。以下のコードを追加して保存すれば、新たなアップロードが起動されて正常に完了するためです。

以下のコードをserverless.jsonに貼り付けます。

// place this in your serverless.json file, without this comment { "runtime": "nodejs12.x", "version": "1.0", "endpoints": { } }

ファイルを保存します。

このファイルはコードエディター上に開いたままにします。後で再度使用します。

watchを実行中なので、デザインマネージャーを再読み込みすると、serverless-tutorialとmy-first-function.functionsの各フォルダーと、新しいserverless.jsonファイルが表示されます。 

4. 関数ファイルを作成する

my-first-function.functionsフォルダーにcongratulation.jsという名前の新しいファイルを作成します。

これが、タスクを処理する実行可能な関数ファイルの本体です。

以下のコードを貼り付けます。

exports.main = (context, sendResponse) => { // your code called when the function is executed const functionResponse = "Congrats! You've just deployed a Serverless Function." // sendResponse is a callback function you call to send your response. sendResponse({body: functionResponse, statusCode: 200}); };

このサーバーレス関数を実行すると、"Congrats!You just deployed a Serverless Function."（サーバーレス関数がデプロイされました）という文字列と、成功を示すステータスコード200が返されます。

実際には、APIを使用したり、非公開の計算を実行したりするケースが考えられます。こうした計算結果を返すか、APIトランザクションの成否に基づくシンプルなステータスコードを返すことになります。

まだ終了ではありません。この関数を実行する方法がまだありません。

5. serverless.json内に関数を登録する

もう一度serverless.jsonファイルを開きます。このファイル内のendpointsオブジェクトを検索します。

このオブジェクトを次のように変更します。

// update the endpoints object in your serverless.json to reflect this object. "endpoints": { "congratulation": { "method": "GET", "file": "congratulation.js" } }

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パラメーターを使用して定義します。関数によってサポートされるメソッドを示す単一の文字列か、文字列の配列です。

6. 関数をテストする

サーバーレス関数に対するGETリクエストをテストする最も簡単な方法は、ブラウザーで直接エンドポイントのURLにアクセスすることです。
https://your-domain.com/_hcms/api/congratulation

your-domain.comは、実際のHubSpotサイトのドメインで置き換えます。

次のように表示されます："Congrats!You just deployed a serverless function"（サーバーレス関数がデプロイされました）。

正常に完了しました。

このレスポンスがない場合は、チュートリアルの最初から各ステップを確かめるとともに、コードを確認してください。ステップ4または5の手順が正しく行われなかったことが考えられます。

複雑なリクエストの場合は、Postmanなどのツールを使用すると役に立ちます。Postmanを利用すると、APIのテストとデバッグが簡単になります。フロントエンド開発者にとっては、コード生成が便利で、JavaScriptからの関数呼び出しの出発点として利用できます。

7. 関数を呼び出す基本的なテンプレートを作成する

新しいターミナルウィンドウを開き、cdを使用してserverless-tutorialフォルダーに切り替えます。

ターミナルで次のコマンドを実行します。

hs create template "test-function"

これにより、test-function.htmlファイルが作成されます。コードエディターでこのファイルを開きます。

</head>タグの上に<script></script>を追加します。

以下のJavaScriptをコピーします。

var requestOptions = { 'method': 'GET', 'headers': { 'Content-Type': 'application/json', } }; fetch("https://www.example.com/_hcms/api/congratulation", requestOptions) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log('error', error));

HubSpotサーバーレス関数でサポートされるコンテンツタイプは、application/jsonのみです。これを省略すると、「サポートされていないメディアタイプ」のエラーになります。

前の手順で作成したスクリプトタグ内に、コピーしたJavaScriptコードを貼り付けます。

www.example.comを実際のアカウントのドメインに変更します。

ファイルを保存します。

8. test-function.htmlテンプレートを使用してページを作成する

デザインマネージャーでtest-function.htmlファイルを見つけます（場合によっては再読み込みが必要）。

ファイルを右クリックし、［ページを作成］を選択します。

ページに「Test Function」と名前を付けます。ページを作成します。

プレビューをクリックし、新しいウィンドウでプレビューします。 

ページ上で右クリックしてから、［検査］を選択することによって、ページの検査を実行します。

全ての手順を正しく行った場合は、正常にメッセージが表示されます。

Congratulations, you've called your serverless function from within a HubSpot CMS page.（HubSpotのCMSページ内からサーバーレス関数が呼び出されました。） 

このチュートリアルでは、テンプレート上でサーバーレス関数を呼び出していますが、サーバーレス関数は、CMS上のサイトでJavaScriptを追加できるどのような場所からでも呼び出すことが可能です。最も一般的な場所は、カスタムモジュール内です。

サーバーレス関数のデバッグ

この段階で、サーバーレス関数が正常に動作しているはずです。関数が複雑化すると、トラブルシューティングは困難になります。ブラウザー内のコンソールがフロントエンドでのJavaScriptのデバッグに役立つように、hsログではサーバーレス関数に関する同様のログを取得できます。このコマンドの詳細については、ローカル開発のリファレンスをご覧ください。

hs logs <endpoint-name> --follow

ここまでに実行したこと

サーバーレス関数フォルダーとserverless.jsonの設定ファイル、さらにcongratulation.jsという名前の関数ファイルを作成しました。GETを使用して、サーバーレス関数から正常な呼び出し完了のテキストを取得しました。JavaScriptを使用することにより、HubSpotのCMSからサーバーレス関数を呼び出しました。

設定ファイル、関数ファイル、.functionsフォルダーの関係性を理解できたので、以降は便利なCLIを使用して、短時間で関数を作成できるようになります。

hs create function <function name>

この関数では、.functionsフォルダー、serverless.jsonファイルおよび指定した名前の関数ファイルが作成されます。

次のステップ

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