Private apps

非公開アプリ(Private App)では、HubSpotのAPIを使用して、HubSpotアカウント上の特定のデータにアクセスできます。非公開アプリで何をリクエストまたは変更できるかは、アカウント側で非公開アプリごとに管理できます。権限が付与されると、そのアプリ専用のアクセストークンが生成されます。 

HubSpotアカウント内で非公開アプリにアクセスするには、スーパー管理者権限が必要です。

注:非公開アプリでは、カスタム タイムライン イベントがサポートされません。Webhookは非公開アプリでサポートされていますが、配信登録については、APIを介してプログラムで編集することはできません。代わりに、非公開アプリの設定で編集する必要があります。

カスタム タイムライン イベントを使用するアプリを作成する予定の場合は、代わりに公開アプリを作成してください。詳しくは非公開アプリと公開アプリの違いをご覧ください。

非公開アプリを作成する

  • HubSpotアカウントにて、メイン ナビゲーション バーにある設定アイコンをクリックします。
  • 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
  • [非公開アプリを作成]をクリックします。
  • [基本情報]タブで、アプリの詳細を設定します。
    • アプリの名前を入力します。
    • プレースホルダーロゴの上にカーソルを合わせると表示されるアップロードアイコンをクリックして、アプリのロゴとして使用する正方形の画像をアップロードします。
    • アプリの説明を入力します。
  • [スコープ]タブをクリックします。
  • 非公開アプリがアクセスできるように設定するスコープごとに、[読み取り]または[書き込み]チェックボックスをオンにします。[スコープを検索]検索バーを使用して、特定のスコープを検索することもできます。
  • アプリの設定が完了したら、右上の[アプリを作成]をクリックします。

updated-read-write-scope-config-private-apps

  • ダイアログボックスで、アプリのアクセストークンの情報を確認してから、[作成を続行]をクリックします。

アプリの作成が完了したら、アプリのアクセストークンを使用して、API呼び出しを開始できます。アプリの情報を編集したりアプリのスコープを変更したりする必要がある場合は、[詳細を編集]をクリックします。

edit-details-of-private-app

 

アプリのアクセストークンでAPI呼び出しを行う

注意:HubSpotアカウントがダウングレードされ、機能が利用できなくなると、非公開アプリはスコープを使用できなくなります。例えば、アカウントがHubDBにアクセスできない場合、非公開アプリはHubDBスコープにアクセスできません。

非公開アプリのアクセストークンは、HubSpotアカウントで利用可能なスコープと非公開アプリ用に設定した内容を反映するように更新されますが、トークン文字列自体は変更されません。 

API呼び出しを開始するには、アプリの詳細ページを開きます。

  • [アクセストークン]カード内の[トークンを表示]をクリックして、アクセストークンを表示します。[コピー]をクリックして、トークンをクリップボードにコピーします。

show-private-app-access-token-1

  • アクセストークンを貼り付けて、開発者に提供したり、ご自身でアプリを開発する際に使用したりできます。HubSpot APIエンドポイントに対して呼び出しを行う際には、Authorizationフィールドに「Bearer (自分のトークン名)」という値を設定します。例えば、Node.jsとaxios(英語)を使用してコンタクトAPIの呼び出しを行う場合、リクエストは次のようになります。
axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );
  • 非公開アプリのアクセストークンはOAuthを基盤として実装されているため、HubSpotのクライアントライブラリーを使用して、アクセストークンによる認証済みの呼び出しを行うこともできます。例えば、Node.jsクライアントライブラリー(英語)を使用する場合は、アプリのアクセストークンを渡すことにより、OAuthクライアントをインスタンス化できます。
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN });

非公開アプリのアクセストークン情報を表示する

非公開アプリのアクセストークンに関する情報(Hub IDや、トークンに関連付けられているスコープなど)を表示するには、/oauth/v2/private-apps/get/access-token-infoPOSTリクエストを送信します。リクエスト本文にアクセストークンを含めます。

// POST request response body { "tokenKey": {{accessToken}} }

レスポンスには、トークンを作成したユーザー、アカウントのHub ID、非公開アプリのID、トークンに関連付けられているスコープに関する情報が格納されています。

// Example response body { userId:123456, hubId:1020304, appId:2011410, scopes:[ "oauth", "crm.schemas.companies.write"] }

アクセストークンをローテーションする

アクセストークンが分からなくなった場合や侵害された場合は、トークンをローテーション(変更)できます。新しいアクセストークンが作成され、元のアクセストークンは失効します。

  • HubSpotアカウントにて、メインのナビゲーションバーに表示される設定アイコンをクリックします。
  • [連携]>[非公開アプリ]の順に進みます。
  • 非公開アプリの名前をクリックします。
  • アクセストークンの横にある[変更(ローテーション)]をクリックします。
    • トークンが侵害され、直ちにアクセスを取り消す場合は、[今すぐこのトークンを変更(ローテーション)して期限切れにする]をクリックします。
    • 特に侵害が生じていなくても、トークンは6か月ごとに変更することが推奨されます。トークンを定期的に変更する準備ができている場合は、[後でこのトークンを変更(ローテーション)して期限切れにする]をクリックします。これにより、7日後にトークンが失効します。
      • アプリを早く移行する準備ができている場合は、[今すぐ期限切れにする]をクリックします。
      • もっと時間が必要だと判断した場合は、[変更(ローテーション)をキャンセル]をクリックし、元のトークンの失効を取り消して、新しいアクセストークンを無効にすることができます。

rotate-private-app-access-token

また、HubSpotは、アクセストークンのローテーションステータスやその他の関連するアラートに関するリマインダーを含むメール通知をスーパー管理者に送信します。HubSpotアカウントのスーパー管理者は、次のイベントとリマインダーの通知を受け取ります。

  • スーパー管理者がローテーションを開始したとき(開始直後または7日後にスケジュール)。
  • スーパー管理者が保留中のローテーションをキャンセルしたとき。
  • スーパー管理者が、トークンの有効期限が切れるまで7日待つのではなく、[今すぐ期限切れにする]をクリックして、アクセストークンをすぐに期限切れにすることを選択したとき。
  • アプリのアクセストークンは24時間後に期限切れになるとき。
  • アプリのアクセストークンがローテーションされ、7日後に期限切れになったとき。
  • アクセストークンを180日以上ローテーションしていない場合に、スーパー管理者にもアプリのアクセストークンをローテーションするリマインダーメールが届くとき。

API呼び出しログを表示する

アプリによる過去30日間のAPI呼び出しを確認するには、以下の手順に従います。

  • アプリの詳細ページで、[ログ]タブをクリックします。
  • 非公開アプリのAPI呼び出しの確認および絞り込みを行うには、以下の手順に従います。
    • [メソッド]または[レスポンス]ドロップダウンメニューをクリックして、リクエストメソッドまたはレスポンスコードでAPI呼び出しの履歴を絞り込みます。
    • [開始日]または[終了日]ドロップダウンメニューをクリックして、特定の期間でAPI呼び出しログを絞り込みます。
    • [リクエストURLで検索]検索ボックスで、URLを指定して特定の呼び出しを検索することもできます。

review-private-app-call-logs

  • API呼び出しログをエクスポートするには、[ログをエクスポート(CSV)]をクリックします。次に、日付範囲(最長で過去30日まで)を指定し、[エクスポート]をクリックします。
  • ポップアップボックスで、エクスポートするAPI呼び出しの日付範囲を選択し、[エクスポート]をクリックします。エクスポートの準備ができると、ダウンロードリンクが記載されたEメールが届きます。 

非公開アプリに関する制限

HubSpotアカウント1件につき、最大20件の非公開アプリを作成できます。各非公開アプリには、HubSpotのAPI利用ガイドラインが適用されます。非公開アプリから実行できる呼び出しの回数は、アカウントのご契約内容とAPI追加オプションのご購入状況に基づきます。

  製品のエディション 10秒当たり 1日当たり
非公開アプリ

(全ての製品の)

無料ツール、Starter

非公開アプリ1件につき100回 アカウント1件につき250,000回
 

(全ての製品の)

Professional、Enterprise

非公開アプリ1件につき150回 アカウント1件につき500,000回
非公開アプリ(API追加オプション購入時)

(全ての製品の)

無料ツール、Starter、Professional、Enterprise

非公開アプリ1件につき200回 アカウント1件につき1,000,000回

StarterプランとProfessionalプランの両方を持っている場合、上位プラン(Professional)の制限がアカウントに適用されます。 

非公開アプリを削除する

非公開アプリを削除すると、そのアプリのアクセストークンは永久に取り消され、API呼び出しにも使用できなくなります。

アプリを削除するには、以下の手順に従います。

  • HubSpotアカウントにて、メイン ナビゲーション バーにある設定アイコンをクリックします。
  • 非公開アプリの名前をクリックします。
  • ページの最下部に表示される[(アプリ名)を削除]をクリックします。
  • ダイアログボックスにアプリの名前を入力して削除を確認し、[削除]をクリックします。

参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。