Zum Hauptinhalt springen
最終更新日: 2025年10月8日
この機能を使用するには、HubSpotからの承認が必要です。アプリオブジェクトへのアクセスの申請に関心がある場合、または機能について詳しく知りたい場合は、こちらのフォームをお送りください。
概念実証アプリを作成する方法を説明します。この方法では、開発者テストアカウントでテストおよび使用できるアプリオブジェクトを設定します。
1

HubSpot CLIの最新バージョンをインストールする

統合アプリを作成するには、HubSpot CLIの最新ベータ版が必要です。ターミナルウィンドウで次のコマンドを実行します。
npm install -g @hubspot/cli@next
CLIのバージョンは7.4.4-beta.0以降である必要があります。hs --versionを実行すると、CLIのバージョンを確認できます。
2

開発者アカウントを認証する

次のコマンドを実行して開発者アカウントを認証する必要があります。
hs auth
  • 画面の指示に従ってアカウントでパーソナル アクセス キーを生成し、このキーをコピーしてターミナルに貼り付け、設定を保存します。
  • このベータ期間中は、このアカウントをCLIの既定にすることが推奨されます。これにより、ベータに登録したアカウントのアクセスで発生する可能性があるエラーを回避できます。
3

新しいボイラープレートプロジェクトを作成する

ターミナルで以下のコマンドを実行し、現在互換性のある機能またはアプリオブジェクト参照スキーマを使用して新しいプロジェクトアプリおよびマーケットプレイスアプリを作成します。
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

新しく作成したプロジェクトを設定し、開発者アカウントにアップロードする

プロジェクトフレームワークは、UIまたはAPIで以前に設定されたアプリ機能を、ソース コード ファイル（通常は<file-name>-hsmeta.json設定ファイルとして定義されるファイル）に移動します。アプリ機能は、必要に応じて、メインの/src/appディレクトリーのサブフォルダーと他の設定ファイルの組み合わせを使用して作成されます。プロジェクトを設定するには、次のようにします。
  • ローカル（または別の非本番）OAuthサーバー設定に基づいて、1つ以上の有効なリダイレクトURLをapp-hsmeta.jsonファイルに追加します。

​
注：

最初に、OAuth Node.jsのサンプルを使用してローカルで実行できます。これは、前のステップで実行したhs project createコマンドのボイラープレート サンプル コードで設定されたリダイレクトURLとして、https://localhost:3000/oauth-callbackで機能するようにすでにセットアップされています。
  • app-hsmeta.jsonファイル内のアプリのuidプロパティーと、プロジェクト内の他の*-hsmeta.json設定ファイルを変更します。
UIDは、プロジェクトの全てのコンポーネントと機能の固有IDとして使用されます。機能とUIDの作成後に、後続のデプロイでUIDが変更または修正されると、プラットフォームは変更後のUIDを以前の機能と異なるものとして認識しますが、これは想定外である可能性があります。
  • 統合アプリにアプリオブジェクトを使用する場合、オブジェクトのリクエストに基づいて許可されるのは、承認済みの「name」プロパティーの定義のみです。この非公開ベータの一環として、アプリの承認済みの「name」を別途確認している必要があります。これは*-object-hsmeta.json設定で使用されます。参考までに、アプリオブジェクトの完全修飾名（FQN）はa<appId>_<name>です。例えば、appIdが16858319でnameプロパティーがCARSであった場合、FQNはa16858319_carsになります。
  • 変更を保存したら、CLIコマンドhs project uploadを実行してプロジェクトをHubSpot開発者プラットフォームにアップロードし、自動的に新しいビルドをトリガーします。
  • ブラウザーウィンドウでhttps://app.hubspot.com/developer_projects/<accountId>に移動してプロジェクトUIにアクセスし、アプリとプロジェクトが正しく作成、ビルド、デプロイされていることを確認します。
5

アプリのクライアントIDとクライアントシークレットをアプリに追加する

  • プロジェクトをアップロードしたら、OAuth設定にコピーするアプリの認証の詳細を取得する必要があります。
    • ［開発］ナビゲーションメニューの［プロジェクト］をクリックします**。**__
    • 新しいプロジェクトの名前をクリックします。
    • アプリのUIDをクリックし、［認証］タブをクリックします**。**
    • 新しいアプリから「クライアントID」__と「クライアントシークレット」__をコピーし、ローカルOAuthサーバーの設定内の対応する場所に貼り付けてから、OAuthサーバーを再起動します。
6

アプリのオブジェクトスキーマ設定を構成する

次に、アプリ オブジェクト スキーマを設定します。
  • /src/appディレクトリー内にディレクトリーを作成し、app-objectsという名前を付けて、新しいアプリオブジェクトを追加します。新しいディレクトリーのパスは/src/app/app-objectsです。
  • オブジェクトのスキーマを表す新しい設定ファイルを作成します。このファイル名のプレフィックスとして、プレビュープロセス中にアプリに付与されたオブジェクト名を使用し、その後に-object-hsmeta.jsonと続ける必要があります。例えばリファレンス プロジェクト テンプレートでは、アプリオブジェクト名は「CAR」であるため、作成される設定ファイルの名前はcar-object-hsmeta.jsonになります。
  • アプリ オブジェクト コンポーネント定義の参照ファイルを参照し、フィールドをカスタマイズして、アプリオブジェクトの該当する値にします。
    • 定義のconfigオブジェクト内にあるnameフィールドは、レビュープロセス中にアプリに付与された名前（UPPER_SNAKE_CASE形式）と一致している必要があります。
    • 次のステップでプロパティーとフィールドがアプリ オブジェクト スキーマに追加され、プロジェクトにアップロードされた後は、これらのプロパティーとフィールドを削除できません。

​
注：

テスト中に、開発ライフサイクルをサポートするために複数のアプリで同じアプリオブジェクト名を使用できます。この概念実証アプリから始めて、移行が実行可能になったら、開発アプリ、ステージングアプリ、本番アプリで同じ名前とスキーマ定義を使用できます。これらの各インスタンスのUIDは一意である必要があります。
  • アプリ オブジェクト スキーマ定義の編集が完了し、これらの変更をコミットする準備ができたら、次のコマンドを実行して変更を保存します。
hs project upload
hs project deploy
  • ブラウザーウィンドウでhttps://app.hubspot.com/developer_projects/<hubId>に移動してプロジェクトUIにアクセスし、アプリとプロジェクトが正しく作成、ビルド、デプロイされていることを確認します。
7

アプリを更新する

アプリ オブジェクト スキーマがアップロードされたので、次はapp-hsmeta.jsonファイルで定義されたスコープを更新して、前のステップで作成したスコープを反映する必要があります。これらのスコープは、hs project uploadの実行後にCLIログに表示されます。
  • app-hsmeta.jsonファイルを編集し、auth定義内のrequiredScopesの配列に新しいスコープを追加します。例えばappIdがa12345だった場合、auth定義を次のように編集します。
"auth": {
  "type" : "oauth",
  "redirectUrls": ["http://localhost:3000/oauth-callback"],
  "requiredScopes": [
    "crm.objects.contacts.read",
    "crm.objects.contacts.write",
    "crm.app.objects.a12345_my_app_object.view",
    "crm.app.objects.a12345_my_app_object.create",
    "crm.app.objects.a12345_my_app_object.edit",
    "crm.app.schemas.a12345_my_app_object.read",
    "crm.app.objects.a12345_my_app_object.merge",
    "crm.app.objects.a12345_my_app_object.delete",
    "crm.app.schemas.a12345_my_app_object.properties.write"
  ],
  "optionalScopes": [],
  "conditionallyRequiredScopes": []
},

​
注：

  • 顧客がアプリオブジェクトを表示できるのは、schemas.read スコープがアプリ設定に含まれており、 インストール/再認証のOAuthフローでリクエストされた場合だけです。設定に全てのアプリ オブジェクト スコープを 含めることを強くおすすめしますが、schemas.readは 顧客がアクセスできるようにするために必須です。例えばappIdが12345の場合、 crm.app.schemas.a12345_MY_APP_OBJECT.readを必須スコープとして 含めます。
  • テストに使用するアプリ（プロトタイプ、開発、ステージング、 本番）に応じて、スコープ定義を追加する場所に 注意する必要があります。非公開ベータのこの段階では、本番アプリのデプロイはまだサポートされていませんが 本番環境の準備ができたら、これらのスコープを conditionallyRequiredScopesとして含めるのが一般に最も安全です。 これらのスコープタイプの詳細については公開アプリの ドキュメントをご確認ください。
  • これらのスコープの追加が完了し、変更を保存したら、次のコマンドを実行して変更をプラットフォームにコミットします。
hs project upload
hs project deploy
デプロイが完了すると、アプリとそれに対応するアプリオブジェクトは、インストール済みアカウントでテストできる状態になります。
8

開発者テストアカウント（任意）を作成してアプリをインストールする

テストアカウントをまだお持ちでない場合は、HubSpotで作成できます。
  • ［開発］__ナビゲーションメニューの［テストアカウント］****に移動し、［開発者テストアカウントを作成］****をクリックします。画面の指示に従って、新しいテストアカウントを作成します。
  • 左側のサイドバーメニューで［プロジェクト］****に移動し、新しいプロジェクトの名前をクリックして、コンポーネントリストでアプリのUIDをクリックします。
  • ［認証］__タブで、アプリのインストールリンクをコピーします。
  • このリンクを使用して、開発者テストアカウントにアプリをインストールします。
  • テストアカウントを開き、［接続されたアプリ］__ページに移動すると、インストール済みのアプリがリストに表示されます。
  • テストアカウントで［CRM］＞［コンタクト］****に移動し、CRMオブジェクトのドロップダウンメニューをクリックして、アプリオブジェクトが使用可能であることを確認します。
  • その後、アプリオブジェクトの新しいレコードを作成して、スキーマ定義が設定ファイルに準拠していることを確認できます。
app-object-available-in-crm
9

HubSpotオブジェクトAPIを使用したプログラムによるデータアクセス

アプリオブジェクトを作成し、開発者テストアカウントでテストしたので、次にインストールしたテストアカウントに関連付けられているOAuthアクセストークンを使用して、オブジェクトAPIでアカウント内のデータを更新するリクエストを直接実行できます。APIの詳細についてはオブジェクトAPIをご確認ください。ただし、アプリオブジェクトに固有のリクエストは、HubSpotの他の標準オブジェクトと同じ規則に従います。アプリオブジェクトのobjectTypeIdまたはfullyQualifiedNameをリクエストのobjectTypeパスパラメーターとして使用する必要があります。例えば次のコードブロックは、アプリオブジェクトの新しいレコードを作成するためのcURLリクエストを送信する方法を示しています。
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/<fullyQualifiedName> \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'
レコード インデックス ページに移動すると、アプリオブジェクトのobjectTypeIdを確認できます。
  • アプリをインストールした開発者テストアカウントで［CRM］＞［コンタクト］****に移動します。
  • ページ上部のドロップダウンメニューをクリックして、アプリオブジェクトを選択します。
  • objectTypeIdは、URLの/objects/<objectTypeId>/views部分に表示されます。

​
次のステップ

開発者プラットフォームのさまざまな機能でアプリオブジェクトを使用する方法を参照ドキュメントでご確認ください。