Search Ads 360 Reporting API 結構
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
Search Ads 360 Reporting API 的主要元件為資源和服務。資源代表 Search Ads 360 實體，您可以使用服務擷取 Search Ads 360 實體。
物件階層
Search Ads 360 帳戶是物件的階層。
資源
資源代表 Search Ads 360 帳戶中的實體。資源範例包括 Customer、Campaign 和 AdGroup。
物件 ID
Search Ads 360 中的每個物件都有專屬 ID，有些 ID 在全球範圍內皆為唯一，也就是在所有 Search Ads 360 帳戶中皆為唯一；其他 ID 則僅在特定範圍內為唯一。
| 物件 ID 唯一性範圍 |
| 預算 ID |
全球 |
| 廣告活動 ID |
全球 |
| 廣告群組 ID |
全球 |
| 廣告 ID |
廣告群組每個 AdGroupId / AdId 組合在全球皆為唯一值。 |
| AdGroupCriterion 編號 |
廣告群組每個 AdGroupId / CriterionId 組合在全域範圍內都不重複。 |
| CampaignCriterion 編號 |
廣告活動每個 CampaignId / CriterionId 組合在全域範圍內都不重複。 |
| 廣告額外資訊 |
廣告活動每個 CampaignId / AdExtensionId 組合在全球皆為唯一值。 |
| 動態饋給ID |
全球 |
| 資訊提供項目編號 |
全球 |
| 資訊提供屬性編號 |
動態消息 |
| 資訊提供對應編號 |
全球 |
| 標籤 ID |
全球 |
| 使用者名單 ID |
全球 |
為 Search Ads 360 物件設計本機儲存空間時，這些 ID 規則非常實用。
物件類型
某些物件可用於多種實體類型。在這種情況下，物件會包含 type 欄位，用於說明其內容。舉例來說，AdGroupAd 可以代表文字廣告、飯店廣告或本地廣告。您可以透過 AdGroupAd.ad.type 欄位存取類型值。其值會傳回至 AdType 列舉。
資源名稱
每個資源都會以 resource_name 字串做為唯一識別，該字串會將資源及其父項串連成一個路徑。
廣告活動資源名稱範例如下：
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
在客戶 ID 為 1234567 的 Search Ads 360 帳戶中，廣告活動 ID 為 987654 的廣告活動具有 resource_name：
customers/1234567/campaigns/987654
服務
您可以使用服務擷取 Search Ads 360 實體和中繼資料。服務類型分為三種：
- 搜尋服務
SearchAds360Service 是單一整合服務，可擷取所有資源物件和成效統計資料。提供兩種方法：Search 和 SearchStream。這兩種方法都需要查詢，以指定要查詢的資源、要擷取的資源屬性和成效指標、用於篩選要求的預設條件，以及用於進一步細分成效統計資料的區隔。詳情請參閱「建立搜尋報表」和「Search Ads 360 查詢語言」。- 現場服務
SearchAds360FieldService 會擷取資源的中繼資料，例如資源的可用屬性及其資料類型。您可以要求目錄，取得 SearchAds360Service 搜尋方法中提供的資源、資源欄位、區隔鍵和指標。詳情請參閱擷取資源中繼資料一文。- 實體專屬服務
這些服務提供 GET 要求方法，可擷取單一資源例項。這有助於檢查資源的結構。
實體專屬服務的範例包括：
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 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."]]
