الإبلاغ عن البث باستخدام 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 |
بحث |
| حجم الصفحة |
غير سارية |
10,000 صف لكل صفحة |
| عدد الطلبات المقدَّمة إلى واجهة برمجة التطبيقات |
طلب واحد |
10 طلبات |
| عدد الردود من واجهة برمجة التطبيقات |
بث مباشر واحد متواصل |
10 ردود |
في معظم حالات الاستخدام، ننصحك باستخدام SearchStream بدلاً من Search للأسباب التالية:
بالنسبة إلى التقارير المكوّنة من صفحة واحدة (أقل من 10,000 صف)، لا توجد اختلافات كبيرة في الأداء بين الطريقتين.
بالنسبة إلى التقارير المتعددة الصفحات، يكون SearchStream أسرع عادةً لأنّه يتجنّب عمليات نقل البيانات المتعددة، كما أنّ القراءة أو الكتابة من ذاكرة التخزين المؤقت على القرص لا تشكّل عاملاً مهمًا.
حدود معدّل الاستخدام
تلتزم الحدود اليومية لكلتا الطريقتين بالحدود العادية ومستويات
الوصول لرمز المطوّر المميز. يتم احتساب طلب بحث أو تقرير واحد كعملية واحدة بغض النظر عمّا إذا كانت النتيجة مقسّمة إلى صفحات أو يتم بثها.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
