Berichtsdaten abfragen

Die Methode reportData.query bietet eine synchrone Möglichkeit, Berichtsdaten abzurufen. Im Gegensatz zum Standarddienst Reports, bei dem dateibasierte Berichte (CSV oder Excel) generiert werden, werden bei dieser Methode strukturierte JSON-Daten direkt in der Antwort zurückgegeben. Es ist nicht erforderlich, eine Report-Ressource im Voraus zu definieren, zu erstellen und zu speichern. Daher eignet es sich ideal für den Echtzeitabruf und die Echtzeitanalyse von Daten.

Übersicht

In dieser Anleitung erfahren Sie, wie Sie diesen Endpunkt verwenden, um Ihre Campaign Manager 360-Berichtsdaten abzufragen.

Anfrage vorbereiten

Erstellen Sie ein ReportDataQueryRequest und geben Sie die Dimensionen, Messwerte, den Zeitraum, die Filter und die Sortierkriterien an.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Ein DateRange-Objekt, das den Zeitraum für die Anfrage angibt. Das kann ein benutzerdefinierter oder ein relativer Zeitraum sein.
dimensionNames
Eine Liste mit Standarddimensionsnamen, nach denen gruppiert werden soll.
metricNames
Erforderlich. Eine Liste der Standardmesswertnamen, die eingeschlossen werden sollen.
dimensionFilters
Eine Liste von DimensionValue-Objekten, die zum Filtern der Berichtsdaten verwendet werden. Damit können Sie Abfrageergebnisse auf bestimmte Werte einer Dimension beschränken.
sortBys
Sortierkonfigurationen für Dimensionen oder Messwerte. Jede Konfiguration enthält den Feldnamen und eine Sortierreihenfolge.
maxResults
Die maximale Anzahl der Zeilen, die pro Seite zurückgegeben werden sollen (Standard: 100, Maximum: 1000).

Seitenumbruch

Mit dem Feld maxResults wird die Anzahl der Ergebnisse gesteuert, die in einer einzelnen Antwort zurückgegeben werden. Wenn Sie maxResults beispielsweise auf 10 setzen, gibt die API maximal 10 Ergebnisse zurück. Es ist möglich, dass die API weniger als 10 Ergebnisse zurückgibt, wenn weniger als 10 Ergebnisse mit Ihrer Anfrage übereinstimmen.

Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort ein nextPageToken. Wenn Sie die nächste Ergebnisseite abrufen möchten, senden Sie dieselbe Anfrage noch einmal und legen Sie das Feld pageToken auf dieses Token fest. Behalten Sie alle anderen Anfrageparameter bei.

Anfrage senden

Senden Sie eine HTTP-POST-Anfrage an den Endpunkt reportdata/query:

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

Achten Sie darauf, dass Ihre Anfrage mit standardmäßigen OAuth 2.0-Anmeldedaten und den erforderlichen Bereichen authentifiziert wird. Weitere Informationen finden Sie unter Anfragen autorisieren.

Erfolgreiche Antwort

Bei einer erfolgreichen Anfrage wird eine HTTP-200 OK-Antwort mit einer JSON-Nutzlast zurückgegeben, die columnHeaders, rows und totalRow enthält.

{
  "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
Der Name und die Typen (DIMENSION oder METRIC) der zurückgegebenen Felder.
rows
Eine Liste von ReportDataRow-Objekten, die die Suchergebnisse enthalten. Die Stringwerte in jeder Zeile werden nach Position mit dem columnHeaders ausgerichtet.
totalRow
Eine einzelne aggregierte Zeile, die die Summe aller übereinstimmenden Messwerte darstellt. Dimensionsfelder und Messwerte, die nicht summiert werden können (z. B. Messwerte für die Reichweite wie uniqueReachTotalReach), sind in dieser Zeile leer ("").
nextPageToken
Ein Token, das in einer nachfolgenden Anfrage verwendet wird, um die nächste Seite abzurufen, wenn zusätzliche Zeilen vorhanden sind.

Latenz und Zeitüberschreitungen

Da es sich um einen synchronen Endpunkt handelt, werden Abfragen sofort ausgeführt und Daten werden direkt in der Antwort zurückgegeben (bis zum maxResults-Paginierungslimit). Abfragen haben eine maximale Ausführungszeit von 60 Sekunden. Wenn eine Abfrage dieses Limit überschreitet, beendet die API den Vorgang und gibt einen HTTP 503 Service Unavailable-Fehler zurück.

Wenn dieser Fehler auftritt, versuchen Sie, den Zeitraum einzugrenzen, die Filter einzugrenzen (z. B. nach bestimmten Werbetreibenden oder Kampagnen zu filtern) oder die Anzahl der angeforderten Dimensionen und Messwerte zu reduzieren. Alternativ können Sie Report mit reports.run ausführen, um asynchron eine herunterladbare Berichtsdatei zu generieren.

Abfragelimits und ‑beschränkungen

Für den Endpunkt reportdata.query gelten mehrere Einschränkungen, um zuverlässige Antworten zu gewährleisten. Anfragen, die gegen diese Einschränkungen verstoßen, werden mit einer HTTP 400 Bad Request-Antwort abgelehnt.

Zeitraumlimits

  • Bei benutzerdefinierten Zeiträumen muss das startDate innerhalb des Zeitraums liegen, in dem Daten für den angeforderten Berichtsdatentyp verfügbar sind. Weitere Informationen finden Sie unter Datenverfügbarkeit.

Einschränkungen für Messwerte und Dimensionen

  • In metricNames muss mindestens ein Messwert angegeben werden.
  • Messwerte und Dimensionen in den Listen metricNames und dimensionNames müssen eindeutig sein.
  • Messwerte und Dimensionen, die mit Nur herunterladen gekennzeichnet sind, können in diesen Abfragen nicht verwendet werden.

Kontingentlimits

Für Anfragen an diesen Endpunkt werden die folgenden Kontingente verwendet:

  • Nutzerkontingent:120 Anfragen pro Minute und Nutzer (2 QPS)
  • Tägliches Limit pro Projekt:10.000 Anfragen pro Tag und Projekt

Anfragen, die diese Limits überschreiten, schlagen mit einem HTTP 429 Too Many Requests-Fehler fehl. Wenn Sie die Ergebnisse durchblättern, wird jede Anfrage für eine neue Seite (mit dem Parameter pageToken) als separate Abfrage gezählt und auf dieses Kontingent angerechnet.