こんにちは。CData Software Japan の色川です。

今年もいよいよ年末の雰囲気がただよってきましたね。年末といえばQiita のアドベントカレンダーですね。もちろん今年もCData のアドベントカレンダーはにぎやかです。

ちょうど最近「HubSpot のコンタクトに添付されているファイルをダウンロードして連携したいのですが」というご相談を幾つか続けていただきました。このシナリオは「HubSpot API の特徴とCData を利用する便利さが分かりやすい話」だと思います。そういった話はCData アドカレのネタにピッタリです。というわけで、この記事では「CData Arc でHubSpot のコンタクトに添付されているファイルのダウンロードを自動化する方法」についてご紹介します。

この記事は、CData Software Advent Calendar 2025 11日目の記事です。

HubSpot

HubSpot は、世界135か国以上、27万社を超える企業が活用しているクラウドベースのマーケティングプラットフォームです。

業界最多級のデータソースサポートを誇るCData Drivers の中でもHubSpot はグローバルで人気の高いデータソースで、今年HubSpot Driverについて取り上げたこちらの記事も日本市場に限らず活用いただいています。

HubSpot API での「添付ファイル」の扱い

HubSpot をCRM などの業務で活用していると「コンタクト（Contacts）に添付されたファイルを取得したい（取得して他のデータソースやシステムに連携したい）」という場面も多いのではないでしょうか。

ここでポイントの1つとなるのは「HubSpot API での添付ファイルの扱い」です。「コンタクト（Contacts）に添付されたファイル」を例にすると、Contacts のエンドポイント（オブジェクト）からAttachments 的な属性として直接取得できるわけでなく、複数のオブジェクトをまたいだ「Association（関連付け）」モデルとなっているのがHubSpot API の特徴の1つと言えるかと思います。

この「コンタクト（Contacts）に添付されたファイル」を例にすれば「対象のContacts と関連するNotes（Engagments Notes） を取得し、そのNotes に含まれるAttached file のId を取得する」ような多段のプロセスが必要です。

なおHubSpot API では、この記事の時点で主力といえるv3 API 以外に、次世代のv4 API など複数のバージョンが提供されていますが、添付ファイルのダウンロードが可能なFiles API はv3 API の利用が必要です。この記事でCData HubSpot Driver を通じて、HubSpot に接続する際は、Schema をHubSpotV3（デフォルト）で構成しています。

CData HubSpot Driver での考え方

HubSpot API をSQL でアクセスできるCData HubSpot Driver を利用すれば「対象のContacts と関連するNotes を取得し、そのNotes に含まれるAttached file のId を取得する」ような多段のプロセスもJoin 一発で解決することができます。

例えば「Contacts からexample@example.com のメールアドレスを持つレコードのId を取得」して「取得したId に一致するContactsId を持つレコードのEngagementsNotesId をContactsToNotesAssociations から取得」して「取得したEngagementsNotesId の値に一致するId を持つレコードのAttached file IDs をEngagementsNotes から取得」したい場合でも、以下のようなSQL で一撃です。

SELECT
  en.[Attached file IDs]
FROM Contacts AS c
  INNER JOIN ContactsToNotesAssociations AS cna
    ON c.Id = cna.ContactsId
  INNER JOIN EngagementsNotes AS en
    ON cna.EngagementsNotesId = en.Id
WHERE c.Email = 'example@example.com'

このようなシナリオは、CData HubSpot Driver の強力な利便性を感じていただける分かりやすい例の1つかと思います。

CData Arc でメールアドレスに一致するContact の添付ファイルをダウンロードする連携フロー

CData 製品の中で「データ連携の自動化（Automation）」を担う「CData Arc」では、業界最多級のデータソースサポートを誇るCData Drivers をシームレスに利用できる「CData コネクタ」を標準で備えています。

以下では「ユーザーにエントリ用のHTML Form を提供するForm コネクタ」でのメールアドレス入力をフローの起点として「入力されたメールアドレスを持つContacts に（関連するContactsToNotesAssociations から取得できるEngagementsNotesId に）紐づくAttached file IDs」をLookup アクションで取得して「Attached file ID を条件にHubSpot のFile API でダウンロードするDownloadFile ストアドプロシージャ」をExecute Stored Procedure アクションで実行するフローの実現イメージをご紹介します。なお、この記事では手軽にForm コネクタを起点としていますが、例えば「Contacts を定期的にSelect するアクションを起点としたフロー」でも「HubSpot からのContacts 更新のWebhook を（を受信できるWebhook コネクタを）起点としたフロー」でも大枠の考え方としては同じイメージでご検討いただけるかと思います。

Form コネクタ

Arc のForm コネクタは、ユーザーがHTML Form に記入・送信したデータをArc のフローへのインプットとして扱うことが出来るエンドポイント（HTML From を提供するURL）を生成できるコネクタです。

メールアドレスを入力させるためのForm であれば設定もシンプルで以下のようなコネクタ設定で、HTML Form を提供するURL（エンドポイント）を生成することができます。

上記のようなURL（エンドポイント）からエントリ（Submit）されると、Arc のフローには以下のようなインプットファイルが生成されます。

CData コネクタ（Lookup アクション）

CData コネクタを含め、Arc のデータソース系コネクタが備えるLookup アクションは、対象のデータソースから指定した条件に合致する値を取得し、その値をフロー内の既存のArc メッセージに挿入（追加）できるアクションです。

この記事では「Form コネクタで入力されたメールアドレスを持つContacts に（関連するContactsToNotesAssociations から取得できるEngagementsNotesId に紐づく）Attached file IDs」をLookup アクションのクエリモードを利用して取得するように構成しました。

SELECT
  en.[Attached file IDs]
FROM
  Contacts AS c
  INNER JOIN ContactsToNotesAssociations AS cna
    ON c.Id = cna.ContactsId
  INNER JOIN EngagementsNotes AS en
    ON cna.EngagementsNotesId = en.Id
WHERE
  c.Email = ${XPATH:/Items/form/Email}

CData コネクタ（Execute Stored Procedure アクション）

Arc でHubSpot の（コンタクトなどに添付されている）添付ファイルをダウンロードする場合、DownloadFile ストアドプロシージャを利用します。Arc でのストアドプロシージャの実行は「Execute Stored Procedure アクション」を利用します。オンデマンドでのテスト実行などもサポートしていますので、フロー開発もスムーズです。

DownloadFile ストアドプロシージャでは、添付ファイルをFileStream として取得することもできますし、指定したLocalPath にファイルの実体として出力することもできます。いずれのパラメータも指定しない場合、ストアドプロシージャ実行の結果セット（Result Set Columns）内のFileData に（ファイル内容をBase64 エンコードした）文字列として出力されます。また結果セット内のURL には一時的にファイルアクセス可能な署名済みのURL が含まれますので、そのURL からGET する流れでもファイルを取得することが出来るでしょう。ファイルの内容や実体をどのような構成・流れでダウンロードするかは、それぞれのフローの目的や用途に応じて選択してください。

XML Map コネクタ

Lookup アクションで取得した「Attached file IDs」と、Execute Stored Procedure アクションでDownloadFile ストアドプロシージャが求めるパラメータをマッピングするのがXML Map コネクタです。この記事でのSize パラメータのように特に指定が不要なパラメータはNull として渡るように「空をnull として扱う」を活用するのもポイントの1つです。

フローイメージ

ここまでで「Form から入力されたメールアドレスを持つContacts から辿れる（Contacts に関連するContactsToNotesAssociations から取得できるEngagementsNotesId に紐づくAttached file IDs を持つ）ファイルをダウンロードする」フローが出来上がりです。

まとめ

この記事では「CData Arc でHubSpot のコンタクトに添付されているファイルのダウンロードを自動化する方法」についてご紹介しました。この記事で作成したフローでは、CData HubSpot Driver の強力な利便性と、CData Arc でのCData HubSpot Driver でのシームレスな利用についてイメージいただけたかと思います。

CData Arc はシンプルで拡張性の高いコアフレームワークに、豊富なMFT・EDI・エンタープライズコネクタを備えたパワフルな製品です。CData Drivers との組み合わせで275を超えるアプリケーションへの連携を実現できます。

皆さんのつなぎたいシナリオでぜひ CData Arc を試してみてください。
CData Arc - セキュアなデータ連携とマネージドファイル転送（MFT）

製品を試していただく中で何かご不明な点があれば、テクニカルサポートへお気軽にお問い合わせください。
CData Software Japan - Support Form

この記事では CData Arc™ 2025 - 25.3.9469.0 を利用しています