API جدید Search Ads 360 Reporting اکنون در دسترس است. به گروه Google searchads-api-announcements بپیوندید تا در مورد پیشرفت‌ها و نسخه‌های آینده به‌روز باشید.
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
Search Ads 360 Reporting API یک مکانیسم یکپارچه بازیابی ویژگی و گزارش سنجه دارد که به شما امکان می‌دهد با استفاده از زبان جستجوی Search Ads 360 عبارت‌هایی ایجاد کنید. این پرس‌وجوهای پیچیده را فعال می‌کند که می‌توانند مقادیر زیادی از داده‌ها را درباره حساب‌های منفرد Search Ads 360 برگردانند.
می توانید با استفاده از یکی از روش های Search یا SearchStream کوئری ایجاد کنید. هر دو روش از پرس و جوهای یکسانی پشتیبانی می کنند و نتایج معادل را برمی گردانند. روش Search داده‌ها را در اندازه‌های صفحه قابل تنظیم برمی‌گرداند و شما را قادر می‌سازد تا با استفاده از صفحه‌بندی روی مجموعه نتایج تکرار کنید. این می تواند در شرایط شبکه با پهنای باند کم یا غیرقابل اعتماد مفید باشد، به عنوان مثال، برای تقسیم یک مجموعه نتیجه بزرگ به پاسخ های کوچکتر که می توانند در صورت قطع اتصال دوباره واکشی شوند. از سوی دیگر، روش SearchStream ، کل نتیجه مجموعه را در یک پاسخ پخش می‌کند، که می‌تواند برای بازیابی اطلاعات انبوه کارآمدتر باشد.
هر دو Search و SearchStream از یک URL اصلی استفاده می کنند:
روش جستجوی مبتنی بر صفحه یک پارامتر pageSize اختیاری می گیرد که تعداد نتایج بازگردانده شده در یک پاسخ API را محدود می کند.
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 تغییر دهید ( pageSize و pageToken توسط SearchStream مورد نیاز نیستند):
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."]]
