最終更新日: 2025年9月12日
HubDBは、スプレッドシートと同じように、テーブル(表)の行、列、セルでデータを表現するリレーショナル データ ストアです。HubDBテーブルをHubSpotアカウント内で追加したり変更したりできますが、ここに記載されているAPIエンドポイントを使用することもできます。ウェブサイトやプログラマブルEメールでHubDBテーブルのデータを使用する方法については、HubSpotのCMS開発者向けドキュメントを参照してください。
HubSpotウェブサイトページと同様に、HubDBテーブルはdraft
バージョンとpublished
バージョンをサポートしています。これにより、公開中のページに影響を与えずに、テスト用または手動による承認プロセス用にテーブル内のデータを更新することができます。下書きテーブルと公開テーブルについて詳細をご確認ください。
公開アクセスを許可するようにテーブルが設定されている場合、クエリーパラメーターportalId
を介してHubSpotアカウントIDを指定すると、認証なしでテーブルと行の公開バージョンにアクセスできます。
HubDB APIのv2から移行しようとしている場合は、最新の(v3)APIの変更点について詳しくご確認ください。
レート制限
HubDBのAPIリクエストには、リクエストの種類に応じて異なるレート制限が適用されます。- 認証を必要としない
GET
リクエスト(クライアントサイドのJavaScriptリクエストを含む)は、1秒あたり10件に限定されます。これらのリクエストは1日あたりの上限には計上されません。 - 認証を使用するその他全てのリクエストには、標準的な制限が適用されます。
下書きテーブルと公開テーブル
HubDBテーブルには下書きバージョンと公開バージョンの両方があります。公開バージョンは非公開にすることもできます。非公開にしてテーブル内のデータを更新すれば、他の公開ページに影響を与えずに、ページのプレビューやテスト、手動による承認プロセスを行うことができます。 このAPIでは、テーブルの下書きバージョンと公開バージョンに別々のエンドポイントが指定されています。例えば、以下のエンドポイントにGET
リクエストを送信することで、テーブルの公開バージョンを取得できます。
/cms/v3/hubdb/tables/{tableIdOrName}
また、下書きはできているが未公開になっているコンテンツを取得するには、URLの末尾に/draft
を追加します。
/cms/v3/hubdb/tables/{tableIdOrName}/draft
下書きデータをレビューした後、HubSpotでプッシュできます。/push-live
エンドポイントを使用することもできます。また、エンドポイント/reset
を介して下書きデータを破棄することもでき、こうすれば中断なしでデータを現在の公開バージョンに戻すことができます。
HubDBテーブルを作成する
HubDBテーブルを作成するには、POST
リクエストを/cms/v3/hubdb/tables
に送信します。
リクエスト本文で、次の必須フィールドを指定します。
フィールド | タイプ | 説明 | 例 |
---|---|---|---|
name | 文字列 | テーブルの内部名。テーブルの作成後に、この「name」を変更することはできません。「name」には半角の英小文字、数字、アンダースコアのみ含めることができますが、数字で始めることはできません。 | "name": "my_table" |
label | 文字列 | ユーザーがHubSpotでテーブルを編集するときに表示される、テーブルのラベル。 | "label":"My table" |
フィールド | タイプ | 説明 | 例 |
---|---|---|---|
useForPages | ブール値 | テーブルを動的ページの作成に使用可能にするかどうかを指定します。 | "useForPages": false |
allowPublicAPIAccess | ブール値 | 承認なしでテーブルを読み取り可能にするかどうかを指定します。 | "allowPublicApiAccess": false |
allowChildTables | ブール値 | テーブルの子テーブルを作成できるかどうかを指定します。 | "allowChildTables": false |
enableChildTablePages | ブール値 | 子テーブルを使用してマルチレベルの動的ページを作成するかどうかを指定します。 | "enableChildTablePages": false |
columns | オブジェクト | テーブルの列。列プロパティーの詳細については、「テーブル列を追加する」のセクションをご覧ください。 | See "Add table columns" section below |
テーブル列の追加
HubDBテーブルの各列は、次のプロパティーを使用して定義可能です。フィールド | タイプ | 説明 | 例 |
---|---|---|---|
name | 文字列 | (必須)列の内部名。列の作成後にこれを変更することはできません。 | "name": "row_name" |
label | 文字列 | 任意。ユーザーがHubSpotで列を編集するときに表示される、列のラベル。 | "label": "Row label" |
type | 文字列 | 列のデータタイプ。次のいずれかにする必要があります。
| "type": "type" |
options | オブジェクト | selectタイプとmultiselectタイプの列で使用できるオプションのリスト。各オプションは、name に加え、option に設定されたtype を使用して定義されます。 | "option": [{"name":"Option 1", "type":"option"}, {"name": "Option 2", "type": "option"}] |
id
フィールドを含めます。
テーブル行の追加
行を追加するには、APIを使用して手動で行う方法と、CSVファイルから行をインポートする方法があります。 HubDBテーブルに行を追加するには、POST
リクエストを/cms/v3/hubdb/tables/{tableIdOrName}/rows
に送信します。
各テーブル行には、次のフィールドを含めることができます。
フィールド | タイプ | 説明 | 例 |
---|---|---|---|
values | オブジェクト | 列名とその列に追加する値を指定する、キーと値のペアからなるリスト。 いずれかの列に特定の値を設定する必要がない場合は、キー/値ペアのリストでその列名を省略できます。 | "values": { "text_column": "sample text", "number_column": 76} |
path | 文字列 | 動的ページに対して有効になっているテーブルの場合、path は、この行で作成されるページに使用されるパスサフィックスです。 | "path": "example_url_path" |
name | 文字列 | 動的ページに対して有効になっているテーブルの場合、name は、この行で作成されるページに使用されるHTMLタイトルです。 | "name": "Example Title" |
childTableId | 数値 | マルチレベルの動的ページを作成する場合、childTableId は子テーブルのIDを指定します。 | "childTableId": 123456 |
CSVからの行のインポート
CSVファイルからHubDBテーブルにデータをインポートするには、POST
リクエストを/cms/v3/hubdb/tables/{tableIdOrName}/draft/import
に送信します。
インポートエンドポイントは、次のようなmultipart/form-data
POST
リクエストを受け入れます。
config
**:**インポートで使用されるJSON形式のオプションのセット。file
**:**インポートするCSVファイル。
config
には、次のフィールドをJSON文字列として含めます。
フィールド | タイプ | 説明 | 例 |
---|---|---|---|
skipRows | 数値 | スキップするヘッダー行の数。このフィールドの値は既定で1 に設定されます。この場合、最初の行はヘッダーとして扱われてスキップされます。全ての行が有効なデータである場合は、このフィールドの値を0 に設定してください。 | "skipRows": 0 |
separator | 文字列 | CSVファイル内の列区切り文字。既定では"," (半角カンマ)に設定されます。 | "separator": "," |
idSourceColumn | 数値 | 行のID(hs_id )が入っているソースファイル内の列のインデックス。この列が指定されている場合、インポートされるCSVファイル内のIDが一致する行によって、テーブル内の既存の行が更新されます。これは任意のフィールドであり、初めてデータをテーブルにインポートするときには無視できます。詳細については、下記の「リセットオプション」セクションを参照してください。 | "idSourceColumn": 1 |
resetTable | ブール値 | 既定ではfalse に設定されます。この場合、既存の行を1つも除去することなく、テーブルの行が更新されます。true に設定すると、スプレッドシートの行によってテーブルのデータが上書きされます。つまり、スプレッドシート内に含まれない行はテーブルから削除されます。詳細については、下記の「リセットオプション」セクションを参照してください。 | "resetTable": true |
nameSourceColumn | 数値 | 動的ページに対して有効になっているテーブルの場合、nameSourceColumn は、行のname が格納されているCSVファイル内の列を指定します。列番号は昇順で、最初の列は1 です。 | "nameSourcecolumn": 5 |
pathSourceColumn | 数値 | 動的ページに対して有効になっているテーブルの場合、pathSourceColumn は、行のpath が格納されているCSVファイル内の列を指定します。列番号は昇順で、最初の列は1 です。 | "pathSourcecolumn": 6 |
childTableSourceColumn | 数値 | CSVファイル内の、行のchildTableId が入っている列を指定します。列番号は昇順で、最初の列は1 です。 | "childTableSourcecolumn": 3 |
columnMappings | 配列 | ソースファイル内の列とインポート先HubDBテーブル内の列の間のマッピングリスト。各マッピングは次の形式でなければなりません:{"source":1,"target”:"columnIdOrName"}
hs_id 列がある場合は、それをcolumnMappings に含めないでください。代わりに、この列をidSourceColumn として含めて既存の行を更新します。 | "columnMappings": [{"source":1, "target": 2}, {"source": 2, "target": "column_name"}] |
primaryKeyColumn | 文字列 | 重複排除に使用される、ターゲットHubDBテーブル内の列の名前。このフィールドで列のIDを使用することはできません。 | "primaryKeyColumn": "column_name" |
encoding | 文字列 | ファイルのエンコーディングの種類。例:utf-8 、ascii 、iso-8859-2 、iso-8859-5 、iso-2022-jp 、windows-1252 。 | "encoding": "utf-8" |
format | 文字列 | CSVのみがサポートされています。 | "format": "csv" |
config
JSONの例を以下に示します。
日付の書式設定
データを日付型の列にインポートする際は、さまざまな日付形式を使用できます。 整数yyyy/mm/dd
yyyy/mm/dd
mm/dd/yyyy
mm/dd/yy
dd/mm/yy
という形式は使用できません)。整数の区切り文字としてハイフン(-
)またはスラッシュ(/
)を使用できます。
準標準の日付形式
整数ベースの日付形式ほど標準化されていない日付形式をインポートすることもできます。例:
The 1st of March in the year 2022
Fri Mar 4 2022
March 4th '22
next Thursday
Today
tomorrow
3 days from now
リセットオプション
CSVファイルからHubDBテーブルにデータをインポートするときに、resetTable
フィールドをtrue
またはfalse
(既定)に設定すると、HubDBの行データを上書きするかどうかを管理できます。
-
resetTable
がtrue
に設定されている場合:- CSVファイル内の行に行ID列(
hs_id
)がない場合、または行IDが0
と指定されている場合、それらの行は、生成された新しい行IDを使って挿入されます。 - CSVファイル内の行IDがターゲットテーブルに既に存在する場合、テーブルの既存の行は入力ファイル内の新しい値で更新されます。
- テーブルに行が存在するものの、入力CSVファイルにその行に対応する行IDがない場合、その行はターゲットテーブルから削除されます。
- 入力CSVファイル内の行IDがターゲットテーブル内に存在しない場合は、生成された新しい行IDを使ってそれらの行が挿入され、入力ファイル内で指定されている行IDは無視されます。
- 入力CSVファイル内に行IDの列が1つも含まれていない場合、ターゲットテーブルから全ての行が削除され、入力ファイル内の行が、生成された新しい行IDを使って挿入されます。
- CSVファイル内の行に行ID列(
-
resetTable
がfalse
(既定)に設定されている場合:- CSVファイル内の行IDがターゲットテーブルに既に存在する場合、テーブルの既存の行は入力ファイル内の新しい値で更新されます。
- テーブルに行が存在するものの、入力CSVファイルにその行に対応する行IDがない場合、その行はターゲットテーブルから削除されず、変更が加えられないままの状態になります。
- 入力CSVファイル内の行IDがターゲットテーブル内に存在しない場合は、生成された新しい行IDを使ってそれらの行が挿入され、入力ファイル内で指定されている行IDは無視されます。
- CSVファイル内の行に行ID列がない場合、または行IDが
0
と指定されている場合、それらの行は、生成された新しい行IDを使って挿入されます。
HubDBデータの取得
テーブルの詳細を取得するか、またはテーブルの特定の行を取得するかに応じて、HubDBデータを取得するにはさまざまな方法があります。- 公開されている全てのテーブルからテーブルの詳細を取得するには
GET
リクエストを/cms/v3/hubdb/tables
に送信します。 - 公開されている特定のテーブルからテーブルの詳細を取得するには、
GET
リクエストを/cms/v3/hubdb/tables{tableIdOrName}
に送信します。 - 特定のテーブルから全ての行を取得するには、
GET
リクエストを/cms/v3/hubdb/tables{tableIdOrName}/rows
に送信します。 - テーブルから特定の行を取得するには、
GET
リクエストを/cms/v3/hubdb/tables{tableIdOrName}/rows/{rowId}
に送信します。
portalId
を介してHubSpotアカウントIDを指定すると、認証なしでテーブルと行の公開バージョンにアクセスできます。
返された行に対するフィルターの適用
HubDBテーブルデータを取得する際に、特定のデータを取得するためのクエリーパラメーターとしてフィルターを適用できます。フィルター クエリー パラメーターは、columnName__operator
という形式で構成されます。
例えば、「bar」 という名前の数値列がある場合、「bar」 が10より大きい行だけを結果に含めるには、&bar__gt=10
とします。
全てのフィルターはAND結合されます(現在のところ、ORフィルターはサポートされていません)。
フィルターを適用する際は、次の点に注意してください。
-
multiselect
の列の値を渡すときには、各値を半角カンマで区切る必要があります(例:multiselect_column__contains=1,2
)。 -
datetime
フィルターでは、現在の時刻を基準とする値を指定する目的で、タイムスタンプの代わりに相対日付を使用できます。例えば-3h
は今から3時間前のタイムスタンプに相当し、10s
は10秒後のタイムスタンプに相当します。サポートされている時間単位は、ms(ミリ秒)、s(秒)、m(分)、h(時間)、d(日)です。現在の時刻を使用するには、値をゼロにします(0s)。 -
これらのフィルター用に組み込む
hs_id
列はnumber
タイプ、hs_created_at
列はdatetime
タイプ、hs_path
列およびhs_name
列はtext
タイプです。
演算子 | 名前 | 説明 |
---|---|---|
eq (or none) | 等しい | 全ての列タイプ。演算子が使用されていない場合、このフィルターが適用されます。multiselectの列でこれを使用すると、指定された値に完全に一致する行が返されます。 |
ne | 等しくない | 全ての列タイプ。 |
contains | 次の全ての値を含む | テキスト、リッチテキスト、およびmultiselect。multiselectの列でこれを使用すると、指定された全ての値を含む行が返されます。このフィルターでは大文字と小文字が区別されます。 |
lt | 次の値より小さい | 数値、日付、日時。 |
lte | 次の値以下 | 数値、日付、日時。 |
gt | 次の値より大きい | 数値、日付、日時。 |
gte | 次の値以上 | 数値、日付、日時。 |
is_null | Null | ブールを除く全てのタイプの列。このフィルターでは値は不要です(例:&exampleColumn__is_null= )。 |
not_null | Nullではない | ブールを除く全てのタイプの列。このフィルターでは値は不要です(例:&exampleColumn__not_null= )。 |
like | いいね! | テキストとリッチテキスト。 |
not_like | いいね!ではない | テキストとリッチテキスト。 |
icontains | 次の文字列を含む | テキストとリッチテキスト。このフィルターでは大文字と小文字が区別されません。 |
startswith | 次の文字列で始まる | テキストとリッチテキスト。 |
in | 次の値のいずれかを含む | 数値、select、multiselect。渡されたオプションのうち少なくとも1つが列に入っている行が返されます。クエリーパラメーターの中に他のsort がない場合、返される結果は、in 演算子での値の指定順に並べ替えられます。 |
返された行の並べ替え
HubDBデータを取得するときに、クエリーパラメーターとして並べ替えを適用することで、返されるデータの順序を指定できます。データを並べ替えるには、次のようにsort
クエリーパラメーターを追加して、列名を指定します。
&sort=columnName
既定では、列が指定されている順序でデータが返されます。これを逆順で並べ替えるには、列名に-
を追加します。
&sort=-columnName
このパラメーターを複数指定することにより、複数の列を基準に並べ替えができるようになります。
列を基準とした並べ替えに加えて、次の3つの関数を使用可能です。
- **geo_distance(location_column_name、緯度、経度):**所在地列の名前と座標を入力として受け入れ、指定された所在地列の値と指定された座標の間の距離が長い順に行を返します。
- **length(column_name):**列の名前を入力として受け入れ、(文字列として計算される)列値の長さの順に行を返します。
- **random():**ランダムな順序で行を返します。
geo_distance
は、距離が最も遠いものを最初にしてアイテムを返します。
sort=-geo_distance(location_column,42.37,-71.07)
動的ページ用のHubDBテーブルの設定
HubSpotのCMSを使用すると、HubDBテーブルをデータソースとして使用して動的ページを生成することができます。例えば、経営陣のメンバーごとに1行ずつ含むテーブルを作成し、ページに表示させたい情報が入った列をそれに含めることができます。ページの動的データソースとしてそのテーブルを選択すると、サマリー項目として全行を表示するリストページがそのページによって生成され、さらに行ごとに個別のページも生成されて、ブログ リスト ページとブログ記事ページに似た状態になります。 コンテンツエディターでテーブルをデータソースとして選択できるようにするには、useForPage
をtrue
に設定する必要があります。必要に応じてdynamicMetaTags
を含めると、各ページのメタデータにどの列を使用するかを指定できます。
例えば次のコードでは動的ページ用のテーブルを作成して、ページのメタデータに使われる3つの列を指定します。
パラメーター | タイプ | 説明 |
---|---|---|
useForPages | ブール値 | テーブルを動的ページのデータソースとして使用できるようにするには、これをtrue に設定します。 |
dynamicMetaTags | オブジェクト | 各動的ページのメタデータに使用する列をIDによって指定します。以下を含めることができます:
|
DESCRIPTION | 数値 | 各ページのメタディスクリプションに使用する列の数値ID。 |
FEATURED_IMAGE_URL | 数値 | 各ページのキービジュアルURLに使用する列の数値ID。 |
LINK_REL_CANONICAL_URL | 数値 | 各ページのcanonical URLに使用する列の数値ID。 |
v3での変更点
- テーブルには
name
とlabel
の両方が必要です。テーブルの作成後に、この「name」を変更することはできません。「name」には半角の英小文字、数字、アンダースコアのみ含めることができますが、数字で始めることはできません。name
とlabel
はどらちも、アカウント内で一意である必要があります。 - APIは、URLパスの中でテーブル
id
とname
の両方をサポートします。 - 行を
GET
するエンドポイントは、values
フィールドでid
ではなく列name
を返します。また、行をPOST
/PUT
/PATCH
するエンドポイントは、values
フィールドでid
ではなく列name
を必要とします。 - 行を更新する
PATCH
エンドポイントで、スパース更新を使用できるようになりました。スパース更新とは、更新する必要のある列値だけを指定できることを意味します(以前のバージョンでは、全ての列値を指定する必要がありました)。複数選択型の列のように、値のリストを使用して列を更新する場合は、全ての値を含むリストを指定する必要があります。列の値を削除するには、リクエスト内でその列の値をnull
として指定する必要があります。 - 行を更新する
PATCH
エンドポイントを優先し、行のセルをget
/update
/delete
するエンドポイントを削除しました。 - インポートエンドポイントでは、JSON形式のオプションで既存のフィールドとともに任意指定フィールド
idSourceColumn
を使用できるようになりました。このフィールドを使用すると、行IDが格納されているCSVファイル内の列を指定できます。新しい行を既存の行の新しい値とともにインポートするには、新しい行の行IDには単に0
を指定し、既存の行には有効な行IDを指定できます。詳細については、以下の「インポート」セクションをご参照ください。さらに、JSON形式のオプションに含まれる列マッピングのターゲットフィールドで、列の名前またはIDを使用することもできます。 - 複製エンドポイントには、新しい名前と新しいラベルが必要です。