GoogleAdsService.SearchStream همه ردیف ها را در یک پاسخ جریانی برمی گرداند که برای مجموعه نتایج بزرگ (بیش از 10000 ردیف) کارآمدتر است. اگر برنامه دسته‌ای شما بخواهد داده‌ها را با بیشترین سرعت ممکن دانلود کند، ممکن است مناسب‌تر باشد.
GoogleAdsService.Search پاسخ های بزرگ را به صفحات قابل مدیریت نتایج تقسیم می کند. اگر برنامه تعاملی شما یک صفحه از نتایج را در یک زمان نمایش دهد، می تواند مناسب تر باشد.
یک query زبان Google Ads Query که نشان می‌دهد کدام منبع باید پرس و جو شود، ویژگی‌ها، بخش‌ها و معیارهای بازیابی، و شرایطی که باید برای محدود کردن اشیاء بازگردانده شوند استفاده کرد.
هر GoogleAdsRow نشان دهنده یک شی است که توسط یک پرس و جو برگردانده می شود و شامل مجموعه ای از ویژگی ها است که بر اساس فیلدهای درخواست شده در عبارت SELECT پر می شوند. ویژگی‌هایی که در بند SELECT گنجانده نشده‌اند، در اشیاء GoogleAdsRow در پاسخ پر نشده‌اند.
به عنوان مثال، اگرچه یک ad_group_criterion دارای یک ویژگی status است، فیلد status صفت ad_group_criterion ردیف در پاسخی برای درخواستی که در آن بند SELECT شامل ad_group_criterion.status نیست، پر نمی شود. به طور مشابه، اگر بند SELECT شامل هیچ فیلدی از منبع campaign نباشد، ویژگی campaign ردیف پر نمی شود.
هر GoogleAdsRow می‌تواند ویژگی‌ها و معیارهای متفاوتی از ردیف دیگر در همان مجموعه نتایج داشته باشد. بنابراین سطرها باید به‌عنوان اشیاء دیده شوند تا ردیف‌های ثابت جدول.
انواع enum ناشناخته
منابعی که با یک نوع UNKNOWN برگردانده می شوند در آن نسخه API به طور کامل پشتیبانی نمی شوند. این منابع را می‌توان از طریق رابط‌های دیگری مانند رابط کاربری Google Ads ایجاد کرد. هنگامی که یک منبع دارای یک نوع UNKNOWN است، می توانید معیارها را انتخاب کنید، اما نمی توانید منبع را از طریق API تغییر دهید. یک مثال از این یک کمپین یا تبلیغ جدید است که در UI معرفی شده است، اما در نسخه API مورد نظر شما پشتیبانی نمی شود.
در اینجا چند نکته وجود دارد که باید در نظر داشت:
منبعی با نوع UNKNOWN می تواند بعداً پشتیبانی شود یا برای مدت نامحدود UNKNOWN بماند.
اشیاء جدید با نوع UNKNOWN می توانند در هر زمانی ظاهر شوند. این اشیاء با عقب سازگار هستند زیرا مقدار enum از قبل در دسترس است. منابع با این تغییر با در دسترس بودن معرفی می شوند تا دید دقیقی از حساب خود داشته باشید. منبع UNKNOWN می تواند به دلیل فعالیت های جدید در حساب شما از طریق واسط های دیگر ظاهر شود، یا زمانی که منبعی دیگر پشتیبانی نمی شود.
منابع UNKNOWN می توانند معیارهای دقیقی را به آنها متصل کرده باشند که قابل پرس و جو هستند.
منابع UNKNOWN معمولاً به طور کامل در رابط کاربری Google Ads قابل مشاهده هستند.
منابع UNKNOWN عموماً قابل تغییر نیستند.
تقسیم بندی
پاسخ شامل یک GoogleAdsRow برای هر ترکیب از موارد زیر است:
نمونه ای از منبع اصلی مشخص شده در عبارت FROM
مقدار هر segment انتخاب شده
به عنوان مثال، پاسخ برای یک پرس و جو که FROM campaign انتخاب می کند و segments.ad_network_type و segments.date در عبارت SELECT دارد، برای هر ترکیبی از موارد زیر یک ردیف دارد:
campaign
segments.ad_network_type
segments.date
نتایج به طور ضمنی با هر نمونه از منبع اصلی تقسیم می شوند، نه بر اساس مقادیر فیلدهای جداگانه انتخاب شده. به عنوان مثال،
تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eGoogle Ads API's \u003ccode\u003eGoogleAdsService\u003c/code\u003e enables retrieval of object attributes, performance stats, and implements ordering, conditions, and limits for streamlined data access.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService\u003c/code\u003e offers two response methods: \u003ccode\u003eSearchStream\u003c/code\u003e for efficient handling of large datasets and \u003ccode\u003eSearch\u003c/code\u003e for manageable, paginated results.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService.Search\u003c/code\u003e requests require \u003ccode\u003ecustomer_id\u003c/code\u003e, Google Ads Query Language \u003ccode\u003equery\u003c/code\u003e, and optional pagination parameters (\u003ccode\u003epage_size\u003c/code\u003e, \u003ccode\u003epage_token\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003eResponses comprise \u003ccode\u003eGoogleAdsRow\u003c/code\u003e objects, reflecting queried object attributes and metrics as specified in the \u003ccode\u003eSELECT\u003c/code\u003e clause.\u003c/p\u003e\n"],["\u003cp\u003eResources returned with an \u003ccode\u003eUNKNOWN\u003c/code\u003e type are not fully supported in that API version, might have been created through other interfaces, and are generally not mutable.\u003c/p\u003e\n"]]],[],null,["# Retrieving objects\n\n| **Objective:** Understand how to retrieve objects and performance stats using [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService). For reporting concepts, see the [reporting guides](/google-ads/api/docs/reporting/overview).\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) is the unified object\nretrieval and reporting service of the Google Ads API. The service has methods that:\n\n- Retrieve specific attributes of objects.\n- Retrieve performance metrics for objects based on a date range.\n- Order objects based on their attributes.\n- Use conditions to indicate which objects you want returned in the response.\n- Limit the number of objects returned.\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) can return results in\ntwo ways:\n\n- [`GoogleAdsService.SearchStream`](/google-ads/api/reference/rpc/v21/GoogleAdsService/SearchStream) returns all rows in a single streaming response which is more efficient for large (greater than 10,000 rows) result sets. This might be more appropriate if your batch application wants to download as much data as fast as possible.\n- [`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) breaks up large responses into manageable pages of results. This could be more appropriate if your interactive application displays a page of results at a time.\n\nLearn more about [paging versus streaming](/google-ads/api/docs/reporting/streaming).\n\nMake a request\n--------------\n\nThe search method requires a\n[`SearchGoogleAdsRequest`](/google-ads/api/reference/rpc/v21/SearchGoogleAdsRequest), which consists\nof the following attributes:\n\n- A `customer_id`\n- A Google Ads Query Language `query` that indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned\n- ([`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) only) An optional `page_token` to retrieve the next batch of results when using [paging](/google-ads/api/docs/reporting/paging).\n\nFor more information on the Google Ads Query Language, check out the [Google Ads Query Language\nguide](/google-ads/api/docs/query/overview).\n\nProcess a response\n------------------\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) returns a list of\n[`GoogleAdsRow`](/google-ads/api/reference/rpc/v21/GoogleAdsRow) objects.\n\nEach `GoogleAdsRow` represents an object returned by a query, and consists of a\nset of attributes that are populated based on the fields requested in the\n`SELECT` clause. Attributes not included in the `SELECT` clause are not\npopulated on the `GoogleAdsRow` objects in the response.\n\nFor example, although an `ad_group_criterion` has a `status` attribute, the\n`status` field of the row's `ad_group_criterion` attribute is not populated in a\nresponse for a query where the `SELECT` clause does not include\n`ad_group_criterion.status`. Similarly, the `campaign` attribute of the row is\nnot populated if the `SELECT` clause does not include any fields from the\n`campaign` resource.\n\nEach `GoogleAdsRow` can have different attributes and metrics from another row\nin the same result set; so the rows should be viewed as objects rather than\nfixed rows of a table.\n\nUNKNOWN enum types\n------------------\n\nResources that are returned with a type of `UNKNOWN` are not fully supported in\nthat API version. These resources could have been created through other\ninterfaces such as the Google Ads UI. You can select metrics when a resource has a\ntype of `UNKNOWN`, but you cannot mutate the resource through the API. An\nexample of this would be a new campaign or ad being introduced in the UI, but\nnot supported in the API version you are querying.\n\nHere are some considerations to keep in mind:\n\n- A resource with an `UNKNOWN` type can be supported later or stay `UNKNOWN` indefinitely.\n- New objects with type `UNKNOWN` can appear at any time. These objects are backward compatible because the enum value is already available. Resources are introduced with this change as they're available so that you have an accurate view of your account. The `UNKNOWN` resource can appear due to new activities in your account through other interfaces, or when a resource is no longer supported.\n- `UNKNOWN` resources can have detailed metrics attached to them that are queryable.\n- `UNKNOWN` resources are typically fully visible in the Google Ads UI.\n- `UNKNOWN` resources generally cannot be mutated.\n\nSegmentation\n------------\n\nThe response would contain one `GoogleAdsRow` for each combination of the\nfollowing:\n\n- Instance of the main resource specified in the `FROM` clause\n- Value of each selected `segment` field\n\nFor example, the response for a query that selects `FROM campaign` and has\n`segments.ad_network_type` and `segments.date` in the `SELECT` clause would\ncontain one row for each combination of the following:\n\n- `campaign`\n- `segments.ad_network_type`\n- `segments.date`\n\nResults are implicitly segmented by each instance of the main resource, not by\nthe values of the individual fields selected. For example, \n\n SELECT campaign.status, metrics.impressions\n FROM campaign\n WHERE segments.date DURING LAST_14_DAYS\n\nresults in one row per **campaign** , not one row per distinct value of the\n`campaign.status` field."]]
