インテグレーションの基本とFAQs
インテグレーションの基本とFAQs

StatusbrewのインサイトAPI

StatusbrewのインサイトAPIは、Statusbrewからアナリティクスデータをあなた独自のダッシュボード、BIツール、データウェアハウスに提供します。外部のレポートシステムやSLAトラッキング、顧客分析ワークフローでStatusbrewのデータを活用したいチームに向けた機能です。

利用可能プラン

インサイトAPIは下記のプランでご利用いただける機能です。

  • Enterpriseプラン ：Enterpriseプランに含まれています。あなたのアカウントでも使えるようにするには、アカウント管理者、またはsales@statusbrew.comまでご連絡ください。

  • Premiumプラン：アドオンでご利用いただくことが可能です。年間一括払いの場合は月額29,900円、月払いの場合は月額39,900円でご利用いただけます。詳細は、sales@statusbrew.comまでお問合せください。

こちらの機能の利用についてはアカウント管理者にご確認いただくか、

認証

すべてのAPIリクエストには、 Authorization ベアラートークンを含むヘッダーが必要です。トークンはアカウントが有効化した際にStatusbrewのアカウントマネージャーによって発行されます。

すべてのリクエストに以下を含めてください。

Authorization: Bearer YOUR_API_TOKEN

APIトークンは安全に保管してください。クライアント側のコードや公開リポジトリなど、人目につく場所に保管しないようにしましょう。トークンのローテションが必要な場合はアカウント管理者に連絡してください。

ベースURL

すべてのAPIリクエストは下記のベースURLを使用します。

https://api.statusbrew.com/v1

インサイトAPIを使いはじめる

StatusbrewインサイトAPIの使い方を理解して、最初のリクエストを成功させましょう。F

  • ステップ 1. トークンの確認

  • ステップ 2. ヘルパーの理解

  • ステップ 3. メトリクスと設定

  • ステップ 4. インサイト

完全なリファレンスは、APIドキュメントをご確認ください。

トークンの確認

これによりベアラートークンが確認され、ユーザーID、メールアドレス、タイムゾーンを含むアカウントの詳細情報が返されます。他のリクエストを行う前にこのエンドポイントを呼び出してください。

エンドポイント

GET /me

ヘルパー

下記のエンドポイントを使ってインサイトのクエリのペイロードとして使用するエンティティデータを取得します。

完全なリファレンスは、APIドキュメントをご確認ください。

組織の取得

あなたが属している組織を、組織ID、名前、オーナーシップステータスと共に返します、特定の組織のメンバーを取得するためには、id 値 (orgn_xxxxx) を用いてください。

レスポンスのid フィールド(例： orgn_xxxxx) が組織IDです。

エンドポイント

GET /organizations

組織のユーザー

特定の組織の全ユーザーの役割、ステータス、詳細情報を返します。組織のオーナーだけがこのエンドポイントを呼び出すことが可能です。チームベースのフィルターやデータアクセスを割り当てる際に、メンバーの id 値を使用してください。

エンドポイント

GET /organizations/{organizationId}/members

スペースの取得

組織における全スペースの一覧を返します。

このレスポンスでは、 id フィールド(例： spce_xxxxx) はあなたのスペースIDです。以降の呼び出しで必ずこのIDが必要になります。

エンドポイント

GET /spaces

スペースソーシャルチャネルの取得

スペースに接続している全ソーシャルプロファイルを、ネットワークタイプ、URN、ユーザーネーム、認証スタータスを含めて返します。 POST /insightsで特定のプロファイルに絞り込むには、 URN の値を dataSources フィルタ値として使用してください。

エンドポイント

GET /spaces/{spaceId}/channels

スペースタグの取得

スペース内の全タグを、名前、利用箇所、親タグ、ステータスを含めて返します。タグディメンションでインサイトデータを照会する場合は、タグIDをフィルター値としてください。

エンドポイント

GET /spaces/{spaceId}/tags

指標

これらのエンドポイントを使って、インサイトクエリを作成する前に、利用可能なレポート指標、ディメンション、フィルター、アグリゲーターを確認してください。

完全なリファレンスは、APIドキュメントをご確認ください。

指標、カテゴリ、デイメンションの取得

スペースで利用可能な全指標をカテゴリ別に分類して返します。各指標には名前、ラベル、概要、サポートされているネットワークが含まれます。このレスポンスの name 値は、GET /report_metric_config/{metricName}と POST /insightsへの入力として使用してください。

現在、22のカテゴリで250以上の指標がサポートされています。

利用可能な全指標とその概要は分析指標一覧でご確認いただけます。

エンドポイント

GET /spaces/{spaceId}/report_metrics

サポートされているディメンション、フィルター、アグリゲーターの取得

特定のディメンション、フィルター、比較オペレーター、アグリゲーター関数を返します。サポートされていないデイメンションやフィルターを使用するとエラーになるため、 POST /insights クエリを構築する前にこのエンドポイントを呼び出して、有効な組み合わせのみを渡すようにしてください。

エンドポイント

GET /spaces/{spaceId}/report_metric_config/{metricName}

API全体でサポートされているアグリゲーターは次の通りです：合計、平均、最小値、最大値。利用可能なアグリゲーターは指標によって異なります。

インサイトAPI

これらのエンドポイントを使って分析データを照会します。3つのエンドポイントは同じリクエストボディを受け入れます。ユースケースに合ったものを選択してください。

完全なリファレンスは、APIドキュメントをご確認ください。

レポートの取得

スペース内の全レポートをセクション、ウィジェット、データソース、保存されたフィルタを含めて返します。トップレベルの id フィールドが reportId です。sections[].grid[] 内の id の値が widgetId です。レポートレベルおよびウィジェットレベルのインサイトエンドポイントを使用するには両方が必要です。

レスポンスでは、トップレベルの id フィールド（例：rprt_xxxxx）がレポートIDです。sections[].grid[] 内の id の値（例：rpwd_xxxxx）がウィジェットIDです。

エンドポイント

GET /spaces/{spaceId}/reports

スペースIDによるインサイト

スペースにおける全プロファイルをデータソースとして使用してアナリティクスを照会します。最も柔軟なバリアントで、プロファイルを横断したレポートや特定の保存されたレポートに関係なく照会したいときに便利です。 filters 値を使って特定のネットワークやプロファイルに絞り込むことができます。

エンドポイント

POST /spaces/{spaceId}/insights

レポートIDによるインサイトInsights with Report ID

特定のレポートのコンテキスト内でアナリティクスを照会し、そのレポートに保存されたデータソースとフィルターを自動的に適用します。APIの結果をStatusbrewのレポートでユーザーが見る内容と一致させたい場合に使用します。ignoreReportFilters: true を渡すと、レポートの保存済みフィルターをバイパスして生データを照会できます。

End Point

POST /reports/{reportId}/insights

ウィジェットIDによるインサイトInsights with Widget ID

レポートで特定のウィジェットを動かしているデータを返します。ウィジェットのデータをプログラムで複製またはエクスポートする場合に使用します。reportId と widgetId は GET /spaces/{spaceId}/reports から取得してください。

エンドポイント

POST /reports/{reportId}/widgets/{widgetId}/insights

エラーコード

このAPIは標準的なHTTPステータスコードを使用しています。全てのエラーコードとその対処法はAPIドキュメントに掲載しています。

  • 200: 成功

  • 400: 不正なリクエストです。リクエストボディまたはパラメータを確認してください。

  • 403: アクセス拒否。あなたのトークンにはこのリソースへのアクセス権限がありません。

  • 404: 見つかりません。リクエストされたソースは存在しません。

  • 405: 許可されていないメソッドです。

  • 415:サポートされていないメディアタイプです。 Content-Type: application/json が設定されていることを確認してください。

  • 429: レート制限を超過しています。APIは5分間に50リクエストまで許可されています。時間をあけて再度お試しください。

  • 500: 内部サーバーエラー。

  • 503: サービス利用不可。

  • 524: タイムアウトが発生しました。

FAQs

インサイトAPIへアクセスするにはどうしたらよいですか？

Enterpriseプランの場合、自動的に使えるのではなく、リクエストいただくことでご利用が可能になります。Puremiumプランではアドオン（年間一括払い月額29,900円、月払い月額39,900円）となります。どちらのプランの場合もアカウント管理者、またはsales@statusbrew.com までご連絡ください。

どこでAPIトークンを確認できますか？

APIトークンはStatusbrewアカウントマネージャーにより発行されます。製品UIで自己生成されるものではありません。tokenの発行またはローテーションについてはアカウント管理者にご確認ください。

トークンが漏洩した場合、どうしたらよいですか？

直ちにアカウント管理者に報告し、そのトークンを無効化し、新しいトークンを発行してもらってください。

スペースIDはどこで確認できますか？

GET /spacesを呼び出します。所属しているスペースの一覧が id を含めて返されます。以降のリクエストでは spaceId として使用してください。

Enterpriseプランを契約中ですがAPIセクションを見つけられません。

専任のアカウント管理者に問い合わせるか、またはsales@statusbrew.comまでご連絡ください。アクセスが有効化されているかを確認し、トークンを発行します。

どのインサイトエンドポイントを使うべきですか？

それぞれ下記をお使いください。

・スペース内のすべてのプロファイルに対して汎用的に照会する場合：POST /spaces/{spaceId}/insights ・特定のレポートのコンテキスト内で照会する場合：POST /reports/{reportId}/insights ・特定のウィジェットのデータを取得する場合： POST /reports/{reportId}/widgets/{widgetId}/insights

指標で利用可能なデイメンションとフィルターを確認したい

各指標で利用可能なディメンション、フィルター、アグリゲーターは異なります。照会したい指標で利用可能な内容を確認するには、GET /spaces/{spaceId}/report_metric_config/{metricName} を呼び出してください。

APIを通して投稿レベルのデータは取得できますか？

はい。post ディメンションを使用して post_total メトリクスの内訳を出し、パーマリンクを含む投稿レベルの詳細を取得できます。このメトリクスでサポートされている全ディメンションとフィルターの一覧は、GET /spaces/{spaceId}/report_metric_config/post_total を呼び出して確認してください。

レート制限はありますか？

はい。このAPIは5分間で50リクエストまで許可しています。それを超過するとエラー 429 となります。時間をあけて再試行してください。

インサイトAPIでは何ができますか？

インサイトAPIを使うと、Statusbrewのレポートやアナリティクスデータをご自身のツールやワークフローに取り込むことができます。APIは読み取り専用のため、データを取得することはできますが、作成・更新・削除はできません。

POSTエンドポイントはどのように呼び出したらよいですか？

POSTエンドポイントはご自身のアプリケーションやバックエンド、PostmanAPIクライアントから呼び出してください。