こんにちは！　CData Software Japan リードエンジニアの杉本です。

今回はグローバルでも国内でも人気のSaaS型CRM HubSpot のCData Driver「CData HubSpot Driver」のUpdateをお知らせします。

HubSpot CRM API v3 について

2020年3月にHubSpotでは新しいバージョンのAPI「v3」がリリースされていました。

developers.hubspot.com

このUpdateのポイントは大きく2つあります。

• 検索・フィルタリング・並び替えのサポート
• CRMインポートエンドポイントのサポート

前者はデータを取得・クエリする際の効率を大幅に向上させました！

後者は大量のデータをAPI経由で登録する際に便利な機能です。

developers.hubspot.com

まず以前までのAPIとどんな違いがあるのか、APIレベルで見てみましょう。

V2 APIと V3 APIのデータ取得方法の違い

例えば以前までのエンドポイント V2 で企業情報を取得する場合、以下の「Get all companies」を利用する必要がありました。

ただ、「Get all companies」はその名の通り、全企業を取得するために使われるケースのみを想定しており、例えば特定の地域の企業を取得したり、業種で並び替えをしたり、といったことができませんでした。

legacydocs.hubspot.com

それが新しいV3 APIではSearch機能がサポートされ、柔軟なフィルター条件、並び替え、カラムの選択がサポートされました！

developers.hubspot.com

以下のようなfilterリクエストを含めることで一致・不一致、部分一致、以上、以下、AND・ORなど柔軟なフィルター条件を指定できます。素晴らしいですね。

curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "filterGroups":[
      {
        "filters": [
          {
            "propertyName": "firstname",
             "operator": "EQ",
             "value": "Alice"
          },
          {
            "propertyName": "lastname",
            "operator": "NEQ",
            "value": "Smith"
          }
        ] 
      },
      {
        "filters": [
          {
            "property": "enum1",
            "operator": "HAS_PROPERTY"
           }
         ]
       }
    ]
  }'

さらにSortもサポートしたので、最新のデータ、古いデータといった並び替えも可能です。

curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "sorts": [
      {
        "propertyName": "createdate",
        "direction": "DESCENDING"
      }
    ]
  }'

また、以前までは以下のような「Create a new contact」のAPIなどを利用して一件一件データの登録リクエストを送る必要があったのですが、

legacydocs.hubspot.com

今回のバージョンアップではCSVをアップロードして一括処理を行うAPIがサポートされ、一括データ登録の処理効率が大幅にアップしています！

developers.hubspot.com

V3 APIで注意したいこと

以下のURLにも記載がありますが、 Engagements、Contact Lists はまだV3でエンドポイントが提供されていません。また、いくつかのエンドポイントはSearchが使えません。この辺は要注意ポイントですね。

developers.hubspot.com

• Search functionality is limited to one request per second
• "engagements", including "tasks", "calls", "emails", and "notes" aren't supported in Search
• We are missing the Engagements and Contact Lists endpoints - use the existing ones for now.
• Secondary Identifiers - we’ll be adding this shortly—hang tight.

＃ CData HubSpot Driverでの変更ポイント

それではCData HubSpot Driverでの変更ポイントも解説していきましょう。

www.cdata.com

CRM API V3の改善（V1およびV2と比較して）

CData HubSpot Driverでの主な変更ポイントは以下のとおりで、HubSpot APIの変更ポイントはほぼ押さえた形で利用できるようになっています。各種演算子をサポートしたのは大きいですね！

• 主要テーブルのフィルタリング機能のサポート。サポートされている演算子には、=、！=、>、<、<=、> =が含まれます。
• ANDとORの組み合わせを使用したフィルタリング機能のサポート。サーバー側では最大2つのOR演算子がサポートされ、これらの各演算子は内部で最大2つのAND演算子をサポートします。
• 主要テーブルの並べ替え機能。APIによるソートがサポートされているのは1列のみです。
• 「バッチ」操作のサポート（バッチ挿入、バッチ更新、バッチ削除）

ちなみに主要テーブルとは以下の7つのテーブルなので要注意です。

• Companies
• Contacts
• Deals
• Products
• Tickets
• LineItems
• Quotes

CRM APIV3の制限

制限事項は以下のとおりです。

• PageSizeは100より大きくすることはできません。
• フィルタリングは、返される行数が10,000未満の場合にのみ使用できます。クエリに対して返される行がさらにある場合は、CData Driver内部で最初にすべての行が取得された後、メモリ上でフィルタリングが行われます。
• フィルタリングリクエストまたはソートリクエストのいずれかを発行する場合、1秒あたり1リクエスト以下が許可されます。
• 一部の列（「CreatedAt」や「UpdatedAt」など）はフィルターをサポートしていません。

なお、CData HubSpot Driverではこの変更点およびまだ未対応のエンドポイントの存在を勘案し、新しいスキーマをユーザーが選べる形で追加開発・提供することになりました。

cdn.cdata.com

CData HubSpot Driver で新しいAPIの使い方

それでは実際にCData HubSpot Driver を使ってみましょう。ODBCを例にしていますが、すべてのテクノロジー（ODBC・JDBC・ADO.NET・Excel Add-inなど）で共通です。

接続設定を行う際に「Schema」のプロパティで「HubSpotV3」を選ぶことで、最新のAPIに準拠したデータモデルが利用可能になります。

もし古いバージョンのデータモデルを利用したい場合は「HubSpot」を選んでください。

設定後、「接続のテスト」をクリックします。

クリック後、ブラウザが立ち上がるので、対象のHubSpotアカウントに接続すればOKです。

あとは、Power BIやTableauなど任意のツールで接続して、データを確認できます。

スキーマの名称がHubSpotV3で表示されていれば、正常に切り替わっています。

具体的な変更ポイントも見てみましょう。

例えば企業を取得する「Companies」テーブルは、以前までは以下のクエリしかサポートしていませんでした。

http://cdn.cdata.com/help/DHF/jp/jdbc/pg_hubspottable-companies.htm

SELECT * FROM Companies 

SELECT * FROM Companies WHERE CompanyId = '123456789'

最新バージョンのデータモデルを利用すると、前述の通り以下のように様々な条件でクエリを書けるようになっています。

cdn.cdata.com

SELECT * FROM Companies WHERE [Associated Deals] > 1 AND [Recent Deal Close Date] < '2020-01-31'

SELECT * FROM Companies WHERE [Associated Contacts] < 50 OR [Last Contacted] > '2020-01-01 15:00:00'

このクエリの実行結果をFiddler経由で見てみると、以下のようにちゃんとfilterのクエリが記述され、リクエストされていることがわかりますね。

また、一括データ登録もINSERT INTO ステートメントを利用することで実現できます。

cdn.cdata.com

INSERT INTO Contacts#TEMP([First Name],[Last Name])VALUES('CData','Sample1');

INSERT INTO Contacts#TEMP([First Name],[Last Name])VALUES('CData','Sample2');

INSERT INTO Contacts#TEMP([First Name],[Last Name])VALUES('CData','Sample3');

INSERT INTO Contacts ([First Name],[Last Name]) SELECT [First Name],[Last Name] FROM Contacts#TEMP;

より便利になったCData HubSpot Driverを是非試してみてください！　

もしわからないことがあれば、無償のテクニカルサポートまでお気軽にどうぞ。

www.cdata.com

関連コンテンツ