تتضمّن Google Ads API آلية موحّدة لاسترداد السمات وإعداد تقارير المقاييس تتيح لك إنشاء طلبات بحث باستخدام لغة طلبات البحث في إعلانات Google. ويتيح ذلك إنشاء طلبات بحث معقّدة يمكنها عرض كميات كبيرة من البيانات حول حسابات فردية على "إعلانات Google".
يمكنك إنشاء طلبات بحث باستخدام إحدى الطريقتَين Search أو SearchStream.
تتيح كلتا الطريقتَين طلبات البحث نفسها وتعرضان نتائج متطابقة. تعرض الطريقة Search البيانات في صفحات ذات حجم ثابت يضم 10,000 صف، ما يتيح لك تكرار مجموعة النتائج باستخدام تقسيم الصفحات. قد يكون ذلك مفيدًا في حالات النطاق الترددي المنخفض أو ظروف الشبكة غير الموثوق بها، على سبيل المثال، لتقسيم مجموعة نتائج كبيرة إلى استجابات أصغر يمكن إعادة جلبها في حال فقدان الاتصال. في المقابل، تنقل الطريقة SearchStream مجموعة النتائج بالكامل في استجابة واحدة، ما قد يكون أكثر فعالية لاسترداد البيانات المجمّعة.
تستخدم الطريقتان Search وSearchStream عنوان URL الأساسي نفسه:
https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds
POST /v25/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 /v25/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 /v25/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'" }