ל-Google Ads API יש מנגנון מאוחד לאחזור מאפיינים ולדיווח על מדדים, שמאפשר ליצור שאילתות באמצעות שפת השאילתות של Google Ads. האפשרות הזו מאפשרת להריץ שאילתות מורכבות שיכולות להחזיר כמויות גדולות של נתונים על חשבונות Google Ads ספציפיים.
אפשר ליצור שאילתות באמצעות ה-method Search או SearchStream.
שתי השיטות תומכות באותן שאילתות ומחזירות תוצאות שוות ערך. השיטה Search מחזירה נתונים בדפים בגודל קבוע של 10,000 שורות, ומאפשרת לכם לחזור על קבוצת תוצאות באמצעות עימוד. זה יכול להיות שימושי בתנאי רשת לא יציבים או עם רוחב פס נמוך. לדוגמה, כדי לחלק קבוצת תוצאות גדולה לתגובות קטנות יותר שאפשר לאחזר מחדש אם החיבור אבד. לעומת זאת, ה-method SearchStream מחזיר את כל מערך התוצאות בתשובה אחת, מה שיכול להיות יעיל יותר לאחזור נתונים בכמות גדולה.
גם Search וגם SearchStream משתמשים באותה כתובת URL בסיסית:
https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds
POST /v26/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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'" }
אם יש יותר מ-10,000 שורות בתוצאות, התשובה תכיל את הערך nextPageToken:
{ "results": [ // ... // ... // ... ], "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B", "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status" }
אם חוזרים על אותה שאילתה עם הפרמטר pageToken שנוסף עם הערכים מהבקשה הקודמת, מקבלים את דף התוצאות הבא:
POST /v26/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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'", "pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" }
כדי להשתמש ב-SearchStream, שמחזירה את כל התוצאות בתגובה אחת בסטרימינג, צריך לשנות את השיטה של השירות בכתובת ה-URL ל-searchStream (pageToken לא נדרש ב-SearchStream):
POST /v26/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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'" }