カスタム コード ワークフロー アクション
ワークフローでは、「カスタムコード」アクションを使用して、JavaScriptまたはPython(「ベータ版」)を作成し、実行します。カスタム コード アクションを使用すると、HubSpot内でもHubSpot外でもワークフロー機能を拡張できます。HubSpotのAPIについて詳しくは、最新バージョンを対象とした開発者ドキュメント(英語)または古いAPIを対象とした以前の開発者ドキュメント(英語)をご確認ください。一般的なカスタム コード アクションの例は、HubSpotのプログラマブルオートメーションのユースケースで確認できます。
カスタム コード アクションでは、JavaScriptをサポートするためにNode 16.xランタイムフレームワークが使用されます。カスタム コード アクションにPythonを使用する場合、カスタム コード アクションではPython 3.9ランタイムフレームワークが使用されます。アクションが実行されると、HubSpotとAWS Lambdaによるサーバーレス機能によって、ランタイム計算が管理されます。
カスタム コード アクションの実装で一般的な問題が発生した場合は、HubSpotのヘルプをご利用ください。ただし、自分で記述したカスタムコードで問題が発生した場合は、HubSpot開発者フォーラムで問題について検索、投稿して、コードのトラブルシューティングに関するヒント、アドバイス、サポートを受けることをお勧めします。
Node.js対応ライブラリー
Node.jsを使用する場合、コードアクション内で次のライブラリーを使用できます。これらのライブラリーを読み込むには、コードの先頭で通常のrequire()
関数を使用します。
- @hubspot/api-client ^8
- async ^3.2.0
- aws-sdk ^2.744.0
- axios ^1.2.0
- lodash ^4.17.20
- mongoose ^6.8.0
- mysql ^2.18.1
- redis" ^4.5.1
- request" ^2.88.2
- bluebird ^3.7.2
- random-number-csprng ^1.0.2
- googleapis ^67.0.0
Python対応ライブラリー
Pythonを使用する場合、コードの先頭でimportステートメントを使用して、次のライブラリーを読み込むことができます。importステートメントは、from [libraryname] import [item]
の形式にする必要があります(例:from redis.client import redis
)。
- requests 2.28.2
- @hubspot/api-client ^7
- google-api-python-client 2.74.0
- mysql-connector-python 8.0.32
- redis 4.4.2
- nltk 3.8.1
標準ライブラリーから何らかの要素を取り込んで使用する場合は、import
を使用できます(例:import os
)。
Get started
カスタム コード ワークフロー アクションを使用するには、以下のサンプルコードを使用します。
Code samples
カスタム コード アクションをワークフローに追加するには、次の手順に従ってください。
- HubSpotアカウントで、[自動化]>[ワークフロー]に移動します。
- ワークフローの名前をクリックするか、新しいワークフローを作成します。
- +(プラス)アイコンをクリックし、ワークフローアクションを追加します。
- 右側のパネルで[カスタムコード]を選択します。
- 右側のパネルで、プロパティーを設定します。
- デフォルトでは、カスタム コード アクションはNode.js 16.xを使用します。Pythonベータ版でPythonを使ってアクションを作成する場合は、[言語]ドロップダウンメニューをクリックし、[Python]を選択します。
- 新しいシークレット(非公開アプリのアクセストークンなど)を追加するには、[シークレットを追加]をクリックします。アプリには、
contacts
やforms
など、HubSpotから取得しようとしているデータのスコープを含める必要があります。詳しくは、HubSpotの非公開アプリに関するぺージをご確認ください。 - ダイアログボックスで、[シークレット名]と[シークレット値]に値を入力します。
- [保存]をクリックします。これで、以降のカスタム コード アクションでこのシークレットを選択できるようになります。
- 既存のシークレットを編集または削除する場合は、[シークレットを管理]をクリックします。
- カスタムコードにプロパティーを含めるには、[プロパティーを選択]ドロップダウンメニューをクリックし、プロパティーを選択します。ワークフローでは、既存のプロパティーまたは以前に書式設定されたプロパティー値を使用できます。プロパティーを選択したら、コード内で使用するプロパティー名を入力します。こちらで、カスタムコードでプロパティーを参照する方法をご確認いただけます。
- 別のプロパティーを追加するには、[プロパティーを追加]をクリックします。各プロパティーは1回のみ追加できます。また、プロパティーには一意の「変数ID」が割り当てられている必要があります。カスタムコードでは最大50個のプロパティーを使用できます。
- プロパティーを削除するには、削除アイコンをクリックします。
- コードフィールドにJavaScriptまたはPythonを入力します。
- 例えば[プロパティー値をコピー]アクションなどで、後にワークフローにて入力として使用できるデータ出力を定義するには、次のようにします。
- [データ出力]で、[データタイプ]ドロップダウンメニューをクリックし、データのタイプを選択します。
- [名前]フィールドに、データ出力の名前を入力します。
- 複数の出力を追加する場合は、[出力を追加]をクリックします。
- [保存]をクリックします。
注:Pythonを使用している場合、コードフィールドにリントエラーは表示されません。
カスタム コード アクションを作成する際は、次の点に留意してください。
- コードスニペットのアクションが実行されると、
def main(event):
関数が呼び出されます。
- event引数は、ワークフロー実行の詳細を含むオブジェクトです。
- ワークフローにデータを返すには、
callback()
関数を使用します。この関数は、exports.main
関数内で呼び出す必要があります。これは、Node.jsでのみ使用できます。
event
オブジェクトには、以下のデータが格納されます。
アクションのテストを行う
ワークフローにカスタム コード アクションを追加する際は、ワークフローを有効にする前に、コードが想定どおりに実行されることを確認するために、アクションのテストが行えます。
カスタム コード アクションをテストするには、まず、コードのテストで使用するレコードを選択してから、コードを実行します。このテストでは、カスタムアクションのコードのみが実行され、ワークフローの他のアクションは実行されません。コードの実行が完了したら、コードの出力とテストのログを表示できます。
注:カスタムコードをテストすると、コードが実行され、選択したテストレコードにあらゆる変更が適用されます。ライブレコードの更新を避けたい場合は、テスト専用のレコードを作成することをお勧めします。
カスタム コード アクションをテストするには、以下の手順に従ってください。
- ワークフローのタイムラインで、カスタム コード アクションをクリックします。
- 右のサイドバーの下部にある[テストアクション]をクリックしてテストセクションを展開します。
- コードのテストで使用するレコードを選択するには、[オブジェクト]ドロップダウンメニューをクリックし、レコードを選択します。
- ワークフローで過去に書式設定されたプロパティー値を使用する場合は、書式設定されたデータのテスト値を入力します。
- コードを実行するには、[テスト]をクリックします。
- 表示されるダイアログボックスで、[テスト]をクリックして、選択したレコードに対してコードをテストすることを確認します。
- コードの実行が完了すると、サイドバーにテスト結果が表示されます。
- ステータス:カスタム コード アクションの成功または失敗のステータス。
- データ出力:定義されたデータ出力に対して得られた値。コードによって生成された、[データ出力]セクションでもコードエディターでも定義されていない出力の横にはアラートが表示されます。ワークフローで後で使用するには、これらの出力を追加する必要があります。
- ログ:テスト自体に関する情報(アクションで使用されたメモリーの量、合計実行時間など)。
- カスタム コード アクションを更新するには、[アクションを作成]をクリックしてアクションエディターを展開します。必要に応じてコードの更新とテストを続けます。
- アクションのテストが完了したら、[保存]をクリックして変更を保存します。
広く共有すべきではないものをコードに参照させなければならないこともあります。これは多くの場合、非公開アプリのアクセストークンなどの認証手段です。ワークフローアクションの定義で直接、関数がアクセスするシークレットを管理できます。カスタムコード内で複数のシークレットを使用する場合、全てのシークレット値の合計長は1,000文字以下でなければなりません。
追加されたシークレットは環境変数として使用可能になり、以下に示すように、カスタムコードでその環境変数にアクセスできます。
場合によって、カスタム コード アクションでオブジェクトのプロパティーを取得しなければならないことがあります。その際にはHubSpotのAPIを使用する代わりに、必要なオブジェクトのプロパティーをワークフローアクション定義に直接追加できます。プロパティーを追加して、コード内でプロパティーを参照するためのプロパティー名を設定します。カスタム コード アクションごとに最大50個のプロパティーの追加が可能です。
プロパティーを追加すると、カスタムコードで参照できるようになります。
ログ
開発者にとって重要なツールは、コードによる結果を出力する機能です。問題をデバッグし、エンドユーザーへのサポートを改善するのに役立ちます。ログの出力を確認するには、ワークフローの[履歴]タブでログを表示します。

How to Define Outputs
ワークフローの後半で使用する出力フィールドを関数で定義します。次に、右側のサイドバーで、出力するデータの型(数値、文字列、ブール値、日時、列挙、日付、電話番号など)を選択し、出力するフィールドを入力します。
出力フィールドは、使用されている言語に応じて書式設定された、JSONオブジェクトの一部にする必要があります。

コードアクションからの出力は、[プロパティー値をコピー]アクションへの入力として使用できます。これにより、値をオブジェクトのプロパティーとして保存するために別のAPI呼び出しを行う必要がなくなります。
出力を定義する際は、以下の点に留意してください。
- 出力するデータの型が文字列形式の場合、文字列の出力値の上限は65,000文字です。この制限を超えると、
OUTPUT_VALUES_TOO_LARGE
エラーが発生します。 - [プロパティー値をコピー]アクションを使用する場合は、対応するソースプロパティーとターゲットプロパティーがあることにも注意してください。
- また、日時型プロパティーに出力をコピーする場合、出力はUNIXミリ秒形式でなければならないことにも注意してください。

Limitations
カスタム コード アクションは20秒以内に実行を完了する必要があり、使用できるメモリーは最大128 MBです。これらの制限に違反すると、エラーが発生します。
Retries
HubSpot APIを使用してオブジェクトのプロパティーを取得するか、カスタム コード アクションで別のHubSpot APIエンドポイントを呼び出す必要がある場合があります。他のAPI呼び出しと同様に、HubSpot APIのレート制限に従う必要があります。
- Node.jsを使用している場合、レート制限エラーが発生してもHubSpotに呼び出しを再試行させるには、カスタム コード アクションの
catch
ブロックでエラーをスローする必要があります。
- Pythonを使用している場合、レート制限エラーが発生してもHubSpotに呼び出しを再試行させるには、カスタム コード アクションの
except
ブロックでエラーを報告する必要があります。
注:レート制限エラー、またはaxiosあるいは@hubspot/api-clientからの429もしくは5XXエラーによりリクエストが失敗すると、HubSpotはエラー発生の1分後から最大3日間、そのアクションを再試行します。その後の失敗は、徐々に間隔を延ばして再試行されます。再試行の間隔は最大で8時間です。
Caveats
- 乱数の生成:乱数を生成するにはMath.random(英語)を使用するのが一般的ですが、異なる実行で同じ数値が生成される場合があります。これは、Math.randomは現在の時刻でシードされるためです。HubSpotは、多数のオブジェクトを同時にワークフローに登録し、実行ごとに状態をクリアするため、異なる実行でMath.randomへのシードが同じように行われる結果になります。代わりに、random-number-csprng 1.0.2ライブラリー(英語)を使用すると、暗号論的疑似乱数の生成が保証されます。
- 変数の再利用:メモリーを節約するには、
exports.main
関数の外部で宣言した変数を、カスタム コード アクションの以降の実行で再利用できます。これは、データベースなどの外部サービスに接続する場合に便利ですが、カスタム コード アクションの実行ごとに一意でなければならないロジックや情報は、exports.main
関数に含める必要があります。
カスタムコードにPythonを使用している場合は、次の注意事項に留意してください。
- 変数の再利用:上記と同様に、
def main
関数の外部で宣言した変数は、カスタム コード アクションの以降の実行で再利用できます。def main
関数の外部で変数を宣言した場合、その変数に対するアラートを計画していないとしても、変数を直接参照できます。- 変数のアラートを計画する場合、その変数を参照する前にグローバルキーワードを使用した
def main
関数内で変数を宣言できます。
貴重なご意見をありがとうございました。