Interfejs Google Ads API ma ujednolicony mechanizm pobierania atrybutów i raportowania danych, który umożliwia tworzenie zapytań za pomocą języka zapytań Google Ads. Umożliwia to wykonywanie złożonych zapytań, które mogą zwracać duże ilości danych o poszczególnych kontach Google Ads.
Zapytania możesz tworzyć za pomocą jednej z metod Search lub SearchStream.
Obie metody obsługują te same zapytania i zwracają równoważne wyniki. Metoda Search zwraca dane w rozmiarach stron, które można dostosować, co umożliwia iterację zbioru wyników za pomocą podziału na strony. Może to być przydatne w przypadku niskiej przepustowości lub niestabilnego połączenia sieciowego, np. gdy chcesz podzielić duży zbiór wyników na mniejsze odpowiedzi, które można pobrać ponownie w przypadku utraty połączenia. Z kolei metoda SearchStream przesyła strumieniowo cały wynik z powrotem w pojedynczej odpowiedzi, co może być bardziej wydajne w przypadku zbiorczego pobierania danych.
Zarówno Search, jak i SearchStream używają tego samego podstawowego adresu URL:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
Metoda wyszukiwania na podstawie strony przyjmuje opcjonalny parametr pageSize, który ogranicza liczbę wyników zwracanych w pojedynczej odpowiedzi interfejsu API.
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}
Jeśli wyniki zawierają więcej wierszy niż wynosi pageSize, w odpowiedzi zwracany jest nextPageToken:
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
Jeśli powtórzysz to samo zapytanie z dodanym parametrem pageToken z podaną wyżej wartością, spowoduje to pobranie następnej strony wyników:
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}
Aby użyć metody SearchStream, która zwraca wszystkie wyniki w pojedynczej odpowiedzi przesyłanej strumieniowo, wystarczy zmienić metodę usługi w adresie URL na searchStream (pageSize i pageToken nie są wymagane przez SearchStream):
POST /v17/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}