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