Migrate an API key integration to a private app
ご使用のアカウントで、APIキーの無効化に関するバナーが表示される場合は、次の内容をご確認ください。
- 影響を受ける全ての連携が移行済みであることを確認してから、APIキーを無効化します。
- 過去7日間にアカウントのAPIキーが使用されたかどうかを確認するには、APIキーの呼び出しログ履歴を表示します。呼び出しログには、8日以上前にキーを使用して行われた要求は表示されません。
- アカウント設定の[接続されたアプリ]ページにリストされているアプリは、OAuthで認証されるため、移行する必要はありません。
- 開発者APIキーは、標準のHubSpot APIキーとは別のものであり、非推奨になることはありません。開発者APIキーは、Webhook APIサブスクリプションやタイムラインイベントAPIイベントタイプなど、HubSpotアプリに関連する設定を管理するために使用されます。
HubSpot APIキーを使用する内部連携を構築した場合、APIキーは全てのHubSpot CRMデータに対する読み取りアクセス権と書き込みアクセス権の両方を提供しますが、APIキーが侵害された場合にセキュリティーリスクが発生する可能性があります。非公開アプリに移行することにより、連携で必要とされる特定のスコープを認証できます。スコープを認証すると、アクセストークンが生成されます。このトークンは、連携でアカウント内のリクエストや変更を行うことが可能なデータを制限します。
既存のAPIキー連携を非公開アプリに移行するには、次の手順に従います。本番環境で変更する前に、まず開発者テストアカウントやサンドボックスアカウントなどのテスト環境を使用することをお勧めします。アプリの移行に関して質問がある場合は、開発者コミュニティー(英語)をご覧ください。
また、以下のHubSpot開発者向け動画で、APIキー連携を非公開アプリに移行する手順をご確認いただけます(英語)。
このガイドの内容
注:非公開アプリでは、Webhookおよび特定の種類の拡張機能はサポートされません。既存の連携でこれらの機能のいずれかを使用している場合は、代わりにOAuthを使用する公開アプリを作成する必要があります。
- HubSpotアカウントにて、メイン ナビゲーション バーにある設定アイコンをクリックします。
- 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
- [非公開アプリを作成]をクリックします。
- [基本情報]タブで、アプリの詳細を設定します。
- アプリの名前を入力します。
- プレースホルダーロゴの上にカーソルを合わせると表示されるアップロードアイコンをクリックして、アプリのロゴとして使用する正方形の画像をアップロードします。
- アプリの説明を入力します。
- [スコープ]タブをクリックします。
- 次に、連携で使用しているAPIに基づいて、認証するスコープを選択します。アプリに必要なスコープを見つけるには、次の手順に従います。
- 既存の連携で使用しているHubSpot APIのリストを作成します。
- APIリクエストごとに、関連する開発者ドキュメント(コンタクトAPIなど)に移動します。
- [エンドポイント]タブをクリックし、連携で使用しているエンドポイントまでスクロールします。
- [必要な条件]セクションで、エンドポイントを使用するために必要なスコープを見つけます。可能な場合は常に、[標準スコープ]に表示されているスコープではなく、[詳細スコープ]に表示されているスコープを選択してください。きめ細かいスコープがない場合は、標準スコープを使用してください。
- 非公開アプリの設定に戻り、一致するスコープの横にある[読み取り]または[書き込み]チェックボックスをオンにします。[スコープを検索]検索バーを使用してスコープを探すこともできます。
- スコープの選択が完了したら、右上の[アプリを作成]をクリックします。アプリの作成後は、いつでもアプリに変更を加えることができます。
- ダイアログボックスで、アプリのアクセストークンの情報を確認してから、[作成を続行]をクリックします。
非公開アプリを作成したら、そのアクセストークンを使用してAPIリクエストを開始できます。非公開アプリの設定ページの[詳細]タブで、アクセストークンの下の[トークンを表示]をクリックすると、トークンが表示されます。
hapiKey
クエリーパラメーターを使用してAPIリクエストを行う代わりに、リクエストのAuthorization
ヘッダーに非公開アプリのアクセストークンを含めます。リクエストを行うときは、Authorization
ヘッダーの値をBearer YOUR_ACCESS_TOKEN
に設定します。特に明記されている場合を除き、この認証方式は、HubSpotのレガシー開発者ドキュメント(英語)に記載されているレガシーAPIを含む、全てのパブリックAPIエンドポイントに対応しています。
リクエストは次のようになります。
非公開アプリのアクセストークンはOAuthを基盤として実装されているため、HubSpotのクライアントライブラリーを使用して、アクセストークンによる認証済みの呼び出しを行うこともできます。例えば、Node.jsクライアントライブラリー(英語)を使用する場合は、アプリのアクセストークンを渡すことにより、OAuthクライアントをインスタンス化できます。
非公開アプリへの移行を完了するには、コードからHubSpot APIキーへの参照を全て削除し、代わりに上記の方法に従って非公開アプリのアクセストークンを使用します。リクエストにトークンをハードコーディングするのではなく、実行するリクエストに応じて、トークンを格納するシークレットを作成します。シークレットを使用すると、サーバーレス関数でトークンを使用するときなどに、トークンが公開されることを防止できます。アクセストークンをシークレットとして格納するには、次の手順に従います。
- ターミナルで、
hs secrets add secretName
を実行します。シークレットの名前は、後で簡単に参照できるように、シンプルなものにすることをお勧めします。 - アクセストークンをターミナルに貼り付けて、Enterキーを押します。
この時点で、環境変数としてシークレットにアクセスできるようになります。詳しくは、後述のサーバーレス関数の例をご確認ください。
APIキーへの参照が全て削除されたことを確認するには、HubSpotアカウントのコールログをチェックします。
- HubSpotアカウントで、メイン ナビゲーション バーにある設定アイコンをクリックします。
- 左のサイドバーで、[連携]>[APIキー]の順に進みます。
- [コールログ]タブで最近のリクエストをチェックし、非公開アプリのアクセストークンを使用するために以前の参照を全て削除してから、リクエストが実行されていないことを確認します。
マーケティングコンタクトを含む有料のMarketing Hubアカウントをご利用中で、以前にAPIキーを使用して、連携によって作成されたコンタクトをマーケティングコンタクトとして設定している場合は、非公開アプリについても同じ操作を行う必要があります。
- HubSpotアカウントにて、メイン ナビゲーション バーにある設定アイコンをクリックします。
- 左のサイドバーで、[連携]>[マーケティングコンタクト]の順に進みます。
- [接続されたアプリ]の下で、検索バーを使用して非公開アプリを見つけて、[コンタクトをマーケティングコンタクトとして同期するにはオンにします]スイッチをクリックしてオンにします。
非公開アプリの設定が完了し、コードのAPIキーへの参照が全て削除されたことを確認したら、キーを無効化できます。
コードからHubSpot APIキーへの参照を全て削除し、それらを非公開アプリのアクセストークンへの参照に置き換えたら、それ以上のコードの変更は不要です。
開発者テストアカウントまたはサンドボックスアカウントで上記の手順を実施したら、本番アカウントで同じプロセスを再現します。次に、非公開アプリのAPIコールログを監視し、アプリの全てのリクエストが400
エラーを返していないことを確認します。
- HubSpotアカウントにて、メイン ナビゲーション バーにある設定アイコンをクリックします。
- 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
- 非公開アプリの名前をクリックします。
- [ログ]タブをクリックします。
- スコープが不十分なために失敗したAPIリクエストについては、
403
エラーが表示されます。連携のランタイムログにアクセスする場合は、対応するAPIリクエストに対するレスポンスに、不足しているスコープの詳細を示すエラーメッセージが含まれている必要があります。
- 非公開アプリに新しいスコープを含める必要がある場合は、次の手順に従います。
- [詳細]タブをクリックします。
- [詳細を編集]をクリックします。
- ページの最上部にある[スコープ]をクリックします。
- 不足しているスコープの横のチェックボックスを全てオンにしたら、右上の[変更をコミット]をクリックします。
非公開アプリの作成と管理、および非公開アプリの制限については、非公開アプリのガイドをご確認ください。
以下では、一般的なAPIキーの使用方法と、APIキーを非公開アプリのアクセストークンに移行する方法について詳しく説明します。
サーバーレス関数でAPIキーを使用している場合は、上記と同様に、非公開アプリのアクセストークンを認証に使用できます。関数が実行する必要のあるスコープが非公開アプリに存在することを確認してください。
非公開アプリのアクセストークンを使用してサーバーレス関数を認証するには、次の手順に従います。
- 「アクセストークン」カードで、[トークンを表示]をクリックしてアクセストークンを表示します。次に、[コピー]をクリックして、トークンをクリップボードにコピーします。
- アクセストークンをコピーした状態のまま、そのトークンを保存するための新しいシークレットを作成します。
- ターミナルで、
hs secrets add secretName
を実行します。シークレットの名前は、後で簡単に参照できるように、シンプルなものにすることをお勧めします。 - アクセストークンをターミナルに貼り付けて、Enterキーを押します。
- ターミナルで、
- サーバーレス関数の
serverless.json
ファイルで、secrets
配列にシークレット名を追加します。
詳しくはアプリのトークンを使用してAPIを呼び出す方法をご確認ください。
APIキーを使用してカスタムオブジェクトを作成する代わりに、非公開アプリを作成して、そのアクセストークンでコールを認証できます。ただし、必要なスコープが非公開アプリに含まれていることが条件となります。例えば、Postmanを使用してカスタムオブジェクトを作成する場合は、認証タイプをBearerトークンに設定し、[トークン]フィールドにトークンを入力します。
非公開アプリを使用したカスタムオブジェクトの作成に関する詳細はHubSpotの開発者ブログ(英語)をご覧ください。
「カスタムコード」ワークフローアクションでAPIキーを使用している場合は、代わりに非公開アプリのアクセストークンを使用できます。ただし、必要なスコープが非公開アプリに存在することが条件となります。更新するには、ワークフローエディターでカスタムアクションを開き、次の変更を行います。
- 最初に、非公開アプリのアクセストークンを格納する新しいシークレットを追加します。
- 次に、新しいシークレットでアクションコードを更新します。