APIキー

API キーを作成して、外部システムを統合したり、カスタム ダッシュボードを構築したり、Balla Stats データを使用してワークフローを自動化したりできます。

中級
12分

前提条件

API キーを作成する前に、以下が必要です。

  • Balla Stats アカウント
  • PROプラン以上

プランの制限: FREE = 0 キー、PRO = 3 キー (1,000 要求/時)、チーム = 10 キー (10,000 要求/時)、エンタープライズ = 50 キー (100,000 要求/時)。

プログラムによる API アクセス

API キーを作成して、外部システムを統合したり、カスタム ダッシュボードを構築したり、Balla Stats データを使用してワークフローを自動化したりできます。

範囲指定されたアクセス許可

きめ細かなアクセス制御

レート制限

キーごとのリクエスト制限

使用状況の追跡

完全な監査証跡

学べること
  • API キーに移動します
  • 最初のキーを作成する
  • 安全にコピーして保存
  • API キーを使用する
  • 使用状況を監視する
  • キーをローテーションまたは取り消す
1
API キーに移動します

ダッシュボードのサイドバーで、「API キー」「」をクリックします。このページには既存のキーがすべて表示され、新しいキーを作成できます。

APIキー管理ページ
2
最初のキーを作成する

「API キーの作成」 をクリックし、わかりやすい名前を入力して、キーに必要なスコープを選択します。利用可能なスコープは次のとおりです。 read, write, matches, players, teams, seasons, and stats.

スコープを選択した「API キーの作成」ダイアログ

読み取り専用スコープから開始し、必要な場合にのみ書き込み権限を追加します。これは最小特権の原則に従います。

3
キーをコピーして保存します

キーは balla_sk_[64 の 16 進数文字] の形式で表示されます。完全なキーが表示されるのはこのときだけです。すぐにコピーして安全な場所に保管してください。

API キーのシークレットが一度表示されます - 今すぐコピーしてください

API キーは 1 回だけ表示されます。 今すぐコピーして安全に保管してください。後から取り出すことはできません。紛失した場合は、キーをローテーションするか、新しいキーを作成する必要があります。

4
API キーを使用する

API キーを HTTP リクエストの Authorization ヘッダーに含めます。

curl -H "Authorization: Bearer balla_sk_..." \
  https://api.ballastats.com/api/matches

または JavaScript では次のようになります。

const response = await fetch(
  'https://api.ballastats.com/api/matches',
  {
    headers: {
      'Authorization': 'Bearer balla_sk_...',
      'Content-Type': 'application/json',
    },
  }
);
const data = await response.json();

すべてのエンドポイントは /api-docs に文書化されています。詳細については、API Documentation チュートリアルを参照してください。

5
使用状況を監視する

キーが最後に使用されたタイムスタンプ、合計リクエスト数、および現在のレート制限ステータスを表示します。使用状況統計は、統合がどのように実行されているか、およびいつプランをアップグレードする必要があるかを理解するのに役立ちます。

API キーの使用統計
6
キーのローテーションまたは取り消し

Rotate キーを使用して、名前、スコープ、設定を維持しながら新しいキーを作成します。古いキーはすぐに取り消されます。 Revoke はキーを永久に非アクティブ化します。取り消されたキーを再アクティブ化することはできません。

キーをローテーションすると、古いキーはすぐに無効になります。ダウンタイムを回避するために、ローテーションの前に新しいキーで統合を更新してください。

ヒント

わかりやすい名前を使用する

各キーの目的を簡単に識別できるように、「Dashboard Bot」や「Stats Exporter」などのわかりやすい名前を使用します。

最低特権

最小特権の原則に従い、統合に実際に必要なスコープのみを付与します。

定期的な回転

セキュリティのためにキーを定期的に (90 日ごと) ローテーションします。重要な衛生状態を常に把握するためのリマインダーを設定します。

キーを決して公開しないでください

API キーをソース コードにコミットしたり、プレーン テキストで共有したりしないでください。環境変数またはシークレット マネージャーを使用します。

よくある問題

401 不正

  • キーが非アクティブ、取り消されている、または期限切れになっている可能性があります
  • キーが Authorization ヘッダーに含まれていることを確認します
  • ヘッダー形式が Bearer balla_sk_... であることを確認します。

403 禁止

  • キーにはこのエンドポイントに必要なスコープがありません
  • キーを編集して必要なスコープを追加します (例: POST リクエストの場合は write を追加します)
  • 各エンドポイントに必要なスコープの API ドキュメントを確認してください

429 リクエストが多すぎます

  • 現在の時間のレート制限を超えています
  • レート制限ウィンドウがリセットされるまで待つか、プランをアップグレードして制限を引き上げてください
  • いつ再試行できるかについては、Retry-After ヘッダーを確認してください。