HubDBエンドポイントを使用して、HubDBデータテーブル内のデータを取得および管理することができます。
draft
バージョンとpublished
バージョンをサポートしています。これにより、公開中のページに影響を与えずに、テスト用または手動による承認プロセス用にテーブル内のデータを更新することができます。下書きテーブルと公開テーブルについて詳細をご確認ください。
公開アクセスを許可するようにテーブルが設定されている場合、クエリーパラメーターportalId
を介してHubSpotアカウントIDを指定すると、認証なしでテーブルと行の公開バージョンにアクセスできます。
HubDB APIのv2から移行しようとしている場合は、最新の(v3)APIの変更点について詳しくご確認ください。
GET
をサポートするエンドポイントはCORS
もサポートしていますから、JavaScriptとアカウントIDを使用してクライアントサイドでテーブル内のデータにアクセスできます。その他の方法および「Get all tables」エンドポイントでは認証が必要であり、CORS
はサポートされていません。GET
リクエスト(クライアントサイドのJavaScriptリクエストを含む)は、1秒あたり10件に限定されます。これらのリクエストは1日あたりの上限には計上されません。GET
リクエストを送信することで、テーブルの公開バージョンを取得できます。
/cms/v3/hubdb/tables/{tableIdOrName}
また、下書きはできているが未公開になっているコンテンツを取得するには、URLの末尾に/draft
を追加します。
/cms/v3/hubdb/tables/{tableIdOrName}/draft
下書きデータをレビューした後、HubSpotでプッシュできます。/push-live
エンドポイントを使用することもできます。また、エンドポイント/reset
を介して下書きデータを破棄することもでき、こうすれば中断なしでデータを現在の公開バージョンに戻すことができます。
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 |
フィールド | タイプ | 説明 | 例 |
---|---|---|---|
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
フィールドを含めます。
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 |
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
resetTable
フィールドをtrue
またはfalse
(既定)に設定すると、HubDBの行データを上書きするかどうかを管理できます。
resetTable
がtrue
に設定されている場合:
hs_id
)がない場合、または行IDが0
と指定されている場合、それらの行は、生成された新しい行IDを使って挿入されます。resetTable
がfalse
(既定)に設定されている場合:
0
と指定されている場合、それらの行は、生成された新しい行IDを使って挿入されます。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を指定すると、認証なしでテーブルと行の公開バージョンにアクセスできます。
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 演算子での値の指定順に並べ替えられます。 |
sort
クエリーパラメーターを追加して、列名を指定します。
&sort=columnName
既定では、列が指定されている順序でデータが返されます。これを逆順で並べ替えるには、列名に-
を追加します。
&sort=-columnName
このパラメーターを複数指定することにより、複数の列を基準に並べ替えができるようになります。
列を基準とした並べ替えに加えて、次の3つの関数を使用可能です。
geo_distance
は、距離が最も遠いものを最初にしてアイテムを返します。
sort=-geo_distance(location_column,42.37,-71.07)
useForPage
をtrue
に設定する必要があります。必要に応じてdynamicMetaTags
を含めると、各ページのメタデータにどの列を使用するかを指定できます。
dynamicMetaTags
を指定するときには、content
ではなくpage_meta
HubLタグをページで必ず使用する必要があります。詳しくは、動的ページガイドをご覧ください。パラメーター | タイプ | 説明 |
---|---|---|
useForPages | ブール値 | テーブルを動的ページのデータソースとして使用できるようにするには、これをtrue に設定します。 |
dynamicMetaTags | オブジェクト | 各動的ページのメタデータに使用する列をIDによって指定します。以下を含めることができます:
|
DESCRIPTION | 数値 | 各ページのメタディスクリプションに使用する列の数値ID。 |
FEATURED_IMAGE_URL | 数値 | 各ページのキービジュアルURLに使用する列の数値ID。 |
LINK_REL_CANONICAL_URL | 数値 | 各ページのcanonical URLに使用する列の数値ID。 |
name
とlabel
の両方が必要です。テーブルの作成後に、この「name」を変更することはできません。「name」には半角の英小文字、数字、アンダースコアのみ含めることができますが、数字で始めることはできません。name
とlabel
はどらちも、アカウント内で一意である必要があります。id
とname
の両方をサポートします。GET
するエンドポイントは、values
フィールドでid
ではなく列name
を返します。また、行をPOST
/PUT
/PATCH
するエンドポイントは、values
フィールドでid
ではなく列name
を必要とします。PATCH
エンドポイントで、スパース更新を使用できるようになりました。スパース更新とは、更新する必要のある列値だけを指定できることを意味します(以前のバージョンでは、全ての列値を指定する必要がありました)。複数選択型の列のように、値のリストを使用して列を更新する場合は、全ての値を含むリストを指定する必要があります。列の値を削除するには、リクエスト内でその列の値をnull
として指定する必要があります。PATCH
エンドポイントを優先し、行のセルをget
/update
/delete
するエンドポイントを削除しました。idSourceColumn
を使用できるようになりました。このフィールドを使用すると、行IDが格納されているCSVファイル内の列を指定できます。新しい行を既存の行の新しい値とともにインポートするには、新しい行の行IDには単に0
を指定し、既存の行には有効な行IDを指定できます。詳細については、以下の「インポート」セクションをご参照ください。さらに、JSON形式のオプションに含まれる列マッピングのターゲットフィールドで、列の名前またはIDを使用することもできます。