تعرض GoogleAdsService.SearchStream
جميع الصفوف في ردّ واحد متدفّق، ما يجعله أكثر فعالية
لمجموعات النتائج الكبيرة (التي تتضمّن أكثر من 10,000 صف). قد يكون هذا الخيار أكثر ملاءمةً إذا كان تطبيقك المجمّع يريد تنزيل أكبر قدر ممكن من البيانات بأسرع ما يمكن.
تعمل GoogleAdsService.Search على تقسيم الردود الكبيرة إلى صفحات نتائج يسهل التعامل معها. قد يكون هذا الخيار أكثر ملاءمةً إذا كان تطبيقك التفاعلي يعرض صفحة من النتائج في كل مرة.
query تشير إلى المورد الذي سيتم طلب البحث عنه، والسمات والشرائح والمقاييس التي سيتم استردادها، والشروط التي سيتم استخدامها لتقييد العناصر التي سيتم عرضها
يمثّل كل GoogleAdsRow عنصرًا تعرضه نتيجة طلب البحث، ويتألف من مجموعة من السمات التي يتم ملؤها استنادًا إلى الحقول المطلوبة في عبارة SELECT. لا تتم تعبئة السمات غير المضمّنة في عبارة SELECT في عناصر GoogleAdsRow في الرد.
على سبيل المثال، على الرغم من أنّ ad_group_criterion يتضمّن السمة status، لا تتم تعبئة الحقل status الخاص بالسمة ad_group_criterion في الصف ضمن الرد على طلب بحث لا تتضمّن عبارة SELECT فيه ad_group_criterion.status. وبالمثل، لا تتم تعبئة السمة campaign الخاصة بالصف إذا لم تتضمّن العبارة SELECT أي حقول من المورد campaign.
يمكن أن يتضمّن كل GoogleAdsRow سمات ومقاييس مختلفة عن صف آخر في مجموعة النتائج نفسها، لذا يجب عرض الصفوف كعناصر وليس كصفوف ثابتة في جدول.
أنواع التعداد UNKNOWN
الموارد التي يتم عرضها بنوع UNKNOWN غير متاحة بالكامل في إصدار واجهة برمجة التطبيقات هذا. ويمكن أن تكون هذه المراجع قد تم إنشاؤها من خلال واجهات أخرى، مثل واجهة مستخدم "إعلانات Google". يمكنك اختيار المقاييس عندما يكون للمرجع نوع UNKNOWN، ولكن لا يمكنك تعديل المرجع من خلال واجهة برمجة التطبيقات. على سبيل المثال، قد يتم طرح حملة أو إعلان جديدَين في واجهة المستخدم، ولكن لا يكونان متاحَين في إصدار واجهة برمجة التطبيقات الذي تستخدمه في طلب البحث.
في ما يلي بعض الاعتبارات التي يجب وضعها في الاعتبار:
يمكن إتاحة مورد من النوع UNKNOWN لاحقًا أو يبقى UNKNOWN إلى أجل غير مسمّى.
يمكن أن تظهر عناصر جديدة من النوع UNKNOWN في أي وقت. هذه العناصر متوافقة مع الإصدارات القديمة لأنّ قيمة التعداد متوفّرة مسبقًا. نقدّم لك المراجع مع هذا التغيير عندما تصبح متاحة لكي تتمكّن من الاطّلاع على معلومات دقيقة عن حسابك. قد يظهر المرجع UNKNOWN بسبب أنشطة جديدة في حسابك من خلال واجهات أخرى، أو عندما يصبح المرجع غير متوافق.
يمكن أن تتضمّن موارد UNKNOWN مقاييس تفصيلية يمكن الاستعلام عنها.
تكون مراجع UNKNOWN مرئية بالكامل عادةً في واجهة مستخدم "إعلانات Google".
لا يمكن تعديل موارد UNKNOWN بشكل عام.
التقسيم
سيتضمّن الردّ GoogleAdsRow واحدًا لكل مجموعة من العناصر التالية:
مثيل للمورد الرئيسي المحدّد في عبارة FROM
قيمة كل حقل segment محدّد
على سبيل المثال، سيتضمّن الردّ على طلب بحث يختار FROM campaign ويتضمّن segments.ad_network_type وsegments.date في عبارة SELECT صفًا واحدًا لكل مجموعة من ما يلي:
campaign
segments.ad_network_type
segments.date
يتم تقسيم النتائج ضمنيًا حسب كل مثيل للمورد الرئيسي، وليس حسب قيم الحقول الفردية المحدّدة. على سبيل المثال:
تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-05 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
