レポートエンドポイント(/v1/reports/*)は、パフォーマンスを最適化しペイロードサイズを削減するために、配列ベースの専用レスポンス形式を使用します。このガイドでは、これらのレスポンスの解釈方法を説明します。
/v1/org/* や /v1/prompts/* などのその他のエンドポイントは、標準的な JSON オブジェクト
構造を使用しており、OpenAPI リファレンスに記載されています。
レポートのレスポンス構造
すべてのレポートエンドポイントは、次の最適化された形式でデータを返します:
レポートデータの解釈
配列の位置のマッピング
レポートのレスポンスを理解する鍵は、配列の位置がリクエストパラメーターと正確に対応していることです:
Dimensions 配列
値は、リクエスト内の dimensions の順序に対応します:
dimensions[0] → リクエストした 1 番目の dimension(hostname)
dimensions[1] → リクエストした 2 番目の dimension(path)
dimensions[2] → リクエストした 3 番目の dimension(date)
Metrics 配列
値は、リクエスト内の metrics の順序に対応します:
metrics[0] → リクエストした 1 番目の metric(count)
metrics[1] → リクエストした 2 番目の metric(share_of_voice)
マッピングの例
上記の最初の結果オブジェクトの場合:
- Hostname:
dimensions[0] = “example.com”
- Path:
dimensions[1] = “/some/path”
- Date:
dimensions[2] = “2023-10-01”
- Count:
metrics[0] = 10
- Share of Voice:
metrics[1] = 0.05
Info オブジェクト
info オブジェクトは、クエリに関するメタデータを提供します:
レポートのレスポンスを扱う
データの処理
配列形式を従来のオブジェクト構造に変換する例:
ベストプラクティス
- 常に
info.query オブジェクトを使用して、レスポンスデータの構造を把握してください
- 配列の位置をハードコードするのではなく、上記のマッピング例を使ってプログラムでレスポンスを処理してください
total_rows フィールドを使って追加データがあるかどうかを判断し、ページネーションを処理してください
- API の制限に達しないよう、レート制限ヘッダーを監視してください
- リクエストパラメーターがユースケースで想定される dimensions と metrics に一致しているか、検証してください
お困りの場合
予期しないレスポンス形式が返された場合や、特定のレポートレスポンスについて詳しく知りたい場合は、サポートチームまでお問い合わせください。