クエリレポートのデータ

reportData.query メソッドは、レポートデータを同期的に取得する方法を提供します。ファイルベースのレポート（CSV または Excel）を生成する標準の Reports サービスとは異なり、このメソッドは構造化された JSON データをレスポンスで直接返します。Report リソースを事前に定義、作成、保存する必要がないため、リアルタイムのデータ取得と探索に最適です。

概要

このガイドでは、このエンドポイントを使用してキャンペーン マネージャー 360 のレポートデータをクエリする方法について説明します。

リクエストを作成する

ディメンション、指標、期間、フィルタ、並べ替え条件を指定して、ReportDataQueryRequest を作成します。

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
: クエリの期間を指定する DateRange オブジェクト。カスタム期間または相対期間を指定できます。
dimensionNames
グループ化する標準ディメンション名のリスト。
metricNames
必須。含める標準指標名のリスト。
dimensionFilters
レポートデータのフィルタリングに使用される DimensionValue オブジェクトのリスト。これを使用して、クエリ結果をディメンションの特定の値に制限します。
sortBys
ディメンションまたは指標の並べ替え構成。各構成には、フィールド名と並べ替え順序が含まれます。
maxResults
ページごとに返す最大行数（デフォルト: 100、最大: 1000）。

ページネーション

maxResults フィールドは、1 回のレスポンスで返される結果の数を制御します。たとえば、maxResults を 10 に設定すると、API は最大 10 件の結果を返します。リクエストに一致する結果が 10 件未満の場合、API から返される結果が 10 件未満になることがあります。

追加の結果がある場合、レスポンスには nextPageToken が含まれます。結果の次のページを取得するには、pageToken フィールドをこのトークンに設定して、同じリクエストをもう一度送信します。他のすべてのリクエスト パラメータは同じままにします。

リクエストを送信する

HTTP POST リクエストを reportdata/query エンドポイントに送信します。

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

リクエストが標準の OAuth 2.0 認証情報と必要なスコープで認証されていることを確認します。詳細については、リクエストを承認するをご覧ください。

成功したレスポンス

クエリが成功すると、columnHeaders、rows、totalRow を含む JSON ペイロードを含む HTTP 200 OK レスポンスが返されます。

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
返されるフィールドの名前と型（DIMENSION または METRIC）。
rows
クエリ結果を含む ReportDataRow オブジェクトのリスト。各行の文字列値は、columnHeaders と位置的に対応しています。
totalRow
一致するすべての指標の合計を表す単一の集計行。この行では、合計できないディメンション フィールドと指標（リーチ指標の uniqueReachTotalReach など）は空（""）になります。
nextPageToken
追加の行が存在する場合に、次のページを取得するために後続のリクエストで使用されるトークン。

レイテンシとタイムアウト

これは同期エンドポイントであるため、クエリはすぐに実行され、データはレスポンスで直接返されます（maxResults ページネーションの上限まで）。クエリの最大実行時間は 60 秒です。クエリがこの上限を超えると、API はオペレーションを終了し、HTTP 503 Service Unavailable エラーを返します。

このエラーが発生した場合は、期間を絞り込むか、フィルタを絞り込む（特定の広告主やキャンペーンでフィルタするなど）、またはリクエストするディメンションと指標の数を減らしてみてください。または、reports.run を使用して Report を実行し、ダウンロード可能なレポートファイルを非同期で生成します。

クエリの上限と制約

reportdata.query エンドポイントは、信頼性の高いレスポンスを確保するためにいくつかの制限を適用します。これらの制約に違反するリクエストは、HTTP 400 Bad Request レスポンスで拒否されます。

期間の上限

  • カスタム日付範囲の場合、startDate はリクエストされたレポート データ型のデータ利用可能期間内である必要があります。詳細については、データの可用性をご覧ください。

指標とディメンションの制約

  • metricNames に少なくとも 1 つの指標を指定する必要があります。
  • metricNames リストと dimensionNames リストの指標とディメンションは一意である必要があります。
  • 「ダウンロードのみ可能」とラベル付けされた指標とディメンションは、これらのクエリで使用できません。

割り当て上限

このエンドポイントに対するリクエストは、次の割り当てを消費します。

  • ユーザーのレート制限: ユーザーあたり 1 分あたり 120 件のリクエスト（2 QPS）
  • プロジェクトごとの 1 日あたりの上限: 1 プロジェクトあたり 1 日 10,000 件のリクエスト

これらの上限を超えるリクエストは、HTTP 429 Too Many Requests エラーで失敗します。結果をページングする場合、新しいページのリクエスト（pageToken パラメータを使用）は個別のクエリとしてカウントされ、この割り当てから消費されます。