プロパティー

プロパティーは、CRMレコードに情報を格納するために使用します。HubSpotでは、CRMオブジェクトごとに既定のプロパティーのセットが用意されています。HubSpot上で、またはプロパティーAPIを使用して、独自のカスタムプロパティーを作成および管理することもできます。 

プロパティーを作成する際には、データの構築方法を考慮することが重要です。多くの場合、HubSpotの標準オブジェクト上にカスタムプロパティーを作成することで適切に対応できます。しかし場合によっては、独自のプロパティーを備えたカスタムオブジェクトを別途作成することが必要になります。

既定のプロパティー

CRMオブジェクトは、主な「タイプ」と「プロパティー」によって定義されます。タイプごとに標準のプロパティーがあり、名前と値のペアで表されます。 

オブジェクトごとの既定のプロパティーをご覧ください。

プロパティーグループ

プロパティーグループは、関連する複数のプロパティーをグループ化するために使用します。グループ化されたプロパティーは各HubSpotレコード上に隣接して表示されます。カスタムプロパティーを作成して連携を行う場合は、カスタムプロパティーのグループを活用することでデータの特定が容易になります。

プロパティーのtypeとfieldTypeの値

プロパティーの作成または更新の際には、typefieldTypeの両方の値が必要です。typeの値により、プロパティーの型、つまり文字列か数値かが決まります。fieldTypeプロパティーによって、プレーンテキストフィールド、ドロップダウンメニュー、日付入力など、HubSpotでのプロパティーの表示形式が決まります。

以下の表に、プロパティーの使用可能なtypeと、それに対応するfieldTypeの値を示します。

typeフィールドの有効な値と、それに対応するfieldTypeの値
type 説明 有効なfieldTypeの値
bool バイナリーオプション(YesまたはNoTrueまたはFalseなど)を格納するフィールド。 booleancheckboxcalculation_equation
enumeration 一連のオプションを表す文字列。各オプションはセミコロンで区切ります。 booleancheckbox, checkbox, radio, select, calculation_equation
date 特定の年、月、日を表す値。値はUTC時間で表す必要があります。値の形式は、ISO 8601文字列またはミリ秒単位のエポック時間のタイムスタンプ(UTC深夜0時)にできます。 date
dateTime 特定の年、月、日、時刻を表す値。HubSpotアプリ上には時刻は表示されません。値はUTC時間で表す必要があります。値の形式は、ISO 8601文字列またはUNIXタイムスタンプ(ミリ秒単位)にできます。 date
string プレーンテキスト文字列。文字数の上限は65,536文字です。 filetexttextareacalculation_equationhtmlphonenumber
number 数値。小数第1位まで。 numbercalculation_equation

有効なfieldTypeの値

FieldtypeDescription
booleancheckbox

ユーザーが「はい」または「いいえ」のいずれかを選択できる入力。フォーム内で使用する場合、1つのチェックボックスとして表示されます。単一チェックボックスプロパティーに値を追加する方法についてご覧ください。

calculation_equation

他のプロパティー値や関連付けに基づいて値を計算できるカスタム式。計算プロパティーを定義する方法についてご覧ください。

checkbox

プロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。複数チェックボックスプロパティーの更新時に値を書式設定する方法についてご覧ください。

date

日付値。日付入力として表示されます。

file

ファイルのフォームへのアップロードが可能。ファイルへのURLリンクとして格納および表示されます。

html

サニタイズ(エスケープ)されたHTMLとしてレンダリングされる文字列。プロパティーに対するリッチ テキスト エディターの使用が可能になります。

number

一連の数字。10進数または指数表記として記述。

phonenumber

書式設定された電話番号として表示されるプレーンテキスト文字列。

radio

プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。

select

プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。

text

プレーンテキスト文字列。単行テキスト入力として表示されます。

textarea

プレーンテキスト文字列。複数行テキスト入力として表示されます。

一意識別子プロパティーを作成する

HubSpotでレコードが作成されると、一意の「レコードID」(hs_object_id)が自動生成され、それが文字列として扱われます。これらのIDはそのオブジェクト内でのみ一意です。したがって、コンタクトと会社のIDが同じになる場合があります。コンタクトと会社の場合、コンタクトの電子メールアドレス(email)や会社のドメイン名(domain)など、他にも一意の識別子があります。

場合によっては、複数のレコードで同じ値を入力できないように、独自の一意識別子プロパティーを作成するのが適切なことがあります。一意のIDプロパティーは、オブジェクトあたり最大10個まで作成できます。APIを介して一意の値を必要とするプロパティーを作成するには:

  • /crm/v3/properties/{objectType}POSTリクエストを送信します。
  • リクエスト本文で、hasUniqueValueフィールドの値をtrueに設定します。
/// Example request body { "groupName": "dealinformation", "name":"system_a_unique", "label": "Unique ID for System A", "hasUniqueValue": true, "type": "string", "fieldType": "text" }

一意IDプロパティーを作成したら、API呼び出しでそれを使用して、特定のレコードを取得することができます。リクエストURLは例えば次のようになります。GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_uniqueこれにより、system_a_uniqueフィールドの値がabcである取引が返されます。

その後、この一意識別子プロパティー値を使用すると、hs_object_idemail(コンタクト)、またはdomain(会社)を使用するのと同じ方法で、特定のレコードを識別および更新できます。

計算プロパティーの作成

計算プロパティーは、同じオブジェクトレコード内の他のプロパティーに基づいてプロパティー値を定義します。計算プロパティーを定義するには、最小値、最大値、件数、合計、平均などを求める演算を含めた式を使用します。プロパティーAPIを使用すると、フィールドタイプとしてcalculation_equation、データ型としてnumberboolstring、またはenumerationを使用して、HubSpotアカウントで計算プロパティーを読み取ったり作成したりできます。

プロパティーの計算式は、calculationFormulaフィールドを使用して定義できます。

:APIを介して作成された計算プロパティーをHubSpot内で編集することはできません。これらのプロパティーは、プロパティーAPIを介してのみ編集できます。

計算プロパティー構文

calculationFormulaを使用すると、算術演算子、比較演算子、論理演算子、条件文、およびその他の関数を使用して式を記述できます。

リテラル構文

  • 文字列リテラル:定数列は、単一引用符('constant')または二重引用符("constant")のいずれかを使用して表現できます。
  • 数値リテラル:定数は任意の実数にできます。小数点表現を含めることもできます。10051.5589は、どちらも有効な定数です。
  • ブール値リテラル:ブール型定数はtrueまたはfalseにできます。

プロパティー構文

  • 文字列プロパティー変数:識別文字列を文字列プロパティーとして解釈させるには、string関数でラップする必要があります。例えば、string(var1)は文字列プロパティーvar1として解釈されます。
  • 数値プロパティー変数:全ての識別子は数値プロパティー変数として解釈されます。例えば、var1は数値プロパティーvar1の値として解釈されます。
  • ブール型プロパティー変数:識別子をブール型プロパティーとして解釈させるには、bool関数でラップする必要があります。例えば、識別子bool(var1)はブール型プロパティーvar1の値として解釈されます。

注:使用される言語では、文字列を除く全てのタイプで大文字と小文字が区別されます。例えば「If A ThEn B」は「if a then b」とまったく同じですが、'a''A'は同じではありません。トークン化にスペース、タブ、改行が使用されますが、無視されます。

演算子

演算子は、リテラル値とプロパティー値で使用できます。算術演算子の場合、乗算には接頭辞表記を使用し、演算の順序を指定するには括弧を使用します。

演算子説明Examples
Add numbers or strings.

property1 + 100

Subtract numbers.property1 + 100 - property2
*
Multiply numbers. 10property1 = 10 * property1
/
Divide numbers.property1 * (100 - property2/(50 - property3))
<
Checks if a value is less than another. Supported by number properties or constants.a < 100
&gt;
Checks if a value is greater than another. Supported by number properties or constants.a > 50
&lt;=
Checks if a value is less than or equal to another. Supported by number properties or constants.a <= b
&gt;=
Checks if a value is greater than or equal to another. Supported by number properties or constants.

b >= c

Checks if a value is equal to another. Supported by both numbers and strings.(a + b - 100c * 150.652) = 150-230b
equals
Checks if a value is equal to another. Supported by both numbers and strings.a + b - 100.2c * 150 equals 150 - 230
!=
Checks if a value is not equal to another. Supported by both numbers and strings.string(property1) != 'test_string'
or
Checks if either or two values are true. a > b or b <= c
and
Checks if both values are true.bool(a) and bool(c)
not
Checks if none of the values are true.not (bool(a) and bool(c))

関数

サポートされている関数は次のとおりです。

Use this table to describe parameters / fields
関数説明Examples
max
Will have between 2 and 100 input numbers, and will return the maximum number out of all the inputs.max(a, b, c, 100)またはmax(a, b)
min
Will have between 2 and 100 input numbers, and will return the minimum number of out all the inputs.

min(a, b, c, 100)またはmin(a, b)

is_present
Evaluates whether an expression can be evaluated.

is_present(bool(a)) = true(プロパティーがブール型の場合)、is_present(bool(a)) = false(プロパティーが空か、ブール型でない場合)

contains
Has two strings as inputs and will return true if the first input contains the second.

contains('hello', 'ello') = truecontains('ello', 'hello') = false

concatenate
Joins a list of strings. The list of inputs can go from 2 up to 100.

concatenate('a', 'b', string(a), string(b))

次の2つの解析関数もあります。

  • number_to_string:入力された数値式を文字列に変換しようと試みます。
  • string_to_number:入力された文字列式を数値に変換しようと試みます。

例えば、"Number of cars: " + num_carsは、文字列と数値を加算することはできないため、有効なプロパティーではありませんが、"Number of cars: " + number_to_string(num_cars)であれば有効なプロパティーです。

条件文

ifelseifendif、およびelseを使った条件文を使用して式を記述することもできます。

条件文の例:if boolean_expression then statement [elseif expression then statement]* [else statement | endif](ここで、括弧で囲まれた[a]はオプションであることを表し、a|bは「a」または「b」のいずれかが有効であることを表します。*は「0」以上であることを意味します。endifを使用すると、条件文を早期に終了して、パーサーが次のelseifが属するifを特定できるようにすることができます。

式の例

以下の例を参考にして、独自の計算式を定義できます。

//Example formula "calculationFormula": "closed - started"

以下に、条件文を使用した高度な例を示します。

//Example formula "calculationFormula": "if is_present(hs_latest_sequence_enrolled_date) then if is_present(hs_sequences_actively_enrolled_count) an hs_sequences_actively_enrolled_count >= 1 then true else false else ''"

プロパティーの値を更新またはクリアする

プロパティーを定義した後、オブジェクトAPIを介してレコードの値を更新できます。以下では、特定のプロパティー フィールド タイプの値を書式設定する方法と、プロパティー値をクリアする方法について説明します。

チェックボックスタイプのプロパティーに値を追加する

レコードのチェックボックス型プロパティーの値を更新する場合は、次の方法で値を書式設定します。

  • ブール型チェックボックスプロパティーHubSpotで[はい]を表示するかチェックをオンにするには、値がtrueである必要があります。HubSpotで[いいえ]を表示するかチェックをオフにするには、値がfalseである必要があります。
  • 複数選択チェックボックスプロパティー:複数チェックボックスプロパティーに値を追加するには、最初の値の前にセミコロンを追加し、各値の間にセミコロンを含めます。プロパティーに既存の値がある場合、先頭のセミコロンによって値が上書きされるのではなく、値が付加されます。例えば、コンタクトのhs_buying_roleプロパティーに既存の値DECISION_MAKERがあるとします。既存の値を置き換えずに追加の値を付加するリクエストは、次のようになります。
///Example body for PATCH request to /crm/v3/objects/contacts/{contactId} { "properties": { "hs_buying_role": ";BUDGET_HOLDER;END_USER" }}

ユーザープロパティーでレコード所有者を割り当てる

APIを介してCRMレコードにユーザーを割り当てるとき、値はユーザーの所有者idでなければならず、これはプロパティー設定または所有者APIを介して見つかります。例えば、ユーザーをコンタクトの所有者として割り当てるには、本文{ "properties":{ "hubspot_owner_id": "41629779"}}を使用するPATCHリクエストをcrm/v3/objects/contacts/{contactId}に送信します。

プロパティー値をクリア

APIを介してオブジェクトプロパティー値を消去するには、プロパティー値に空の文字列を指定できます。

例えば、コンタクトオブジェクトからfirstnameを消去するには、本文{ "properties": { "firstname": ""}}を使用したPATCHリクエストをhttps://api.hubapi.com/crm/v3/objects/contacts/{contactId}に送信します。


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