最終更新日: 2025年9月11日
開発者プラットフォームの最新バージョン（2025.2）には、ファイルベースの新しいビルドおよびデプロイフレームワークが含まれています。このフレームワークには、アプリの設定、アセット、その他のソースコードが含まれています。
新しい開発者プラットフォーム（ベータ版）に登録する前に作成した既存の公開アプリがある場合、このガイドでは、それをプロジェクトフレームワークの最新バージョンに移行する手順について概説します。移行を進める前に、サポートされている機能と制限事項に関する以下の2つのセクションをご確認ください。
サポートされているアプリ機能と拡張機能
次のものを含む、プロジェクトでサポートされる全ての機能が移行に含まれます。- アプリの設定
- Webhook
- カスタム ワークフロー アクション
始める前に
カスタムオブジェクトが接続されたカードが既存のプロジェクトに存在する場合、移行前に、アプリにcrm.objects.custom.readスコープがあることを確認してください。最新バージョン2025.2より前に構築されたプロジェクトの場合、カスタム オブジェクト カードをビルドするために必要なスコープはcrm.schemas.custom.readだけでした。開発者プラットフォームの最新バージョン（2025.2）では、カードからカスタム オブジェクト データにアクセスするにはcrm.objects.custom.readが必要です。
制限事項
現在は非公開ベータ期間中であり、次の機能はまだサポートされていません。- GitHubから自動アップロードとビルドをトリガーするGitHub連携は、まだサポートされていません。現在、プロジェクトがGitHubにリンクされている場合は、移行を始める前に必ず連携を無効にしてください。GitHub連携を無効にして、CI／CD自動化のためのGitHubアクションを設定するには、こちらの記事の手順をご覧ください。
- アプリの設定ページを以前に作成した場合は、新しいUI拡張機能を使って設定環境をリファクタリングする必要があります。アプリの現在の本番環境バージョンの全てのインターフェイス要素を、最新バージョンへの移行前にメモしておくことをお勧めします。移行プロセスが完了した後、新しいUI拡張機能を使用して設定ページを再作成できます。
- 従来のCRMカード機能は、最新バージョンの開発者プロジェクトを使用するアプリではサポートされません。代わりにアプリ カード スキーマを使用するよう、既存の全てのCRMカードをリファクタリングする必要があります。
- アプリの基盤となる権限アーキテクチャーが更新され、より詳細なユーザー固有の権限がサポートされるようになります。この変更の一環として、新規顧客インストールでは、関連するサービス アカウント ユーザーがアカウント内に作成され、アプリに紐付けられるようになりました。
- アプリを再認証する個別ユーザーの数にかかわりなく、各アカウントは1つのリフレッシュトークンだけを受け取るようになります。
- リフレッシュトークンとアクセストークンのメタデータを取得する既存のOAuthエンドポイントからは、インストールしたユーザーが引き続き
userIdとして返され、アプリの移行後にはserviceAccountIdが返されるようになります。
アプリを移行する
上記のセクションの考慮事項を確認した後は、アプリの移行に進むことができます。このプロセスでは、アプリの元の認証資格情報、アプリ機能、およびインストール環境が保持されます。アプリのバックエンドで必要な変更はありません。- コマンド
npm i -g @hubspot/cli@nextを実行して、HubSpot CLIの最新のベータ版バージョンがインストールされたことを確認し、hs authおよびhs accounts useコマンドを使用してそれをアカウントに接続します。
CLIのバージョンは
7.5.4以降である必要があります。hs --versionを実行すると、CLIのバージョンを確認できます。- 移行プロセスを開始するには、移行しようとしている既存のアプリに基づいて、以下のいずれかのコマンドを使用します。
- プロジェクトに含まれない従来のアプリを移行する場合は、次のコマンドを実行します。
プロジェクトベースのアプリを移行する場合は、コマンド
hs project migrateを実行します。- 移行するアプリを選択するよう求める画面が表示されます。これにより、アプリおよび現在設定されている状態を表すアプリ機能を含む新しいプロジェクトが、ローカル ファイル システムの中に作成されます。
- アプリを選択した後、移行するコンポーネントを確定するように求められます。確定して次のステップに進む前に、移行プロセスを十分に理解しておく必要があります。
- 次に、プロジェクト名、新しいプロジェクトへのローカルパス、および必要なUIDを指定するように求められます。
UIDは、アプリの全ての機能に対応する固有IDとして使用されます。特定の機能のUIDがいったん定義された後、後続のビルドでそれを変更または修正すると、プラットフォームはそれを「新しい」、つまり以前のビルドと異なるものとして認識します。これは意図に反している可能性があります。
- プロジェクトの詳細を確定した後、移行プロセスでは、次の一連のアクションが1回の操作として自動的に実行されます。
- アカウントの［プロジェクト］__ページにアプリ用のプロジェクトが作成され、アプリコンポーネントおよび互換性のある全ての機能がそこに含まれます。
- アプリの既存の機能がソース コード ファイルに変換され、後でそれらを更新して設定を修正できるようになります。
- （「Build #1」__というラベル付きの）新しいプロジェクトがビルドおよびデプロイされ、これによってアプリとそのプロジェクトの間の関連付けが完了します。これにより、元の認証資格情報、アプリ機能、およびインストール環境が保持されます。
- ターミナルにプロンプトが表示されたら、新しいプロジェクト ソース ファイルを、以前に指定したローカルディレクトリーにダウンロードします。
- 既存のプロジェクトが移行された場合は、元の
src/ディレクトリーからarchive/にファイルを移動して、新しいプロジェクト ソース コードを/src/に入れます。
新しいプロジェクトの「Build #1」__では、サポートされている全機能に関するアプリの設定状態がキャプチャされ、戻すことができるベースラインとなります。必要に応じて「Build #1」****を再デプロイすると、このプロジェクトに対する将来の変更（例：Reactベースのアプリカードの追加）を安全に元に戻すことができます。
移行後、プロジェクト ソース コードで定義された機能は、HubSpot内のアプリ管理UIを使用しても、以前の開発者APIを使用しても、編集できなくなります。他の機能（カスタム ワークフロー アクションやタイムラインイベントなど）については、引き続きそれぞれのAPIで維持されます。
- 移行が完了すると、
hsproject.jsonファイルの"platformVersion": "2025.2"フィールドにそれが反映され、HubSpot CLIとプロジェクトのソース コード ファイルを使用して新規または既存の機能を開発し始めることができます。