Hubspotのカスタムコードを使ってカスタムオブジェクトとコンタクトを関連付ける

この記事で分かること

Hubspotのワークフローを使うと「新規作成」したオブジェクトを既存のオブジェクトに関連付けることができます。しかしワークフローでは既存のオブジェクト同士を関連付けることができません。

このようなときに、カスタムコードを使うと既存のオブジェクト同士を関連付けることができます。ここではその方法をまとめます。

必要なこと

• Operations Hub Professional以上の契約
• あった方がいいこと
  • カスタム コード ワークフロー アクション のスキル
  • 【新機能】カスタム コード アクションでPythonを使用可能です のスキル

手順

1. API Keyを取得する
2. 関連付けラベルを作成する
3. オブジェクトを関連付ける

API Keyを取得する

カスタムコードを作るためには、まず API Key を作成する必要があります。そのためには設定画面から「非公開アプリ」を作成しましょう。名前やロゴ、説明は分かりやすいものになっていれば何でも大丈夫です。

ただし「スコープ」は適切に設定してあげる必要があります。

スコープ

スコープはやりたいことに応じて適切に設定します。よく使うものとしては crm.objects.deals のようにオブジェクトを編集するようなものや、crm.objects.owners のような担当者の情報を取得するものがあります。

今回は取引のタスクを編集するので、取引に関するREAD/WRITEの権限チェックを入れています。これがないと画像のようなエラーが起きてしまいます。他のオブジェクトのタスクを編集したいときは随時他の権限を追加してください。

• crm.objects.contacts.read
• crm.objects.contacts.write

API Keyをコピーする

非公開アプリを作成したら次にAPI Keyをコピーします。カスタムコードではこちらのコピーした値を使用します。これを漏らすとHubspotの情報漏洩に繋がるため、厳重に管理します。

関連付けラベルを作成する

通常のオブジェクトでは必要ありませんが、カスタムオブジェクトの場合は「関連付けラベル」を自分で作成する必要があります。ここでは設定 > オブジェクト > カスタムオブジェクトのページから、「クラウドファンディング」カスタムオブジェクトと「コンタクト」の関連付けラベルを作成しています。

このとき「内部名」を設定してあげることで、後のカスタムコードで使うことができます。デフォルトで用意されているオブジェクト同士の内部名は contact_to_company のような形式になっています。それに合わせて、今回は contact_to_crowdfundings にしました。

オブジェクトを関連付ける

カスタムコードを使ってオブジェクト同士を関連付けるには、Associations APIを使います。今回はこのような汎用的な create_association 関数を作成し、main から呼び出す形にしました。

このコードでは BatchInputPublicAssociation を使って2つのオブジェクトを関連付けるための準備をして、associations.batch_api.create で実際の関連付けを行っています。このとき f"{object_type1}_to_{object_type2}" という形で、先ほど作成した関連付けラベルの内部名を使用できるようになっています。

def create_association(hubspot, object_id1, object_id2, object_type1, object_type2):
  batch_input_public_association = BatchInputPublicAssociation(inputs=[{
    "from": { "id": object_id1 },
    "to": { "id": object_id2 },
    "type": f"{object_type1}_to_{object_type2}"
  }])
  api_response = hubspot.crm.associations.batch_api.create(
    from_object_type=object_type1,
    to_object_type=object_type2,
    batch_input_public_association=batch_input_public_association
  )
  return api_response

mainからの呼び出し

呼び出す際はこのように引数を指定します。左から順に以下のようになっており、④と⑤が f"{object_type1}_to_{object_type2}" で結合されて、関連付けラベルの内部名になります。他のオブジェクトとの関連付けも、同様にラベルを作成してからAssociations API を使うことで実現できます。

1. hubspot オブジェクト。APIを呼び出すためのオブジェクト
2. コンタクトのID
3. カスタムオブジェクトのID
4. コンタクトのオブジェクトタイプ
5. カスタムオブジェクトのオブジェクトタイプ

import os
from hubspot import HubSpot
from hubspot.crm.associations import BatchInputPublicAssociation, ApiException
...
def main(event):
  hubspot = HubSpot(access_token=os.getenv('PRIVATE_APPLI_KEY'))
  try:
    create_association(hubspot, 12345, 67890, "contact", "crowdfundings")
  except ApiException as e:
    print(e)
    raise

  return {
    "outputFields": {
    }
  }

発生する可能性があるエラー

内部名が間違っている

関連付けようとしたらラベルがないため失敗したときのエラーです。contact_to_crowdfundings なんて存在しないと言われています。

'message': 'contact_to_crowdfundings is not a valid association type '

権限が足りない

API Keyの権限が足りないために起きているエラーです。スコープが不足していると言われています。

"message":"The scope needed for this API call isn't available for public use. If you have questions, contact support or post in our developer forum."