プロパティー
プロパティーは、CRMレコードに情報を格納するために使用します。HubSpotでは、CRMオブジェクトごとに既定のプロパティーのセットが用意されています。HubSpot上で、またはプロパティーAPIを使用して、独自のカスタムプロパティーを作成および管理することもできます。
プロパティーを作成する際には、データの構築方法を考慮することが重要です。多くの場合、HubSpotの標準オブジェクト上にカスタムプロパティーを作成することで適切に対応できます。しかし場合によっては、独自のプロパティーを備えたカスタムオブジェクトを別途作成することが必要になります。
プロパティーグループは、関連する複数のプロパティーをグループ化するために使用します。グループ化されたプロパティーは各HubSpotレコード上に隣接して表示されます。カスタムプロパティーを作成して連携を行う場合は、カスタムプロパティーのグループを活用することでデータの特定が容易になります。
type |
説明 | 有効なfieldType の値 |
---|---|---|
bool |
バイナリーオプション(Yes またはNo 、True またはFalse など)を格納するフィールド。 |
booleancheckbox 、calculation_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文字です。 | file 、text 、textarea 、calculation_equation 、html 、phonenumber |
number |
数値。小数第1位まで。 | number 、calculation_equation |
有効なfieldType
の値
Fieldtype | Description |
---|---|
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
に設定します。
一意IDプロパティーを作成したら、API呼び出しでそれを使用して、特定のレコードを取得することができます。リクエストURLは例えば次のようになります。GET
https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_uniqueこれにより、system_a_unique
フィールドの値がabc
である取引が返されます。
その後、この一意識別子プロパティー値を使用すると、hs_object_id
、email
(コンタクト)、またはdomain
(会社)を使用するのと同じ方法で、特定のレコードを識別および更新できます。
計算プロパティーは、同じオブジェクトレコード内の他のプロパティーに基づいてプロパティー値を定義します。計算プロパティーを定義するには、最小値、最大値、件数、合計、平均などを求める演算を含めた式を使用します。プロパティーAPIを使用すると、フィールドタイプとしてcalculation_equation
、データ型としてnumber
、bool
、string
、またはenumeration
を使用して、HubSpotアカウントで計算プロパティーを読み取ったり作成したりできます。
プロパティーの計算式は、calculationFormula
フィールドを使用して定義できます。
calculationFormula
を使用すると、算術演算子、比較演算子、論理演算子、条件文、およびその他の関数を使用して式を記述できます。
リテラル構文
- 文字列リテラル:定数列は、単一引用符(
'constant'
)または二重引用符("constant"
)のいずれかを使用して表現できます。 - 数値リテラル:定数は任意の実数にできます。小数点表現を含めることもできます。
1005
と1.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. |
|
―
| 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 |
>
| Checks if a value is greater than another. Supported by number properties or constants. | a > 50 |
<=
| Checks if a value is less than or equal to another. Supported by number properties or constants. | a <= b |
>=
| Checks if a value is greater than or equal to another. Supported by number properties or constants. |
|
=
| 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)) |
関数
サポートされている関数は次のとおりです。
関数 | 説明 | 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. |
|
is_present
| Evaluates whether an expression can be evaluated. |
|
contains
| Has two strings as inputs and will return true if the first input contains the second. |
|
concatenate
| Joins a list of strings. The list of inputs can go from 2 up to 100. |
|
次の2つの解析関数もあります。
number_to_string
:入力された数値式を文字列に変換しようと試みます。string_to_number
:入力された文字列式を数値に変換しようと試みます。
例えば、"Number of cars: " + num_cars
は、文字列と数値を加算することはできないため、有効なプロパティーではありませんが、"Number of cars: " + number_to_string(num_cars)
であれば有効なプロパティーです。
条件文
if
、elseif
、endif
、およびelse
を使った条件文を使用して式を記述することもできます。
条件文の例:if boolean_expression then statement [elseif expression then statement]* [else statement | endif]
(ここで、括弧で囲まれた[a]
はオプションであることを表し、a|b
は「a」または「b」のいずれかが有効であることを表します。*
は「0」以上であることを意味します。endif
を使用すると、条件文を早期に終了して、パーサーが次のelseif
が属するif
を特定できるようにすることができます。
式の例
以下の例を参考にして、独自の計算式を定義できます。
以下に、条件文を使用した高度な例を示します。
プロパティーを定義した後、オブジェクトAPIを介してレコードの値を更新できます。以下では、特定のプロパティー フィールド タイプの値を書式設定する方法と、プロパティー値をクリアする方法について説明します。
レコードのチェックボックス型プロパティーの値を更新する場合は、次の方法で値を書式設定します。
- ブール型チェックボックスプロパティー:HubSpotで[はい]を表示するかチェックをオンにするには、値が
true
である必要があります。HubSpotで[いいえ]を表示するかチェックをオフにするには、値がfalse
である必要があります。 - 複数選択チェックボックスプロパティー:複数チェックボックスプロパティーに値を追加するには、最初の値の前にセミコロンを追加し、各値の間にセミコロンを含めます。プロパティーに既存の値がある場合、先頭のセミコロンによって値が上書きされるのではなく、値が付加されます。例えば、コンタクトの
hs_buying_role
プロパティーに既存の値DECISION_MAKER
があるとします。既存の値を置き換えずに追加の値を付加するリクエストは、次のようになります。
APIを介してオブジェクトプロパティー値を消去するには、プロパティー値に空の文字列を指定できます。
例えば、コンタクトオブジェクトからfirstname
を消去するには、本文{ "properties": { "firstname": ""}}
を使用したPATCH
リクエストをhttps://api.hubapi.com/crm/v3/objects/contacts/{contactId}
に送信します。
貴重なご意見をありがとうございました。