Wykonywanie zapytań o dane raportu

Metoda reportData.query umożliwia synchroniczne pobieranie danych raportu. W przeciwieństwie do standardowej Reports usługi, która generuje raporty w postaci plików (CSV lub Excel), ta metoda zwraca uporządkowane dane JSON bezpośrednio w odpowiedzi. Eliminuje to konieczność wcześniejszego definiowania, tworzenia i zapisywania zasobu Report, co sprawia, że jest to idealne rozwiązanie do pobierania i eksplorowania danych w czasie rzeczywistym.

Przegląd

Zapoznaj się z tym przewodnikiem, aby dowiedzieć się, jak używać tego punktu końcowego do wysyłania zapytań o dane raportowania Campaign Managera 360.

Przygotowanie żądania

Utwórz ReportDataQueryRequest określając wymiary, dane, zakres dat, filtry i kryteria sortowania.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Obiekt DateRange określający okres, którego dotyczy zapytanie. Może to być niestandardowy lub względny zakres dat.
dimensionNames
Lista standardowych nazw wymiarów, według których mają być grupowane dane.
metricNames
Wymagane. Lista standardowych nazw danych do uwzględnienia.
dimensionFilters
Lista obiektów DimensionValue używanych do filtrowania danych raportu. Użyj tej opcji, aby ograniczyć wyniki zapytania do określonych wartości wymiaru.
sortBys
Konfiguracje sortowania według wymiarów lub danych. Każda konfiguracja zawiera nazwę pola i kolejność sortowania.
maxResults
Maksymalna liczba wierszy do zwrócenia na stronie (domyślnie: 100, maksymalnie: 1000).

Podział na strony

Pole maxResults określa liczbę wyników zwracanych w pojedynczej odpowiedzi. Jeśli na przykład ustawisz maxResults na 10, interfejs API zwróci co najwyżej 10 wyników. Może się zdarzyć, że interfejs API zwróci mniej niż 10 wyników, jeśli liczba wyników pasujących do Twojego żądania jest mniejsza niż 10.

Jeśli dostępne są dodatkowe wyniki, odpowiedź zawiera nextPageToken. Aby pobrać następną stronę wyników, wyślij ponownie to samo żądanie, ustawiając pole pageToken na ten token. Pozostałe parametry żądania pozostaw bez zmian.

Wysyłanie żądania

Wyślij żądanie HTTP POST do reportdata/query punktu końcowego:

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

Upewnij się, że żądanie jest uwierzytelnione za pomocą standardowych danych logowania OAuth 2.0 i niezbędnych zakresów. Więcej informacji znajdziesz w sekcji Autoryzowanie żądań.

Odpowiedź pomyślna

Pomyślne zapytanie zwraca odpowiedź HTTP 200 OK z ładunkiem JSON zawierającym columnHeaders, rows i totalRow.

{
  "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
Nazwa i typy (DIMENSION lub METRIC) zwracanych pól.
rows
Lista obiektów ReportDataRow zawierających wyniki zapytania. Wartości ciągów w każdym wierszu są wyrównane według pozycji z columnHeaders.
totalRow
Pojedynczy wiersz agregacji reprezentujący sumę wszystkich pasujących danych. Pola wymiarów i dane, których nie można zsumować (np. dane o zasięgu, takie jak uniqueReachTotalReach) są w tym wierszu puste ("").
nextPageToken
Token używany w kolejnym żądaniu do pobrania następnej strony, jeśli istnieją dodatkowe wiersze.

Opóźnienie i przekroczenie limitu czasu

Ponieważ jest to synchroniczny punkt końcowy, zapytania są wykonywane natychmiast, a dane są zwracane bezpośrednio w odpowiedzi (do limitu podziału na strony maxResults). Maksymalny czas wykonywania zapytań to 60 sekund. Jeśli zapytanie przekroczy ten limit, interfejs API zakończy operację i zwróci błąd HTTP 503 Service Unavailable.

Jeśli wystąpi ten błąd, spróbuj zawęzić zakres dat, ograniczyć filtry (np. filtrować według konkretnych reklamodawców lub kampanii) albo zmniejszyć liczbę żądanych wymiarów i danych. Możesz też uruchomić Report za pomocą reports.run, aby asynchronicznie wygenerować plik raportu do pobrania.

Limity i ograniczenia zapytań

Punkt końcowy reportdata.query wymusza kilka limitów, aby zapewnić niezawodne odpowiedzi. Żądania, które naruszają te ograniczenia, są odrzucane z odpowiedzią HTTP 400 Bad Request.

Limity zakresu dat

  • W przypadku niestandardowych zakresów dat startDate musi przypadać w okresie dostępności danych dla żądanego typu danych raportu. Więcej informacji znajdziesz w sekcji Dostępność danych.

Ograniczenia dotyczące danych i wymiarów

  • W metricNames trzeba podać co najmniej 1 dane.
  • Dane i wymiary na listach metricNames i dimensionNames muszą być unikalne.
  • Dane i wymiary oznaczone jako Tylko do pobrania nie mogą być używane w tych zapytaniach.

Limity przydziału

Żądania wysyłane do tego punktu końcowego wykorzystują te limity:

  • Limit liczby żądań na użytkownika: 120 żądań na minutę na użytkownika (2 żądania na sekundę)
  • Limit dzienny na projekt: 10 000 żądań dziennie na projekt

Żądania, które przekraczają te limity, kończą się niepowodzeniem i wyświetleniem błędu HTTP 429 Too Many Requests. Jeśli przeglądasz wyniki, każde żądanie nowej strony (za pomocą parametru pageToken) jest liczone jako osobne zapytanie i wykorzystuje ten limit.