非公開アプリ

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

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

注:非公開アプリでは、拡張機能、カスタム タイムライン イベント、Webhookはサポートされません。こうした機能を使用するアプリの作成を検討している場合は、公開アプリを作成する必要があります。

公開アプリと非公開アプリの違い

非公開アプリ、公開アプリ共に、HubspotのAPIを使用して構築する連携です。主な違いは、HubSpotアカウントの認証方式と、単一のアカウントに関連付けられるかどうかという点です。

非公開アプリ

  • 単一のアカウントにのみインストールできます。
  • APIキーではなく、HubSpot上で設定するアクセストークンを認証に使用します。 

公開アプリ

  • 複数のアカウントにインストールできます。
  • アプリマーケットプレイスに掲載できます。
  • 開発者が設定するOAuthを認証に使用します。
  • Webhookなどの高度な連携機能を利用できます。

非公開アプリと公開アプリの違い(英語)の詳細をご覧ください。 

非公開アプリを作成する

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

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

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

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

edit-details-of-private-app

 

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

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 });

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

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

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

rotate-private-app-access-token

 

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

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

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

review-private-app-call-logs

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

1つのHubSpotアカウントには、非公開アプリ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

 

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

非公開アプリのアクセストークンに関する情報(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"] }

非公開アプリを削除する

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

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

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