گزارش جریان با استفاده از GoogleAdsService
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
برای بازیابی موجودیت‌های Google Ads API و داده‌های گزارش، از یکی از این روش‌ها استفاده کنید:
در اینجا تمایزات سطح بالا برای این دو روش وجود دارد:
| GoogleAdsService.SearchStream | GoogleAdsService.Search |
|---|
| مناسب برای کد تولید | بله | بله |
|---|
| خدمات | GoogleAdsService | GoogleAdsService |
|---|
| سناریو | واکشی اشیا و گزارش ها | واکشی اشیا و گزارش ها |
|---|
| پاسخ | جریان اشیاء GoogleAdsRow | صفحات اشیاء GoogleAdsRow |
|---|
| فیلدهای پاسخ | فقط آنهایی که در پرس و جو مشخص شده اند | فقط آنهایی که در پرس و جو مشخص شده اند |
|---|
| محدودیت های روزانه | محدودیت های روزانه بر اساس سطوح دسترسی | محدودیت های روزانه بر اساس سطوح دسترسی |
|---|
SearchStream در مقابل Search
در حالی که Search می‌تواند چندین درخواست صفحه‌بندی شده برای دانلود کل گزارش ارسال کند، SearchStream یک درخواست را ارسال می‌کند و بدون در نظر گرفتن اندازه گزارش، اتصال دائمی با Google Ads API را آغاز می‌کند.
برای SearchStream ، بسته‌های داده بلافاصله شروع به دانلود می‌کنند و کل نتیجه در یک بافر داده ذخیره می‌شود. کد شما می‌تواند شروع به خواندن داده‌های بافر کند بدون اینکه منتظر بمانید تا کل جریان به پایان برسد.
با حذف زمان رفت و برگشت شبکه مورد نیاز برای درخواست هر صفحه جداگانه از یک پاسخ Search ، بسته به برنامه شما، SearchStream می‌تواند عملکرد بهتری را نسبت به صفحه‌بندی، به ویژه برای گزارش‌های بزرگ‌تر، ارائه دهد.
مثال
این مثال به گزارشی می‌پردازد که از 100,000 ردیف تشکیل شده است. جدول زیر تفاوت های حسابداری بین این دو روش را نشان می دهد.
| SearchStream | جستجو کنید |
|---|
| اندازه صفحه | قابل اجرا نیست | 10000 ردیف در هر صفحه |
|---|
| تعداد درخواست های API | 1 درخواست | 10 درخواست |
|---|
| تعداد پاسخ های API | 1 جریان پیوسته | 10 پاسخ |
|---|
برای بیشتر موارد استفاده، به دلایل زیر SearchStream از طریق Search توصیه می کنیم:
برای گزارش های تک صفحه ای (زیر 10000 ردیف): تفاوت عملکرد قابل توجهی بین دو روش وجود ندارد.
برای گزارش‌های چند صفحه‌ای: SearchStream معمولاً سریع‌تر است، زیرا از چندین سفر رفت و برگشت اجتناب می‌شود، و خواندن یا نوشتن از حافظه پنهان دیسک عامل کمتری است.
محدودیت های نرخ
محدودیت‌های روزانه برای هر دو روش از محدودیت‌های استاندارد و سطوح دسترسی توکن توسعه‌دهنده شما تبعیت می‌کنند. یک پرس و جو یا گزارش به عنوان یک عملیات بدون در نظر گرفتن نتیجه صفحه یا پخش جریانی حساب می شود.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-26 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-26 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe Google Ads API offers two primary methods for retrieving data: \u003ccode\u003eSearchStream\u003c/code\u003e and \u003ccode\u003eSearch\u003c/code\u003e, both suitable for production environments and fetching objects and reports.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eSearchStream\u003c/code\u003e delivers results as a continuous stream, ideal for large reports, while \u003ccode\u003eSearch\u003c/code\u003e provides paginated responses.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eSearchStream\u003c/code\u003e often offers performance advantages by reducing network round trips, especially for reports exceeding 10,000 rows.\u003c/p\u003e\n"],["\u003cp\u003eBoth methods are subject to the same daily limits and access levels, with a single query or report counting as one operation regardless of the method.\u003c/p\u003e\n"],["\u003cp\u003eGoogle recommends using \u003ccode\u003eSearchStream\u003c/code\u003e for most use cases due to its performance benefits for larger reports.\u003c/p\u003e\n"]]],[],null,["# Report streaming using GoogleAdsService\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nTo retrieve Google Ads API entities and reporting data, use one of these methods:\n\n- [`GoogleAdsService.SearchStream`](/google-ads/api/reference/rpc/v21/GoogleAdsService/SearchStream)\n- [`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search)\n\nHere are the high-level distinctions for the two methods:\n\n| | GoogleAdsService.SearchStream | GoogleAdsService.Search |\n| Suitable for production code | **Yes** | **Yes** |\n| Service | [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) | [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) |\n| Scenario | Fetching objects and reports | Fetching objects and reports |\n| Response | **Stream** of [`GoogleAdsRow`](/google-ads/api/reference/rpc/v21/GoogleAdsRow) objects | Pages of [`GoogleAdsRow`](/google-ads/api/reference/rpc/v21/GoogleAdsRow) objects |\n| Response's fields | Only those specified in the query | Only those specified in the query |\n| Daily limits | Daily limits based on [access levels](/google-ads/api/docs/access-levels) | Daily limits based on [access levels](/google-ads/api/docs/access-levels) |\n|------------------------------|----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|\n\n`SearchStream` versus `Search`\n------------------------------\n\nWhile [`Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) can send multiple\npaginated requests to download the entire report, [`SearchStream`](/google-ads/api/reference/rpc/v21/GoogleAdsService/SearchStream) sends a single request and\ninitiates a persistent connection with the Google Ads API regardless of report size.\n\nFor `SearchStream`, data packets start to download immediately with the entire\nresult cached in a data buffer. Your code can start reading the buffered data\nwithout having to wait for the entire stream to finish.\n\nBy eliminating the round-trip network time required to request each individual\npage of a `Search` response, depending on your app, `SearchStream` can offer\nimproved performance over paging, especially for bigger reports.\n\n### Example\n\nThis example looks at a report that consists of `100,000` rows. The following\ntable breaks down the accounting differences between the two methods.\n\n| | SearchStream | Search |\n| Page size | Not Applicable | 10,000 rows per page |\n| Number of API requests | 1 request | 10 requests |\n| Number of API responses | 1 continuous stream | 10 responses |\n|-------------------------|---------------------|----------------------|\n\n### Performance factors\n\nFor most use cases, we recommend `SearchStream` over `Search` for the following\nreasons:\n\n- For single page reports (under 10,000 rows): No significant performance\n differences between the two methods.\n\n- For multiple page reports: `SearchStream` is typically faster since multiple\n round trips are avoided, and reading or writing from disk cache is less of a\n factor.\n\n### Rate limits\n\nDaily limits for both methods adhere to the standard limits and [access\nlevels](/google-ads/api/docs/access-levels) of your developer token. A single query or report\nis counted as one operation regardless of the result being paged or streamed."]]
