أصبحت Search Ads 360 Reporting API الجديدة متاحة الآن. يمكنك الانضمام إلى مجموعة Google searchads-api-announcements لتبقى على اطّلاع على التحسينات والإصدارات القادمة.
يمكنك إنشاء طلبات بحث باستخدام إحدى الطريقتين Search أو SearchStream.
تتيح كلتا الطريقتين طلبات البحث نفسها وتعرضان نتائج مكافئة. تعرض الطريقة
Search البيانات بأحجام صفحات قابلة للتخصيص، ما يتيح لك تكرار مجموعة نتائج باستخدام تقسيم الصفحات. قد يكون ذلك مفيدًا في حال توفّر معدّل نقل بيانات منخفض أو في حال عدم استقرار الشبكة، مثلاً لتقسيم مجموعة نتائج كبيرة إلى ردود أصغر يمكن إعادة جلبها في حال فقدان الاتصال. في المقابل، تعرض الطريقة
SearchStream مجموعة النتائج بأكملها في ردّ واحد، ما قد يكون أكثر فعالية لاسترداد البيانات المجمّعة.
يستخدم كل من Search وSearchStream عنوان URL الأساسي نفسه:
تتضمّن طريقة البحث المستندة إلى الصفحة المَعلمة الاختيارية pageSize التي تحدّ من عدد النتائج التي يتم عرضها في ردّ واحد من واجهة برمجة التطبيقات.
POST/v0/customers/CUSTOMER_ID/searchAds360:searchHTTP/1.1Host:searchAds360.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_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'"}
إذا كان عدد الصفوف في النتائج أكبر من pageSize، سيتم عرض nextPageToken في الرد:
يؤدي تكرار طلب البحث نفسه مع إضافة pageToken بالقيمة أعلاه إلى عرض الصفحة التالية من النتائج:
POST/v0/customers/CUSTOMER_ID/searchAds360:searchHTTP/1.1Host:searchads360.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_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"}
لاستخدام طريقة SearchStream، التي تعرض جميع النتائج في استجابة واحدة يتم بثها، ما عليك سوى تغيير طريقة الخدمة في عنوان URL إلى searchStream (لا تتطلّب SearchStream استخدام pageSize وpageToken):
POST/v0/customers/CUSTOMER_ID/searchAds360:searchStreamHTTP/1.1Host:searchads360.googleapis.comContent-Type:application/jsonAuthorization: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'"}
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Search Ads 360 Reporting API allows you to create complex queries using the Search Ads 360 Query Language to retrieve large amounts of data.\u003c/p\u003e\n"],["\u003cp\u003eYou can retrieve data using either the \u003ccode\u003eSearch\u003c/code\u003e or \u003ccode\u003eSearchStream\u003c/code\u003e methods, both supporting the same queries but differing in data delivery.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eSearch\u003c/code\u003e method offers pagination for handling large datasets, returning results in customizable page sizes controlled by the \u003ccode\u003epageSize\u003c/code\u003e parameter.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eSearchStream\u003c/code\u003e method streams the entire result set in a single response, ideal for efficient bulk data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eClient libraries simplify pagination with the \u003ccode\u003eSearch\u003c/code\u003e method, automatically handling subsequent page requests.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API uses `Search` and `SearchStream` methods for data retrieval via queries. `Search` allows paginated results using the `pageSize` parameter (defaulting to 10,000) and `nextPageToken` for subsequent pages. Conversely, `SearchStream` delivers the complete dataset in a single response, streamlining bulk data acquisition and not needing the `pageSize` or `pageToken`. Both use the same base URL with differing method names, but are distinct in how they return the data.\n"],null,["# Search & SearchStream\n\n| **Note:** See the [Search](/search-ads/reporting/api/reference/rest/examples#search) section of the accompanying examples for more complete examples.\n\nThe Search Ads 360 Reporting API has a unified [attribute retrieval and metrics reporting\nmechanism](/search-ads/reporting/concepts/search-reports)\nthat lets you create queries using the [Search Ads 360 Query\nLanguage](/search-ads/reporting/query/query-language).\nThis enables complex queries that can return large quantities of data about\nindividual Search Ads 360 accounts.\n\nYou can create queries using either of the `Search` or `SearchStream` methods.\nBoth methods support the same queries and return equivalent results. The\n`Search` method returns data in customizable page sizes, enabling you to iterate\nover a result set using pagination. This could be advantageous in low bandwidth\nor unreliable network conditions, for example, to segment a large result set\ninto smaller responses that can be re-fetched if a connection is lost. The\n`SearchStream` method, on the other hand, streams the entire result set back in\na single response, which can be more efficient for bulk data retrieval.\n\nBoth `Search` and `SearchStream` use the same base URL: \n\n```html\n https://searchAds360.googleapis.com/v0/customers/CUSTOMER_ID/searchAds360\n```\n\nThe page-based search method takes an optional `pageSize` parameter which limits\nhow many results are returned in a single API response.\n**Note:** The `pageSize` parameter is optional and will default to 10,000 if not explicitly set. \n\n```http\nPOST /v0/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/searchAds360:search HTTP/1.1\nHost: searchAds360.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\n\n{\n\"pageSize\": 10000,\n\"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'\"\n}\n```\n\nIf there are more rows in the results than `pageSize`, a `nextPageToken` is\nreturned in the response: \n\n```javascript\n{\n \"results\": [\n // ...\n // ...\n // ...\n ],\n \"nextPageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\",\n \"fieldMask\": \"adGroupCriterion.keyword.text,adGroupCriterion.status\"\n}\n```\n\nRepeating the same query with a `pageToken` added with the value above fetches\nthe next page of results: \n\n```http\nPOST /v0/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/searchAds360:search HTTP/1.1\nHost: searchads360.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\n\n\n{\n\"pageSize\": 10000,\n\"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'\",\n\"pageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\"\n}\n```\n| **Note:** The provided client libraries handle pagination automatically, eliminating the need to repeatedly query to return each subsequent page. See an [example of using pagination in the client libraries](/search-ads/reporting/concepts/pagination#pagination_example).\n\nTo use the `SearchStream` method, which returns all results in a single streamed\nresponse, simply change the service method in the URL to `searchStream`\n(`pageSize` and `pageToken` are not required by `SearchStream`): \n\n```http\nPOST /v0/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/searchAds360:searchStream HTTP/1.1\nHost: searchads360.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\n\n{\n \"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'\"\n}\n```\n| **Note:** The results of a `SearchStream` API call are wrapped in a JSON array, whereas most other API calls return a single JSON object as the response message. See the [JSON mappings](/search-ads/reporting/api/reference/rest/json-mappings) section for more info."]]
