API利用ガイドライン
HubSpotでは、全てのユーザーに安定した品質をお届けするために、公開APIの利用状況を詳しくモニタリングしています。アプリや連携の全ての開発に際し、HubSpot利用規定とAPIに関する利用条件を順守していただく必要があります。HubSpotは随時APIを変更または廃止する権利を有しますが、更新情報は常に開発者変更ログ(英語)を通じて事前にお知らせします。
認証とセキュリティー
最適なセキュリティーを実現するために、全てのアプリにはHubSpotのOAuthプロトコルを直接お使いいただく必要があります。または、非公開アプリを開発する場合にはアプリのアクセストークンを使用します。アプリには、このプロトコルに準拠したTTL(time-to-live)データの保存とユーザー アクセス トークンのリフレッシュを実装いただく必要があります。アクセストークンの生成時には、リフレッシュまでのAPI呼び出しに使用できる期間を示すexpires_in
パラメーターが含まれています。Unauthorized (401)
(認証されていない)リクエストは、新しいアクセストークンを取得する必要性を示す指標とはなりません。
非公開アプリ
非公開アプリのAPIの使用状況を表示するには、次のようにします。
- HubSpotアカウントで、メイン ナビゲーション バーにある設定アイコンをクリックします。
- 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
- 非公開アプリの名前をクリックします。
- アプリの詳細ページで、[ログ]タブをクリックします。
- 表に掲載されているAPI呼び出しを確認します。検索バー、フィルター、日付入力を使用して、表示されるAPI呼び出しをさらに絞り込むこともできます。
非公開アプリでのAPIの使用状況の確認について詳しくは、こちらをご覧ください。
OAuthを使用した公開アプリ
OAuthを使用した公開アプリのAPIの使用状況を表示するには、次のようにします。
- 開発者アカウントで、メイン ナビゲーション バーにある[アプリ]に移動します。
- アプリの名前をクリックします。
- 左のサイドバーメニューで[モニタリング]に移動します。
- タブを切り替えることで、さまざまなタイプのアプリに対するリクエストやアプリからのリクエストを表示できます。これらのログが表示された状態で、個々のリクエストをクリックすると、詳細情報が表示されます。
OAuthを使ったアプリ
OAuthアプリの場合、アプリをインストールするHubSpotアカウントごとに、リクエスト数は10秒間に100回に制限されています。ただし、後述の「その他の制限」セクションで説明しているように、検索APIは除きます。API追加オプションに関連する制限は適用されません。
非公開アプリ
各非公開アプリには、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回 |
- 開発者アカウント1件につき最大100件のアプリを作成可能
- HubSpotアカウント1件につき最大20件の非公開アプリを作成可能
- アプリ1件につき1,000件までのWebhookサブスクリプションを作成可能
- アプリ1件につき最大25個のCRM拡張機能を作成可能
- アプリ1件につき最大750個のタイムライン イベント タイプを作成可能
- タイムライン イベント タイプ1個につき最大500個のプロパティーを作成可能
- 検索APIエンドポイントのレート制限:認証トークン1つにつき1秒当たり最大4件のリクエスト
サービスの制限と価格については、こちらをご覧ください。
アプリまたは連携でレート制限を超えると、以降の全てのAPI呼び出しに対し、429
のエラーレスポンスを受け取ることになります。エラーレスポンスが返されるリクエストの数が、1日の合計リクエスト数の5%を超えないようにしてください。HubSpotアプリマーケットプレイスへのアプリの掲載を予定している場合、この5%の制限を守っていただく必要があります。
429
レスポンスの形式を以下に示します。
message
とpolicyName
は、どちらの上限に達したかを示します(日次制限または2次制限)。
1日当たりの制限は、タイムゾーン設定に基づいて深夜0時にリセットされます。
次の表は、HubSpotへの各APIリクエストのレスポンスに含まれるレート制限ヘッダーの詳細を示しています。表の下部に例外が記載されています。
ヘッダー | 説明 |
---|---|
X-HubSpot-RateLimit-Daily |
1日当たりに実行可能なAPIリクエストの数。このヘッダーは、OAuthを使用して承認されたAPIリクエストへのレスポンスに含まれていません。 |
X-HubSpot-RateLimit-Daily-Remaining |
当日に実行可能な残りのAPIリクエストの数。このヘッダーは、OAuthを使用して承認されたAPIリクエストへのレスポンスに含まれていません。 |
X-HubSpot-RateLimit-Interval-Milliseconds |
X-HubSpot-RateLimit-Max ヘッダーとX-HubSpot-RateLimit-Remaining ヘッダーが適用される時間。例えば、値が10000なら10秒間を表します。 |
X-HubSpot-RateLimit-Max |
X-HubSpot-RateLimit-Interval-Milliseconds で指定された時間内で実行可能なリクエストの数。例えば、このヘッダー値が100で、 X-HubSpot-RateLimit-Interval-Milliseconds ヘッダーが10000の場合、リクエストの回数は10秒当たり100回に制限されます。 |
X-HubSpot-RateLimit-Remaining |
X-HubSpot-RateLimit-Interval-Milliseconds で指定された時間内で実行可能な残りのAPIリクエストの数。 |
注:
X-HubSpot-RateLimit-Secondly
ヘッダーとX-HubSpot-RateLimit-Secondly-Remaining
ヘッダーが含まれている場合、そのデータ自体は正確ですが、この2つのヘッダーで参照されている制限は既に適用されていないため、廃止されたものとして扱ってください。- 検索APIエンドポイントからのレスポンスに、上記のレート制限ヘッダーは含まれません。
こちらのエンドポイントを使って、当日中に使用された呼び出し数を確認することもできます。
TEN_SECONDLY_ROLLING
の制限に到達した場合は、アプリで発行するリクエストをスロットリングして制限内に収めてください。リクエストのスロットリングと組み合わせる対策、または1日当たりの制限に達する場合の対策について、以下を参照してください。
これらの方法を検討しても呼び出し制限に到達する場合は、HubSpotの開発者フォーラム(英語)に投稿してください。その際には、ご使用のAPIや、その利用状況、到達した制限など、できるだけ詳しい情報をご提供ください。
サイトまたはアプリの各ページの読み込み時にHubSpotからのデータを使用する場合は、HubSpot APIで毎回リクエストするのではなく、データのキャッシュ処理によってキャッシュからデータを読み込むようにしてください。一括処理のためにアカウント設定を取得する呼び出しを繰り返し行う場合(オブジェクトのプロパティー、担当者、またはフォーム設定を取得するなど)、こうした設定情報についても可能な限りキャッシュ処理を行ってください。
HubSpotのMarketing Hub Enterpriseをご契約されている場合、ワークフロー内でWebhookアクションを使用してコンタクトレコードのデータを貴社のシステムに送信できます。Webhookは、どのワークフローのアクションとしてもトリガーできるため、コンタクトデータを貴社のシステムに送信するための条件として、どのようなワークフローの開始条件でも使用できます。Webhookの詳しい使い方については、こちらを参照してください。また、Webhookデータの例についてはこちら(英語)をご覧ください。ワークフローを介して行われたWebhook呼び出しは、APIレート制限には計上されません。
貴重なご意見をありがとうございました。