f:id:sugimomoto:20210301114934p:plain

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

2021年1月28日にHubSpot API V3で関連データ（Association）の取得方法に変更がありました。

今回の記事では「HubSpot APIそのものはどういった変更が行われたのか？」と合わせてCData Driver での影響内容・変更点について解説したいと思います。

正式なリファレンスは以下のページをどうぞ。

developers.hubspot.com

API Update 内容

今回の変更内容は、関連データの取得、つまりHubSpot の以下のような関連データをAPIで取得する場合の共同の変更です。

f:id:sugimomoto:20210301114626p:plain

HubSpot API V3の場合、例えば会社データ（Companies）に関連するコンタクト担当者（Contacts）を取得するには、以下のようにクエリパラメータ「?associations=contacts」で指定したリクエストを送ります。

これで今までであれば、以下のようにどんなに関連データが多くても、一回のレスポンスで取得することができました。

GET https://api.hubapi.com/crm/v3/objects/companies?associations=contacts HTTP/1.1
Host: api.hubapi.com
Authorization: Bearer XXXX
Accept: application/json

{
    "results": [
        {
            "id": "3162976988",
            "properties": {
                "createdate": "2020-03-11T16:07:48.650Z",
                "domain": "wells-torres.demospot.org",
                "hs_lastmodifieddate": "2021-01-22T20:43:43.183Z",
                "hs_object_id": "3162976988",
                "name": "Wells-Torres"
            },
            "createdAt": "2020-03-11T16:07:48.650Z",
            "updatedAt": "2021-01-22T20:43:43.183Z",
            "associations": {
                "contacts": {
                    "results": [
                        {
                            "id": "1",
                            "type": "company_to_contact"
                        },
                        {
                            "id": "51",
                            "type": "company_to_contact"
                        },
            (この後にも続々レコードが存在)
                    ]
                }
            },
            "archived": false
        }
    ]
}

しかしながら、最新のAPIでは一回のリクエストで取得できる関連レコードの件数が100件に制限されており、100件以上関連レコードが存在する場合は「paging」オブジェクトを返却し、再度リクエストを要求しないといけない仕様になっています。

{
    "results": [
        {
            "id": "3162976988",
            "properties": {
                "createdate": "2020-03-11T16:07:48.650Z",
                "domain": "wells-torres.demospot.org",
                "hs_lastmodifieddate": "2021-01-22T20:43:43.183Z",
                "hs_object_id": "3162976988",
                "name": "Wells-Torres"
            },
            "createdAt": "2020-03-11T16:07:48.650Z",
            "updatedAt": "2021-01-22T20:43:43.183Z",
            "associations": {
                "contacts": {
                    "results": [
                        {
                            "id": "1",
                            "type": "company_to_contact"
                        },
                        {
                            "id": "51",
                            "type": "company_to_contact"
                        },
            (この後にも続々レコードが存在するが、100件まで)
                    ],
                    "paging": {
                        "next": {
                            "after": "MC0yLTg4NQ%3D%3D",
                            "link": "https://api.hubapi.com/crm/v3/objects/0-2/3162976988/associations/0-1?portalId=5692228&after=MC0yLTg4NQ%3D%3D"
                        },
                        "prev": null
                    }
                }
            },
            "archived": false
        }
    ]
}

そのため、もしPaginationの処理をプログラムで実装していない場合は、最新のAPIだと100件までしかデータを取得することができません。

オブジェクトの追加なので、既存のライブラリやプログラムが壊れるといったことはあまり無いとは思いますが、注意しましょう。

なお、上記エンドポイント以外にも、関連データを取得するために利用するエンドポイントはすべて対象です。

GET /crm/v3/objects/{objectType}
GET /crm/v3/objects/{objectType}/{objectId}
GET /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}
POST /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/read
PUT/crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}