أصبحت Search Ads 360 Reporting API الجديدة متاحة الآن. يمكنك الانضمام إلى مجموعة Google
searchads-api-announcements لتبقى على اطّلاع على التحسينات والإصدارات القادمة.
بنية واجهة برمجة التطبيقات لإعداد التقارير في "إعلانات شبكة البحث 360"
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المكونات الأساسية لواجهة Search Ads 360 Reporting API هي الموارد و
الخدمات. يمثِّل المورد كيان "إعلانات شبكة البحث 360" وأنت تستخدم خدمة
لاسترداد كيانات "إعلانات شبكة البحث 360".
التدرّج الهرمي للكائنات
حساب "إعلانات شبكة البحث 360" هو تدرّج هرمي من العناصر.
المرجع من المستوى الأعلى للحساب هو العميل.
يحتوي كل حساب على حملة نشطة واحدة أو أكثر.
يحتوي كل Campaign على مجموعة إعلانية واحدة أو أكثر تُجمِّع إعلاناتك في
مجموعات منطقية.
يحتوي كل AdGroup على إعلان مجموعة إعلانية واحد أو أكثر.
يمكنك إرفاق عنصر AdGroupCriterion أو CampaignCriterion
واحد أو أكثر بمجموعة إعلانية أو حملة. تحدّد المعايير كيفية عرض الإعلانات.
- هناك العديد من أنواع المعايير، مثل الكلمات الرئيسية وشرائح العمر والمواقع الجغرافية. تؤثر المعايير المحدّدة على مستوى الحملة في جميع الموارد الأخرى ضمن الحملة. يمكنك أيضًا تحديد ميزانيات وتواريخ على مستوى الحملة.
الموارد
تمثّل الموارد الكيانات في حسابك على "إعلانات شبكة البحث 360". تشمل أمثلة موارد
Customer وCampaign وAdGroup.
أرقام تعريف العناصر
يتم تحديد كل عنصر في "إعلانات شبكة البحث 360" من خلال رقم تعريفه الخاص. تكون بعض المعرّفات
فريدة على مستوى العالم، أي على مستوى جميع حسابات "إعلانات شبكة البحث 360"، في حين تكون بعضها الآخر
فريدة ضمن نطاق محدود فقط.
| نطاق تفرد رقم تعريف العنصر |
| معرِّف الميزانية |
عالمي |
| رقم تعريف الحملة |
عالمي |
| معرف المجموعة الإعلانية |
عالمي |
| الرقم التعريفي للإعلان |
المجموعة الإعلانيةكل زوج AdGroupId / AdId فريد على مستوى العالم. |
| رقم تعريف معيار المجموعة الإعلانية |
المجموعة الإعلانيةيكون كل زوج من AdGroupId / CriterionId فريدًا على مستوى العالم. |
| رقم تعريف معيار الحملة |
الحملةكل زوج CampaignId / CriterionId فريد على مستوى العالم. |
| معلومات الإعلان الإضافية |
الحملةكل زوج CampaignId / AdExtensionId فريد على مستوى العالم. |
| الرقم التعريفي للخلاصة |
عالمي |
| الرقم التعريفي لعنصر الخلاصة |
عالمي |
| رقم تعريف سمة الخلاصة |
الخلاصة |
| الرقم التعريفي لتخطيط الخلاصة |
عالمي |
| الرقم التعريفي للتصنيف |
عالمي |
| رقم تعريف قائمة المستخدمين |
عالمي |
يمكن أن تكون قواعد الأرقام التعريفية هذه مفيدة عند تصميم مساحة تخزين محلية لعناصر "إعلانات شبكة البحث
360".
أنواع الكائنات
يمكن استخدام بعض الكائنات لأنواع متعددة من الكيانات. في هذه الحالة، يحتوي
العنصر على حقل type يصف محتوياته. على سبيل المثال، يمكن أن يشير الرمز
AdGroupAd إلى إعلان نصي أو إعلان فندق أو إعلان محلي.
يمكنك الوصول إلى قيمة النوع من خلال حقل AdGroupAd.ad.type. ويتم عرض قيمتها في تعداد AdType.
أسماء الموارد
يتم تحديد كل مورد بشكل فريد من خلال سلسلة resource_name التي
تربط المورد وعناصره الرئيسية في مسار.
على سبيل المثال، تكون أسماء موارد الحملات على النحو التالي:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
حملة تحمل رقم التعريف 987654 في حساب "إعلانات شبكة البحث 360" الذي يحمل رقم تعريف العميل
1234567، تتضمّن resource_name:
customers/1234567/campaigns/987654
الخدمات
تتيح لك الخدمات استرداد عناصر "إعلانات شبكة البحث 360" والبيانات الوصفية. هناك ثلاثة أنواع من الخدمات وهي:
- البحث في الخدمة
SearchAds360Service هي خدمة واحدة وموحّدة لاسترداد جميع
كائنات الموارد وإحصاءات الأداء. وتوفّر طريقتَين: Search
وSearchStream. تتطلّب كلتا الطريقتَين طلب بحث يحدّد
المورد المطلوب البحث عنه، وسمات المورد ومقاييس الأداء المطلوب استرجاعها،
والعبارات الشرطية التي سيتم استخدامها لفلترة الطلب، والشرائح التي سيتم استخدامها لمزيد من تقسيم إحصاءات الأداء. راجِع إنشاء تقارير البحث ولغة طلبات البحث في "إعلانات شبكة البحث 360" للحصول على مزيد من المعلومات.- الخدمة الميدانية
- يسترد
SearchAds360FieldService البيانات الوصفية
حول الموارد، مثل السمات المتاحة لأحد الموارد ونوع بياناته. يمكنك طلب قائمة الموارد وحقول الموارد ومفاتيح
التصنيف إلى شرائح والمقاييس المتوفرة في طرق البحث باللغة SearchAds360Service. اطّلِع على مقالة استرداد البيانات الوصفية للموارد لمزيد من المعلومات.
- الخدمات الخاصة بالكيانات
توفّر هذه الخدمات طريقة طلب GET تتيح استرداد نسخة مورد واحدة. ويُعدّ ذلك مفيدًا لفحص بنية أحد الموارد.
تشمل الأمثلة على الخدمات الخاصة بالكيانات ما يلي:
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Search Ads 360 Reporting API uses resources to represent Search Ads 360 entities and services to retrieve them, with the core being the SearchAds360Service for comprehensive data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eSearch Ads 360 accounts are structured hierarchically, starting with the customer resource at the top, followed by campaigns, ad groups, ads, and criteria for targeting.\u003c/p\u003e\n"],["\u003cp\u003eEvery Search Ads 360 object has a unique ID, some globally and others within a specific scope like an ad group or campaign, which is important for data management.\u003c/p\u003e\n"],["\u003cp\u003eResources are identified by resource names, which are strings that combine the resource and its parent resources in a path format, such as customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID.\u003c/p\u003e\n"],["\u003cp\u003eThe Search Ads 360 Reporting API provides services like SearchAds360Service for data retrieval, SearchAds360FieldService for resource metadata, and entity-specific services for detailed information on individual resources like custom columns.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API uses resources (entities) and services (retrieval methods). Resources, like `Customer`, `Campaign`, and `AdGroup`, are organized hierarchically. Each object has a unique ID with varying scopes and a `resource_name` for identification. Services include `SearchAds360Service` to retrieve resources and statistics, `SearchAds360FieldService` for metadata, and entity-specific services for individual resource instances. `SearchAds360Service` uses queries with attributes, metrics, predicates, and segments to filter data.\n"],null,["# Search Ads 360 Reporting API structure\n\nThe primary components of the Search Ads 360 Reporting API are *resources* and\n*services*. A resource represents a Search Ads 360 entity and you use a service\nto retrieve Search Ads 360 entities.\n\nObject hierarchy\n----------------\n\nA Search Ads 360 account is a hierarchy of objects.\n\n- The top-level resource of an account is the [customer](/search-ads/reporting/api/reference/fields/v0/customer).\n\n- Each account contains one or more active [campaigns](/search-ads/reporting/api/reference/fields/v0/campaign).\n\n- Each `Campaign` contains one or more [ad groups](/search-ads/reporting/api/reference/fields/v0/ad_group) that group your ads into\n logical collections.\n\n- Each `AdGroup` contains one or more [ad group ads](/search-ads/reporting/api/reference/rpc/ad_group_ad).\n\n- You can attach one or more [`AdGroupCriterion`](/search-ads/reporting/api/reference/fields/v0/ad_group_criterion) or [`CampaignCriterion`](/search-ads/reporting/api/reference/fields/v0/campaign_criterion)\n to an ad group or campaign. Criteria define how ads are triggered.\n\n - There are many [criterion types](), such as, keywords, age ranges, and locations. Criteria defined at the campaign level affect all other resources within the campaign. You can also specify campaign-wide budgets and dates.\n\nResources\n---------\n\nResources represent the entities in your Search Ads 360 account. Example\nresources include [`Customer`](/search-ads/reporting/api/reference/fields/v0/customer), [`Campaign`](/search-ads/reporting/api/reference/fields/v0/campaign) and [`AdGroup`](/search-ads/reporting/api/reference/fields/v0/ad_group).\n\n### Object IDs\n\nEvery object in Search Ads 360 is identified by its own ID. Some IDs are\nglobally unique, that is, across all Search Ads 360 accounts, while others\nare unique only within a confined scope.\n\n| Object ID uniqueness scope ||\n|----------------------|------------------------------------------------------------------------------|\n| Budget ID | Global |\n| Campaign ID | Global |\n| AdGroup ID | Global |\n| Ad ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `AdId` pair is globally unique. |\n| AdGroupCriterion ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `CriterionId` pair is globally unique. |\n| CampaignCriterion ID | Campaign \u003cbr /\u003e Each `CampaignId` / `CriterionId` pair is globally unique. |\n| Ad Extensions | Campaign \u003cbr /\u003e Each `CampaignId` / `AdExtensionId` pair is globally unique. |\n| Feed ID | Global |\n| Feed Item ID | Global |\n| Feed Attribute ID | Feed |\n| Feed Mapping ID | Global |\n| Label ID | Global |\n| UserList ID | Global |\n\nThese ID rules can be useful when designing local storage for your Search Ads\n360 objects.\n\n### Object types\n\nSome objects can be used for multiple entity types. If this is the case, the\nobject contains a `type` field that describes its contents. For example,\n[`AdGroupAd`](/search-ads/reporting/api/reference/rpc/ad_group_ad) can refer to a text ad, hotel ad, or local ad.\nYou can access the type value through the [`AdGroupAd.ad.type`](/search-ads/reporting/api/reference/rpc/add_group_ad) field. Its\nvalue is returned in the [`AdType`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.enums#adtypeenum) enum.\n\n### Resource names\n\nEach resource is uniquely identified by a `resource_name` string that\nconcatenates the resource and its parents into a path.\n\nCampaign resource names, for example, have the form: \n\n```scdoc\ncustomers/CUSTOMER_ID/campaigns/CAMPAIGN_ID\n```\n\nA campaign with ID `987654` in the Search Ads 360 account with customer ID\n`1234567`, has the `resource_name`: \n\n```text\ncustomers/1234567/campaigns/987654\n```\n\nServices\n--------\n\nServices let you retrieve your Search Ads 360 entities and metadata. There a\nthree service types:\n\nSearch service\n: [`SearchAds360Service`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360service) is the single, unified service for retrieving all\n resource objects and performance statistics. It provides two methods: *`Search`*\n and *`SearchStream`* . Both methods require require a query that specifies the\n resource to query, the resource attributes and performance metrics to retrieve,\n the predicates to use for filtering the request, and the segments to use to\n further break down performance statistics. See [Create search reports](/search-ads/reporting/concepts/search-reports) and [Search\n Ads 360 Query Language](/search-ads/reporting/concepts/query-language) for more\n information.\n\nField service\n: [`SearchAds360FieldService`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360fieldservice) retrieves metadata\n about resources, such as, the available attributes for a resource and its data\n type. You can request the catalog for resources, resource fields, segmentation\n keys, and metrics available in the `SearchAds360Service` search methods. See\n [Retrieve resource metadata](/search-ads/reporting/concepts/field-service)\n to learn more.\n\nEntity-specific services\n\n: These services provide a `GET` request method that retrieves a single resource\n instance. This is useful for examining the structure of a resource.\n\n Examples of entity-specific services include:\n\n - [CustomColumnService](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#customcolumnservice) that returns the requested custom column in full detail."]]
