カスタムオブジェクト
-
Marketing Hub
- Enterprise
-
Sales Hub
- Enterprise
-
Service Hub
- Enterprise
-
CMS Hub
- Enterprise
-
Operations Hub
- Enterprise
HubSpotアカウントごとに、標準CRMオブジェクトとして、コンタクト、会社、取引、チケットがあります。ビジネスニーズに基づいてCRMデータを表示し、整理するためのカスタムオブジェクトを作成することもできます。HubSpotでカスタムオブジェクトを作成するか、カスタムオブジェクトAPIを使用して、カスタムオブジェクト、プロパティー、他のCRMオブジェクトとの関連付けを定義できます。
以下で、APIを使用してカスタムオブジェクトを作成し、管理する方法を説明し、サンプル カスタム オブジェクトの作成手順を詳しく見ていきます。
カスタムオブジェクトの作成の詳細については、HubSpot開発者ブログの次の投稿をご覧ください。
注:カスタムオブジェクトは各アカウントに固有であり、ご契約内容によっては、作成できるカスタムオブジェクトの数に制限があります。適用される上限について詳しくは、HubSpot製品・サービスカタログをご覧ください。
次の認証方法のいずれかを使用して、カスタムオブジェクトの作成、読み取り、更新を行うことができます。
- OAuth(英語)
- 非公開アプリのアクセストークン
カスタムオブジェクトを作成するには、まず、オブジェクトスキーマを定義する必要があります。スキーマには、オブジェクトの名前、プロパティー、および他のCRMオブジェクトとの関連付けを含めます。スキーマリクエストの詳細については、この記事の上部の[オブジェクトスキーマ]タブでご確認いただけます。以下のサンプルチュートリアルで、リクエストの例を確認することもできます。
カスタム オブジェクト スキーマを作成するには、crm/v3/schemas
に対してPOST
リクエストを行います。リクエスト本文に、オブジェクトスキーマの定義(オブジェクトの名前、プロパティー、関連付け)を含めます。
カスタムオブジェクトに名前を付ける際は、次の点に留意してください。
- オブジェクトを作成した後に、オブジェクトの名前とラベルを変更することはできません。
- 名前には、文字、数字、アンダースコアのみを使用できます。
- 名前はアルファベットで始める必要があります。
- 製品の特定の部分では、長いラベルが切り詰められる場合があります。
オブジェクトのプロパティーと関連付けに必要な定義については、以下の説明をお読みください。
リクエスト本文で定義したプロパティーは、個々のカスタム オブジェクト レコードに情報を格納するために使用されます。
注:HubSpotアカウントで、1つのカスタムオブジェクトにつき作成できる固有の値のプロパティーは10個までです。
定義したプロパティーを使用して、以下のプロパティーベースのフィールドに値を入力します。
- requiredProperties:新しいカスタム オブジェクト レコードを作成するときに必要なプロパティー。
- searchableProperties:HubSpotでの検索に使用するためにインデックス付けされるプロパティー。
- primaryDisplayProperty:個々のカスタム オブジェクト レコードに名前を付けるために使用されるプロパティー。
- secondaryDisplayProperties:primaryDisplayPropertyに属する個々のレコードに表示されるプロパティー。
secondaryDisplayProperties
にリストされる最初のプロパティーは、そのタイプが以下のいずれかの場合、オブジェクト インデックス ページにも4つ目のフィルターとして追加されます。string
number
enumeration
boolean
datetime
- UIから表示プロパティーを削除するには、一度プロパティーを削除してから再作成する必要があります。
デフォルトでは、スキーマリクエストによってプロパティーを作成する際に、type
プロパティーはstring
に設定され、fieldType
プロパティーはtext
に設定されます。以下の値を使用して、さまざまなタイプのプロパティーを作成できます。
type |
説明 | 有効なfieldType の値 |
---|---|---|
enumeration |
一連のオプションを表す文字列。各オプションをセミコロンで区切って入力します。 | booleancheckbox 、checkbox 、radio 、select |
date |
特定の年、月、日を表すISO 8601形式の値。 | date |
dateTime |
特定の年、月、日、時刻を表すISO 8601形式の値。HubSpotアプリ上には時刻は表示されません。 | date |
string |
プレーンテキスト文字列。文字数の上限は65,536文字です。 | file 、text 、textarea |
number |
数値。小数第1位まで。 | number |
fieldType |
説明 |
---|---|
booleancheckbox |
ユーザーが「はい」または「いいえ」のいずれかを選択できる入力。フォーム内で使用する場合、1つのチェックボックスとして表示されます。 |
checkbox |
プロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。 |
date |
日付値。日付入力として表示されます。 |
file |
フォームへのファイルのアップロードが可能。ファイルへのURLリンクとして格納および表示されます。 |
number |
一連の数字。10進数または指数表記として記述。 |
radio |
プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。 |
select |
プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。 |
text |
プレーンテキスト文字列。単行テキスト入力として表示されます。 |
textarea |
プレーンテキスト文字列。複数行テキスト入力として表示されます。 |
関連付け
HubSpotは、カスタムオブジェクトに自動的にEメール、ミーティング、メモ、タスク、コール、コミュニケーションオブジェクトを関連付けます。さらに、カスタムオブジェクトに他の標準的なHubSpotオブジェクトや他のカスタムオブジェクトを関連付けることもできます。
スキーマ作成リクエストによって関連付けを作成する場合は、以下の例に示すように、名前を使用して標準のオブジェクトを識別し、objectTypeId
を使用してカスタムオブジェクトを識別します。
全てのカスタムオブジェクトを取得するには、GET
リクエストを/crm/v3/schemas
に送信します。
特定のカスタムオブジェクトを取得する場合は、次のエンドポイントのいずれかに対してGET
リクエストを送信します。
/crm/v3/schemas/{objectTypeId}
/crm/v3/schemas/p_{object_name}
/crm/v3/schemas/{fullyQualifiedName}
オブジェクトのスキーマに含まれるオブジェクトの
fullyQualifiedName
は、そのオブジェクトのスキーマに含まれています。これは、p{portal_id}_{object_name}
から派生したものです。アカウント情報APIを使用して、アカウントのポータルIDを確認できます。
例えば、IDが1234
で、lender
という名前のオブジェクトを持つアカウントの場合、リクエストURLは次のようになります。
https://api.hubapi.com/crm/v3/schemas/2-3465404
https://api.hubapi.com/crm/v3/schemas/p_lender
https://api.hubapi.com/crm/v3/schemas/p1234_lende
カスタム オブジェクト レコードを取得することもできます。
- レコードIDの値を使用して特定のレコードを取得するには、
crm/v3/objects/{objectType}/{recordId}
に対してGET
リクエストを送信します。
このエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。
Parameter | Description |
---|---|
properties
| レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象のカスタム オブジェクト レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
propertiesWithHistory
| レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のカスタム オブジェクト レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
associations
| 関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。 |
- 複数のレコードを取得するには、
crm/v3/objects/{objectType}/batch/read
に対してPOST
リクエストを送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。
リクエストで、レコードID(hs_object_id
)またはカスタムの固有の識別子のプロパティー。既定で、リクエストのid
値はレコードIDを表すので、レコードIDを使用して取得する場合はidProperty
パラメーターは不要です。カスタムの固有の値のプロパティーを使用する場合は、idProperty
パラメーターを含める必要があります。
例えば、カスタム オブジェクト レコードを一括で取得する場合のリクエストは、次のいずれかのようになります。
オブジェクトのスキーマを更新するには、PATCH
リクエストをhttps://api.hubapi.com/crm/v3/schemas/{objectTypeId}
に送信します。
カスタムオブジェクトを定義した後は、以下の点にご留意ください。
- オブジェクトの名前とラベル(単数形と複数形)を変更することはできません。
requiredProperties
、searchableProperties
、primaryDisplayProperty
、secondaryDisplayProperties
は、オブジェクトのスキーマを更新することで変更できます。新しいプロパティーを、必須プロパティー、検索可能プロパティー、または表示プロパティーとして設定するには、スキーマを更新する前にそのプロパティーを作成する必要があります。- カスタム オブジェクト プロパティーは、HubSpotで、またはプロパティーAPIを使用して作成および編集できます。
関連付けを更新する
カスタムオブジェクトに他のオブジェクト関連付けを追加するには、POST
リクエストを/crm/v3/schemas/{objectTypeId}/associations
に送信します。
カスタムオブジェクトには、標準のHubSpotオブジェクト(「コンタクト」「会社」「取引」「チケット」など)または他のカスタムオブジェクトを関連付けることができます。以下の例に示すように、toObjectTypeId
フィールドで、カスタムオブジェクトはそのobjectTypeId
値で識別し、標準のオブジェクトはその名前で識別します。
カスタムオブジェクトは、そのタイプの全てのオブジェクトインスタンスが削除された後にのみ削除できます。カスタムオブジェクトを削除するには、DELETE
リクエストを/crm/v3/schemas/{objectType}
に送信します。
削除したオブジェクトと同じ名前の新しいカスタムオブジェクトを作成する必要がある場合は、DELETE
リクエストを/crm/v3/schemas/{objectType}?archived=true
に送信して、スキーマのハード(物理)削除を行う必要があります。カスタム オブジェクト タイプの削除は、そのタイプの全てのオブジェクトインスタンス、関連付け、カスタムオブジェクトのプロパティーが削除された後のみしかできません。
以下は、サンプル カスタム オブジェクトの作成方法を説明するチュートリアルです。記載されているリクエストの詳細については、記事の上部にある[オブジェクト]タブを参照してください。
このチュートリアルの内容は次のとおりです。
- カスタム オブジェクト スキーマの作成
- カスタム オブジェクト レコードの作成
- カスタム オブジェクト レコードへのHubSpotコンタクトの関連付け
- カスタムオブジェクトとHubSpotチケットとの間の新しい関連付け定義の作成
- 新しいプロパティー定義の作成
- 新しいプロパティーの追加による、オブジェクトスキーマ(
secondaryDisplayProperties
)の更新
目標:CarSpotという自動車販売店では、在庫情報をHubSpotに保存するために、カスタムオブジェクトを使用したいと考えています。車両の所有権と購入のトラッキングを行うには、車両にコンタクトレコードを関連付ける必要があります。その過程で、HubSpotチケットとカスタムプロパティーを使用して車両メンテナンスのトラッキングも行います。
オブジェクトスキーマを作成する
CarSpotでは、次の属性をプロパティーとして表すことができるオブジェクトスキーマを作成する必要があります。
- 条件(新車または中古車):enumeration
- 販売店受付日:date
- 製造年:number
- メーカー:string
- モデル:string
- VIN:string(固有の値)
- 色:string
- 走行距離:number
- 価格:number
- メモ:string
また、オブジェクトの使用方法に関するコンテキストを提供する説明を追加し、カスタムオブジェクトと標準のコンタクトオブジェクトの関連付けを定義して、車を潜在的な購入者に結び付けられるようにします。
データモデルが完成したら、オブジェクトスキーマを作成するために、POST
リクエストを/crm/v3/schemas
に送信します。このリクエストの本文は次のように設定します。全て
オブジェクトスキーマを作成した後、CarSpotは新しいオブジェクトの{objectTypeId}
フィールドの値を確認します。後でオブジェクトを取得および更新する際にこの値を使用するためです。必要に応じて、{fullyQualifiedName}
の値を使用することもできます。
カスタム オブジェクト レコードを作成する
カスタムオブジェクトが作成されたら、CarSpotは、在庫にある車両ごとにオブジェクトレコードを作成できます。
最初の車両のオブジェクトレコードを作成するために、次のようにリクエスト本文を設定したPOST
リクエストを/crm/v3/objects/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
レコードが作成された後は、id
値を使用して、車両に既存のコンタクトを関連付けることができます。
後から、このレコードと特定のプロパティーを取得する場合は、https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model
に対してGET
リクエストを送信します。
カスタム オブジェクト レコードを別のレコードに関連付ける
新しい車両レコードのID(181308
)と別のレコードのIDを使用して、カスタム オブジェクト レコードを別のオブジェクトのレコードに関連付けることができます。
関連付けを作成するには、PUT
リクエストを/crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}
に送信します。オブジェクトの関係がすでに定義されている場合、associationType
値を判別するには、GET
リクエストをcrm/v3/schemas/{objectType}
に送信します。
例えば、コンタクトID 51
と関連付けタイプ75
を使用して、CarSpotは車両レコードにコンタクトを関連付けることができます。上記のIDを使用して、次のリクエストURLが作成されます。
https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75
新しい関連付けを定義する
CarSpotは次に、車両の販売後サービスのトラッキングを開始したいと考えています。そのために、HubSpotのチケットを使用して、実施されたメンテナンスをログに記録します。
車両とチケットを関連付けられるようにするために、次のようにリクエストの本文を設定したPOST
リクエストを/crm/v3/schemas/2-3465404/associations
に送信して、新しい関連付けを作成します。
このAPI呼び出しの応答は次のようになります。全てをコピー
2つのカスタムオブジェクト間に新しい関連付けを作成する場合は、「toObjectTypeId」フィールドで「objectTypeId」を指定して、カスタムオブジェクトを指定します。標準オブジェクトの場合、名前で指定するか、次の値を使用できます。
- コンタクト:0-1
- 会社名:0-2
- 取引:0-3
- チケット:0-5
新しいプロパティーを定義する
メンテナンスのトラッキングを進めるにつれて、CarSpotはメンテナンスサービスをパッケージにして提供できる可能性があることに気づきました。個々の車両レコードでこれらのメンテナンスパッケージのトラッキングを行うために、利用可能なパッケージを含む新しいenumeration型プロパティーを作成します。
新しいプロパティーを定義するには、次のようにリクエスト本文を設定したPOST
リクエストを/crm/v3/properties/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
プロパティーが作成されたので、このプロパティーを各車両レコードのサイドバーに表示して、営業担当者や技術者が情報をすぐに利用できるようにしたいと考えています。それには、このプロパティーをsecondaryDisplayProperties
に追加するために、次のようにリクエスト本文を設定したPATCH
リクエストを/crm/v3/schemas/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
このようにして、技術者が車両に関連付けられたコンタクトレコードを開くと、プロパティーがサイドバーのカスタム オブジェクト カードに表示されるようになります。
HubSpotを使用していくにつれて、CarSpotはHubSpotのAPIを通じて、このカスタムオブジェクトを改善し拡張する方法を見出していくことでしょう。さらに、カスタム オブジェクト データを使用して動的ページを作成することも考えられます。
貴重なご意見をありがとうございました。