非公開アプリを使用してカスタムオブジェクトを構築する方法

Yoshi · ‎11 14, 2022

HubSpotは各アカウントに、コンタクト、会社、取引など、一連の標準CRMオブジェクトを提供します。しかし、このようなオブジェクトでは、保存する必要があるデータのタイプが反映されない場合もあります。そこで、ビジネスニーズに基づいてCRMデータを表示し、整理するためのカスタムオブジェクトを作成できます。このようなカスタムオブジェクトが特に優れているのは、他の標準CRMオブジェクトと同じ方法で、自動化やEメールテンプレートなどに使用できることです。

カスタムオブジェクトAPIを使用して、カスタムオブジェクトのスキーマ、プロパティー、および他のCRMオブジェクトとの関連付けを定義できます。呼び出しは、PostmanなどのAPIテストアプリケーションを使用して行えます。このチュートリアルではこの方法を使用します。

非公開アプリを使用した認証

カスタムオブジェクトの作成には認証が必要です。認証は非公開アプリまたはOAuthを使用して行えます。このAPIリクエストを認証するには、非公開アプリを構築しましょう。非公開アプリは、アカウントデータへのアクセスの範囲を指定された認証方法（以下スコープ）です。そのため、アクセストークンが漏洩していても、機密データが漏洩するリスクがありません。開発者はこのアプリがアクセス可能なスコープをいつでも変更できます。

アカウントのメインメニューで、歯車マークの設定アイコンをクリックします。左側のサイドバーで［連携］をクリックし、［非公開アプリ］を選択します。

［非公開アプリを作成］をクリックします。アプリにCustom Object Authenticationなどの名前を付けます。

［スコープ］タブをクリックします。［スコープ］タブは呼び出しを成功させるのに重要です。この非公開アプリでは、次のスコープが必要です。

crm.objects.custom.write
crm.objects.custom.read
crm.schemas.custom.write
crm.schemas.custom.read

これらのスコープは［標準］ドロップダウンに入っています。見つかるまで下にスクロールして、横にあるチェックボックスをクリックします。この操作で、この非公開アプリにカスタムオブジェクトレコードを読み書きする機能が付与されます。また、新しいカスタムオブジェクトを作成する呼び出しである、新しいカスタムオブジェクトスキーマを作成する機能も付与されます。

ここで、右上隅の［アプリを作成］をクリックします。ポップアップウィンドウで［作成を続行］をクリックします。次に、新しいポップアップウィンドウで［トークンを表示］をクリックし、［コピー］をクリックして非公開アプリのアクセストークンをコピーします。これで、API呼び出しの使用に必要な認証が得られました。

PostmanでのAPIエンドポイントリクエスト

Postmanを使用すると、独自のアプリをセットアップしなくても自分のAPIをリクエストが出来ます。Postmanでの操作を行うために必要なものは、APIエンドポイント、認証情報、およびカスタムオブジェクトJSONスキーマだけです。新しいカスタムオブジェクトを作成するには、POSTリクエストをhttps://api.hubapi.com/crm/v3/schemasに送信します。［Bearer Token］認証タイプを選択します。［Token］フィールドに自分のアクセストークンを貼り付けます。

トークンとエンドポイントを追加したら、カスタムオブジェクトスキーマの構築を始めましょう。これはリクエストの本体で渡されます。

カスタムオブジェクトスキーマの構築

カスタムオブジェクトスキーマには複数の必須プロパティーがあります。より深く理解するため、開発者ドキュメントを確認してください。この例では、できるだけ簡単なスキーマにしましょう。カスタムオブジェクトスキーマの主な3つのセクションは以下のとおりです。

カスタムオブジェクト名
カスタムオブジェクトのプロパティー
カスタムオブジェクトと他のCRMオブジェクトとの関連付け

オブジェクトを作成すると、その後はその名前とラベルを変更できないことに注意してください。カスタムオブジェクトスキーマには少なくとも1つのプロパティーが必要です。他のプロパティーはカスタムオブジェクトの構築後に追加できます。

nameはカスタムオブジェクトの内部ラベルで、小文字で書かなければならず、スペースを含んではなりません。名前が複数の単語の場合は、単語間にアンダーバーを追加できます。ラベルは人間が読めるバージョンのカスタムオブジェクト名であり、アカウントに表示されます。単数バージョンと複数バージョンの両方を作成します。

primaryDisplayPropertyは、個々のカスタムオブジェクトレコードに名前を付けるために使用するプロパティーです。secondaryDisplayPropertiesは、primaryDisplayPropertyの下の個々のレコードに表示されるプロパティーです。requiredPropertiesは、新しいカスタムオブジェクトレコードを構築するときに必要なプロパティーです。searchablePropertiesは、HubSpotでの検索のためにインデックス登録されるプロパティーです。

各カスタムオブジェクトには少なくとも1つのプロパティーが必要です。プロパティーキーの内部に、さまざまなプロパティーフィールドを含む配列を作成します。各プロパティーにはname、label、type、fieldTypeを含める必要があります。string、number、date、enumerationなど、選択できるtypeが複数あります。typeをenumerationに設定する場合は、選択肢となる値を含める必要があります。

最後の必須セクションはassociatedObjectsです。この値も配列であり、標準CRMオブジェクトや、作成済みの他のカスタムオブジェクトへの関連付けを含めることができます。

ここに、「Boat」という名前のカスタムオブジェクトを構築するためのJSONスキーマを示します。

Boatカスタムオブジェクトスキーマ　JSON

{
  "name": "boat",
  "labels": {
    "singular": "Boat",
    "plural": "Boats"
  },
  "primaryDisplayProperty": "model",
  "secondaryDisplayProperties": [
     "make"
],
  "searchableProperties": [
     "year",
     "make",
     "hin",
     "model"
],
  "requiredProperties": [
     "year",
     "make",
     "hin",
     "model"
  ],
  "properties": [
    {
      "name": "condition",
      "label": "Condition",
      "type": "enumeration",
      "fieldType": "select",
      "options": [
        {
          "label": "New",
          "value": "new"
        },
        {
          "label": "Used",
          "value": "used"
        }
      ]
    },
    {
      "name": "date_received",
      "label": "Date received",
      "type": "date",
      "fieldType": "date"
    },
    {
      "name": "year",
      "label": "Year",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "make",
      "label": "Make",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "model",
      "label": "Model",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "hin",
      "label": "HIN",
      "type": "string",
      "hasUniqueValue": true,
      "fieldType": "text"
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "mileage",
      "label": "Mileage",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "price",
      "label": "Price",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "notes",
      "label": "Notes",
      "type": "string",
      "fieldType": "text"
    }
  ],
  "associatedObjects": [
    "CONTACT"
  ]
}

ここで、このスキーマをPostmanに追加しましょう。［Body］タブで必ず［raw］オプションを選択します。言語をJSONに設定します。自分のJSONスキーマを貼り付けて、右上隅の青い［Send］ボタンをクリックします。リクエストが成功すると、「201 Created」ステータスが表示されます。

最後に、アカウントに戻ってカスタムオブジェクトが作成されたことを確認しましょう。これで、メインメニューにカスタムオブジェクトのリストが表示されるようになります。［コンタクト］をクリックして、［カスタムオブジェクト］にカーソルを合わせます。フライアウトウィンドウが表示され、そこにアカウントのカスタムオブジェクトがリストされます。新しいカスタムオブジェクト「Boat」が作成されました。

まとめ

カスタムオブジェクトは他のCRMオブジェクトと同様に機能します。レコードを一括で追加するためCSVでデータをインポートすることも、［作成］ボタンを使用して新しいレコードを一度に1つずつ追加することもできます。ビジネスニーズに合わせて適切なカスタムオブジェクトを定義し、CMSページからカスタムワークフローまで、あらゆる場所で使用できます。

何よりも、非公開アプリにより安心感が得られます。アクセストークンが漏洩しても、機密情報の漏洩を心配する必要はなくなります。スコープによってアカウントの他の部分へのアクセスが制限されるからです。行われる全ての呼び出しを追跡することもできます。カスタムオブジェクトの安全かつ確実な構築を始めましょう。

日本語ブログ

非公開アプリを使用してカスタムオブジェクトを構築する方法