جستجو & SearchStream

ویدئوی : گزارش‌دهی

API گوگل ادز دارای یک مکانیزم یکپارچه برای بازیابی ویژگی‌ها و گزارش معیارها است که به شما امکان می‌دهد با استفاده از زبان جستجوی گوگل ادز، پرس‌وجو ایجاد کنید. این امر پرس‌وجوهای پیچیده‌ای را امکان‌پذیر می‌کند که می‌توانند حجم زیادی از داده‌ها را در مورد حساب‌های کاربری گوگل ادز منفرد برگردانند.

شما می‌توانید با استفاده از هر یک از روش‌های Search یا SearchStream پرس‌وجوهایی ایجاد کنید. هر دو روش از پرس‌وجوهای یکسانی پشتیبانی می‌کنند و نتایج معادلی را برمی‌گردانند. روش Search داده‌ها را در صفحاتی با اندازه ثابت ۱۰۰۰۰ ردیف برمی‌گرداند و به شما امکان می‌دهد با استفاده از صفحه‌بندی، روی یک مجموعه نتیجه تکرار کنید. این می‌تواند در شرایط پهنای باند کم یا شبکه غیرقابل اعتماد، مثلاً برای تقسیم یک مجموعه نتیجه بزرگ به پاسخ‌های کوچکتر که در صورت قطع اتصال قابل بازیابی مجدد باشند، مفید باشد. از سوی دیگر، روش SearchStream کل مجموعه نتیجه را در یک پاسخ واحد پخش می‌کند که می‌تواند برای بازیابی داده‌های حجیم کارآمدتر باشد.

هر دو Search و SearchStream از یک URL پایه یکسان استفاده می‌کنند:

    https://googleads.googleapis.com/v22/customers/CUSTOMER_ID/googleAds
POST /v22/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'"
}

اگر بیش از ۱۰،۰۰۰ ردیف در نتایج وجود داشته باشد، یک nextPageToken در پاسخ بازگردانده می‌شود:

{
  "results": [
    // ...
    // ...
    // ...
  ],
  "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

تکرار همان کوئری با یک pageToken که با مقادیر درخواست قبلی اضافه شده است، صفحه بعدی نتایج را واکشی می‌کند:

POST /v22/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 تغییر دهید ( SearchStream نیازی به pageToken ندارد):

POST /v22/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'"
}