Openflow Connector for HubSpot を設定する

注釈

このコネクタは、 Snowflakeコネクタ規約 に従うものとします。

このトピックでは、 Openflow Connector for HubSpot を設定する手順について説明します。

前提条件

  1. Openflow Connector for HubSpot について を確認してください。

  2. :doc:`/user-guide/data-integration/openflow/setup-openflow-byoc`または:doc:`Openflow のセットアップ - Snowflake デプロイメント</user-guide/data-integration/openflow/setup-openflow-spcs>`があることを確認してください。

  3. Openflow - Snowflake Deployments を使用する場合、:doc:`必要なドメインの構成</user-guide/data-integration/openflow/setup-openflow-spcs-sf-allow-list>`を精査し、:ref:`label-openflow_domains_used_by_openflow_connectors_hubspot`コネクタに必要なドメインへのアクセス許可を付与していることを確認してください。

認証情報を取得する

HubSpot 管理者として、 HubSpot プライベートアプリトークンを生成するか、 HubSpot アカウントで作成します。これにより、 HubSpot API に対するリクエストを認証することができます。

  1. HubSpot アカウントにログインします。

  2. 上部のナビゲーションバーで歯車のアイコンを選択し、 Settings に移動します。

  3. 左側のナビゲーションで、 Integrations » Private Apps に移動します。

  4. Create a private app を選択します。

    1. アプリの名前を入力します。

    2. Scopes タブに移動します。

    3. 作成する API リクエストに必要なスコープを選択します。API リクエストに必要なスコープを探すには、 スコープ をご参照ください。

    4. Create app を選択します。

    5. 各エンドポイントに対して行う API リクエストに必要なスコープを設定します。

  5. アクセストークンを表示するには、 View access token を選択します。トークンをコネクタパラメーターに貼り付けるか、安全に保存します。

Snowflakeアカウントを設定する

Snowflakeアカウント管理者として、以下のタスクを実行します。

  1. 新しいロールを作成するか、既存のロールを使用して データベース権限 および ビュー権限 を付与します。

  2. タイプを SERVICE として、新しいSnowflakeサービスユーザーを作成します。

  3. Snowflakeサービスユーザーに、前の手順で作成したロールを付与します。

  4. ステップ2のSnowflake SERVICE ユーザーを key-pair auth で構成します。

  5. Snowflakeではこの手順を強く推奨します。Openflowがサポートするシークレットマネージャ（AWS、Azure、Hashicorpなど）を構成し、公開キーと秘密キーを秘密ストアに格納します。

    注釈

    何らかの理由でシークレットマネージャを使用したくない場合は、組織のセキュリティポリシーに従って、キーペア認証に使用するパブリックキーとプライベートキーファイルを保護する責任があります。

    1. シークレットマネージャーを構成した後、認証する方法を決定します。AWS 上では、Openflowに関連付けられた EC2 インスタンスロールが推奨されます。こうすることで、他の秘密を永続化する必要がなくなるからです。

    2. Openflowで、右上のハンバーガーメニューから、このシークレットマネージャーに関連付けられたパラメータープロバイダーを構成します。Controller Settings » Parameter Provider に移動してから、パラメーター値を取得します。

    3. この時点で、すべての認証情報を関連するパラメーターパスで参照することができるため、機密性の高い値をOpenflow内で永続化する必要はありません。

  6. 他のSnowflakeユーザーが、コネクタによって取り込まれた生の取り込みドキュメントやとテーブルへのアクセスを必要とする場合は（Snowflakeでのカスタム処理のためなど）、それらのユーザーにステップ1で作成したロールを付与します。

  7. 取り込んだデータを格納するコネクタ用に、Snowflakeでデータベースとスキーマを作成します。最初のステップで作成したロールに以下の データベース権限 を付与します。

    CREATE DATABASE hubspot_destination_db;
CREATE SCHEMA hubspot_destination_db.hubspot_destination_schema;
GRANT USAGE ON DATABASE hubspot_destination_db TO ROLE <hubspot_connector_role>;
GRANT USAGE ON SCHEMA hubspot_destination_db.hubspot_destination_schema TO ROLE <hubspot_connector_role>;
GRANT CREATE TABLE, CREATE VIEW ON SCHEMA hubspot_destination_db.hubspot_destination_schema TO ROLE <hubspot_connector_role>;

  8. コネクタが使用するウェアハウスを作成するか、既存のものを使用します。まずは最小のウェアハウスサイズから始め、複製するテーブルの数や転送するデータ量に応じて異なるサイズを試してみてください。テーブル数が大きい場合は、通常、ウェアハウスのサイズを大きくするよりも、 マルチクラスターウェアハウス を使用した方がスケーリングが向上します。

  9. コネクタで使用するロールを持つユーザーが、ウェアハウスを使用するために必要な権限を持っていることを確認します。権限がない場合は、ロールに必要な権限を付与してください。

    CREATE WAREHOUSE hubspot_connector_warehouse WITH WAREHOUSE_SIZE = 'X-Small';
GRANT USAGE ON WAREHOUSE hubspot_connector_warehouse TO ROLE <hubspot_connector_role>;

コネクタを設定する

データエンジニアとして、以下のタスクを実行してコネクタをインストールおよび構成します。

コネクタをインストールする

コネクタをインストールするには、データエンジニアとして次を実行します。

  1. Openflow概要ページに移動します。Featured connectors セクションで、 View more connectors を選択します。

  2. Openflowのコネクタページでコネクタを探し、 Add to runtime を選択します。

  3. Select runtime ダイアログで、Available runtimes ドロップダウンリストからランタイムを選択して Add をクリックします。

    注釈

    コネクタをインストールする前に、コネクタが取り込んだデータを格納するためのデータベースとスキーマをSnowflakeで作成したことを確認します。

  4. Snowflakeアカウント認証情報でデプロイメントを認証し、Snowflakeアカウントへのランタイムアプリケーションのアクセスを許可するよう求められたられたら、 Allow を選択します。コネクタのインストールプロセスは数分で完了します。

  5. Snowflakeアカウント認証情報でランタイムを認証します。

コネクタプロセスグループが追加されたOpenflowキャンバスが表示されます。

コネクタを構成する

  1. インポートしたプロセスグループを右クリックし、 Parameters を選択します。

  2. フローパラメーター の説明に従って、必要なパラメーター値を入力します。

フローパラメーター

このセクションでは、以下のパラメーターコンテキストに基づいて構成できるフローパラメーターについて説明します。

HubSpot ソースパラメーター

パラメーター

説明

HubSpot アクセストークン

HubSpot プライベートアプリケーションのアクセストークン。

HubSpot 宛先パラメーター

パラメーター

説明

必須

宛先データベース

データが永続化されるデータベース。Snowflakeにすでに存在している必要があります。名前は大文字と小文字を区別します。引用符で囲まれていない識別子の場合、名前を大文字で指定します。

有り

宛先スキーマ

データが永続化されるスキーマ。これはSnowflakeにすでに存在している必要があります。名前は大文字と小文字を区別します。引用符で囲まれていない識別子の場合、名前を大文字で指定します。

次の例をご参照ください。

  • CREATE SCHEMA SCHEMA_NAME または CREATE SCHEMA schema_name: SCHEMA_NAME を使用します

  • CREATE SCHEMA "schema_name" または CREATE SCHEMA "SCHEMA_NAME": それぞれ schema_name または SCHEMA_NAME を使用します

有り

Snowflake認証ストラテジー

以下を使用する場合:

  • Snowflake Openflow Deployment または BYOC:SNOWFLAKE_MANAGED_TOKEN を使用します。このトークンはSnowflakeによって自動的に管理されます。BYOC デプロイメントでは、 SNOWFLAKE_MANAGED_TOKEN を使用するために、事前に ランタイムロール が構成されている必要があります。

  • BYOC: 代わりに、BYOC では認証戦略の値として KEY_PAIR を使用できます。

有り

Snowflakeアカウント識別子

以下を使用する場合:

  • Session Token Authentication Strategy: 空白にする必要があります。

  • KEY_PAIR: データが永続化される[organization-name]-[account-name]形式のSnowflakeアカウント名。

有り

Snowflake秘密キー

以下を使用する場合:

  • Session Token Authentication Strategy: 空白にする必要があります。

  • KEY_PAIR:認証に使用される RSA プライベートキーである必要があります。

    その RSA キーは PKCS8 標準に従ってフォーマットされ、標準の PEM ヘッダーとフッターを持つ必要があります。SnowflakeプライベートキーファイルまたはSnowflakeプライベートキーのいずれかを定義する必要があることに注意してください。

無し

Snowflake秘密キーファイル

以下を使用する場合:

  • Session token authentication strategy:プライベートキーファイルは空白である必要があります。

  • KEY_PAIR:Snowflakeへの認証に使用される プライベートキーを含むファイルをアップロードします。これは、PKCS8 標準に従ってフォーマットされ、標準の PEM ヘッダーとフッターを含んでいる必要があります。ヘッダー行は -----BEGIN PRIVATE で始まります。プライベートキーファイルをアップロードするには、Reference asset チェックボックスを選択します。

無し

Snowflake秘密キーパスワード

以下を使用する場合

  • Session Token Authentication Strategy: 空白にする必要があります。

  • KEY_PAIR: Snowflakeプライベートキーファイルに関連付けられたパスワードを提供します。

無し

Snowflakeロール

以下を使用する場合

  • Session Token Authentication Strategy:Snowflakeロールを使用します。ランタイムの View Details に移動すると、Openflow UI でSnowflakeロールを見つけることができます。

  • KEY_PAIR Authentication Strategy:サービスユーザーのために構成された有効なロールを使用します。

有り

Snowflakeのユーザー名

以下を使用する場合

  • Session Token Authentication Strategy: 空白にする必要があります。

  • KEY_PAIR:Snowflakeインスタンスへの接続に使用するユーザー名を提供します。

有り

オーバーサイズ値戦略

複製中にコネクタが内部サイズ制限（16MB）を超える値を処理する方法を決定します。可能な値は次のとおりです。

  • **失敗テーブル**（デフォルト）：テーブルは永久に失敗したものとしてマークされ、そのテーブルの複製が停止します。

  • Nullの設定：値は宛先テーブルで``NULL``に置き換えられます。オーバーサイズ値を超えるテーブル内のデータが失われても許容できる場合、これを使用してテーブルの失敗を防ぎます。

無し

Snowflakeウェアハウス

クエリの実行に使用されるSnowflakeウェアハウス。

有り

HubSpot 取り込みパラメーター

パラメーター

説明

オブジェクト型

取り込むコンマ区切りの HubSpot オブジェクト型のリスト。

サポートされるオブジェクト型の値は次のとおりです。

  • 予定

  • コール

  • キャンペーン

  • カート

  • コマースの支払い

  • 通信

  • 企業

  • 連絡先

  • コース

  • ディール

  • 割引

  • メール

  • 料金

  • フィードバックの提出

  • 目標

  • 請求書

  • リード

  • 品目

  • リスト

  • 会議

  • メモ

  • オーダー

  • 郵便

  • 製品

  • 見積書

  • 見積書テンプレート

  • サービス

  • サブスクリプション

  • タスク

  • 税金

  • チケット

  • ユーザー

更新後

指定された日付または時刻以降に更新されたオブジェクトをフィルターします。このパラメーターはオプションです。

データ取り込みスケジュール

次のスケジュールまでの時間。30分や1時間など、有効な時間である必要があります。

フローを実行する

  1. プレーンを右クリックし、 Enable all Controller Services を選択します。

  2. インポートしたプロセスグループを右クリックし、 Start を選択します。コネクタがデータの取り込みを開始します。

コネクタを再構成する

コネクタのパラメーターは、コネクタがデータの取り込みを開始した後に変更できます。問題のクエリの条件が変更された場合は、以下の手順を実行して宛先テーブルのデータに一貫性があることを確認します。

  1. コネクタを停止する: すべてのOpenflowプロセッサーが停止していることを確認します。

  2. 構成設定にアクセスします:Snowflake Openflowインターフェイス内のコネクタの構成設定に移動します。

  3. パラメーターを変更する: 必要に応じてパラメーターを調整します。

  4. プロセッサーの状態をクリア：取り込み基準を変更する場合、宛先テーブルのデータを一貫させるために、最初から取り込みを開始することをSnowflakeは強くお勧めします。List Fresh HubSpot Objects プロセッサーで状態をクリアした後、コネクタは最初からすべてのオブジェクトをフェッチします。行の重複を防ぐために、宛先テーブルの手動切り捨てが必要な場合があります。

データ構造とビュー

コネクタは、Snowflakeデータベース内に次の2つの形式でデータを保存します。

生データの保存

すべての生 HubSpot データは、オブジェクト型パラメーターで指定された正確な名前でテーブルに格納されます。例:

  • オブジェクト型パラメーターで Products,Contacts,Companies を構成した場合、コネクタは PRODUCTS 、 CONTACTS 、および COMPANIES の3つのテーブルを作成します。

  • 各テーブルには HubSpot API 応答からの完全な JSON ペイロードが含まれています。

  • 生データは HubSpot からの元の構造とすべてのメタデータを保持します。

フラット化されたビュー

クエリと分析を容易にするために、コネクタはオブジェクト型ごとにフラット化されたビューを自動的に作成します。

  • 各生テーブルには、接尾辞 _VIEW が付いた対応するビューがあります。例えば、 PRODUCTS_VIEW 、 CONTACTS_VIEW 、 COMPANIES_VIEW などがあります。

  • ビューは、 JSON ペイロードからよく使用されるフィールドを抽出し、個別の列として表示します。

  • 複雑なネストされた構造は、 SQL クエリの簡略化のためにフラット化されます。