API جدید Search Ads 360 Reporting اکنون در دسترس است. به گروه Google
searchads-api-announcements بپیوندید تا در مورد پیشرفت‌ها و نسخه‌های آینده به‌روز باشید.
ساختار API گزارش Search Ads 360
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
اجزای اصلی Search Ads 360 Reporting API منابع و خدمات هستند. یک منبع یک موجودیت Search Ads 360 را نشان می دهد و شما از یک سرویس برای بازیابی موجودیت های Search Ads 360 استفاده می کنید.
سلسله مراتب شی
حساب Search Ads 360 سلسله مراتبی از اشیاء است.
منبع سطح بالای یک حساب، مشتری است.
هر حساب شامل یک یا چند کمپین فعال است.
هر Campaign شامل یک یا چند گروه تبلیغاتی است که تبلیغات شما را در مجموعه های منطقی گروه بندی می کنند.
هر AdGroup حاوی یک یا چند آگهی گروه تبلیغاتی است.
می توانید یک یا چند AdGroupCriterion یا CampaignCriterion به یک گروه تبلیغاتی یا کمپین پیوست کنید. معیارها نحوه راه اندازی تبلیغات را مشخص می کنند.
- انواع معیارهای زیادی وجود دارد، مانند کلمات کلیدی، محدوده سنی و مکان. معیارهای تعریف شده در سطح کمپین بر تمام منابع دیگر درون کمپین تأثیر می گذارد. شما همچنین می توانید بودجه و تاریخ کمپین را مشخص کنید.
منابع
منابع موجودیت‌های موجود در حساب Search Ads 360 شما را نشان می‌دهند. منابع مثال شامل Customer ، Campaign و AdGroup است.
شناسه های اشیاء
هر شی در Search Ads 360 با شناسه خود شناسایی می شود. برخی از شناسه‌ها در سراسر جهان منحصر به فرد هستند، یعنی در همه حساب‌های Search Ads 360، در حالی که برخی دیگر فقط در یک محدوده محدود منحصر به فرد هستند.
| محدوده منحصر به فرد شناسه شی |
|---|
| شناسه بودجه | جهانی |
| شناسه کمپین | جهانی |
| شناسه AdGroup | جهانی |
| شناسه آگهی | گروه تبلیغات هر جفت AdGroupId / AdId در سطح جهانی منحصر به فرد است. |
| AdGroupCriterion ID | گروه تبلیغات هر جفت AdGroupId / CriterionId در سطح جهانی منحصر به فرد است. |
| CampaignCriterion ID | کمپین هر جفت CampaignId / CriterionId در سطح جهانی منحصر به فرد است. |
| پسوندهای تبلیغاتی | کمپین هر جفت CampaignId / AdExtensionId در سطح جهانی منحصر به فرد است. |
| شناسه فید | جهانی |
| شناسه مورد فید | جهانی |
| شناسه ویژگی فید | خوراک |
| شناسه نقشه‌برداری فید | جهانی |
| شناسه برچسب | جهانی |
| شناسه لیست کاربری | جهانی |
این قوانین شناسه می تواند هنگام طراحی فضای ذخیره سازی محلی برای اشیاء Search Ads 360 مفید باشد.
انواع شی
برخی از اشیاء را می توان برای چندین نوع موجودیت استفاده کرد. اگر اینطور باشد، شی حاوی یک فیلد type است که محتویات آن را توصیف می کند. به عنوان مثال، AdGroupAd می تواند به یک آگهی متنی، آگهی هتل یا آگهی محلی اشاره کند. می توانید از طریق فیلد AdGroupAd.ad.type به مقدار نوع دسترسی داشته باشید. مقدار آن در فهرست AdType برگردانده می شود.
نام منابع
هر منبع به طور منحصر به فرد توسط یک رشته resource_name شناسایی می شود که منبع و والدین آن را در یک مسیر به هم متصل می کند.
به عنوان مثال، نام منابع کمپین به شکل زیر است:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
کمپینی با شناسه 987654 در اکانت Search Ads 360 با شناسه مشتری 1234567 دارای resource_name است:
customers/1234567/campaigns/987654
خدمات
خدمات به شما امکان می دهند موجودیت ها و ابرداده های Search Ads 360 خود را بازیابی کنید. سه نوع خدمات وجود دارد:
- سرویس جستجو
-
SearchAds360Service یک سرویس واحد و یکپارچه برای بازیابی همه اشیاء منابع و آمار عملکرد است. این دو روش را ارائه می دهد: Search و SearchStream . هر دو روش به یک پرس و جو نیاز دارند که منبع مورد نظر، ویژگی‌های منبع و معیارهای عملکرد برای بازیابی، مقدماتی برای فیلتر کردن درخواست و بخش‌هایی را که برای تجزیه بیشتر آمار عملکرد استفاده می‌شود، مشخص کند. برای اطلاعات بیشتر به ایجاد گزارش‌های جستجو و Search Ads 360 Query Language مراجعه کنید. - خدمات میدانی
-
SearchAds360FieldService ابرداده‌های مربوط به منابع، مانند ویژگی‌های موجود برای یک منبع و نوع داده آن را بازیابی می‌کند. می‌توانید کاتالوگ را برای منابع، فیلدهای منبع، کلیدهای تقسیم‌بندی، و معیارهای موجود در روش‌های جستجوی SearchAds360Service درخواست کنید. برای کسب اطلاعات بیشتر به بازیابی ابرداده منبع مراجعه کنید. - خدمات خاص نهاد
این سرویس ها یک روش درخواست GET را ارائه می کنند که یک نمونه منبع واحد را بازیابی می کند. این برای بررسی ساختار یک منبع مفید است.
نمونه‌هایی از خدمات خاص نهاد عبارتند از:
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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."]]
