Dostępny jest już nowy interfejs Search Ads 360 Reporting API. Dołącz do grupy dyskusyjnej Google
searchads-api-announcements, aby na bieżąco otrzymywać informacje o nadchodzących ulepszeniach i wersjach.
Struktura interfejsu API do raportowania Search Ads 360
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Główne komponenty interfejsu Search Ads 360 Reporting API to zasoby i usługi. Zasoby reprezentują elementy Search Ads 360, a usługa służy do ich pobierania.
Hierarchia obiektów
Konto Search Ads 360 to hierarchia obiektów.
Zasób najwyższego poziomu na koncie to klient.
Każde konto zawiera co najmniej 1 aktywną kampanię.
Każda Campaign zawiera co najmniej 1 grupę reklam, która grupowanie reklam w logiczne kolekcje.
Każda AdGroup zawiera co najmniej 1 reklamę grupy reklam.
Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 element AdGroupCriterion lub CampaignCriterion. Kryteria określają sposób uruchamiania reklam.
- Istnieje wiele typów kryteriów, np. słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii wpływają na wszystkie inne zasoby w ramach kampanii. Możesz też określić budżety i daty obowiązujące w całości kampanii.
Zasoby
Zasoby reprezentują elementy na koncie Search Ads 360. Przykładowe zasoby to Customer, Campaign i AdGroup.
Identyfikatory obiektów
Każdy obiekt w Search Ads 360 jest identyfikowany na podstawie własnego identyfikatora. Niektóre identyfikatory są unikalne globalnie, czyli obejmują wszystkie konta Search Ads 360, a inne są unikalne tylko w ograniczonym zakresie.
| Zakres unikalności identyfikatora obiektu |
| Identyfikator budżetu |
Cały świat |
| Identyfikator kampanii |
Cały świat |
| Identyfikator grupy reklam |
Cały świat |
| Identyfikator reklamy |
Grupa reklamKażda para AdGroupId / AdId jest niepowtarzalna globalnie. |
| Identyfikator kryterium grupy reklam |
Grupa reklamKażda para AdGroupId / CriterionId jest niepowtarzalna globalnie. |
| CampaignCriterion ID |
KampaniaKażda para CampaignId / CriterionId jest globalnie unikalna. |
| Rozszerzenia reklam |
KampaniaKażda para CampaignId / AdExtensionId jest niepowtarzalna globalnie. |
| Identyfikator kanału RSS |
Cały świat |
| Identyfikator elementu kanału |
Cały świat |
| Identyfikator atrybutu w pliku danych |
Kanał |
| Identyfikator mapowania kanału |
Cały świat |
| Identyfikator etykiety |
Cały świat |
| Identyfikator listy użytkowników |
Cały świat |
Te reguły identyfikatorów mogą być przydatne podczas projektowania lokalnego miejsca na dane dla obiektów Search Ads 360.
Typy obiektów
Niektóre obiekty mogą służyć do różnych typów obiektów. W takim przypadku obiekt zawiera pole type, które opisuje jego zawartość. Na przykład:
AdGroupAd może oznaczać reklamę tekstową, reklamę hoteli lub reklamę lokalną.
Wartość typu możesz sprawdzić w polu AdGroupAd.ad.type. Jego wartość jest zwracana w wyliczeniu AdType.
Nazwy zasobów
Każdy zasób jest jednoznacznie identyfikowany przez ciąg znaków resource_name, który łączy zasób i jego elementy nadrzędne w ścieżkę.
Nazwy zasobów kampanii mają np. postać:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Kampania o identyfikatorze 987654 na koncie Search Ads 360 o identyfikatorze klienta 1234567 ma resource_name:
customers/1234567/campaigns/987654
Usługi
Usługi umożliwiają pobieranie elementów i metadanych Search Ads 360. Dostępne są 3 typy usług:
- Usługa wyszukiwania
SearchAds360Service to jedna, zintegrowana usługa służąca do pobierania wszystkich obiektów zasobów i statystyk skuteczności. Umożliwia to 2 metody: Search i SearchStream. Obie metody wymagają zapytania, które określa zasób, do którego ma być kierowane zapytanie, atrybuty zasobu i dane o skuteczności do pobrania, predykaty do użycia do filtrowania żądania oraz segmenty do użycia do dalszego podziału statystyk skuteczności. Więcej informacji znajdziesz w artykułach Tworzenie raportów wyszukiwania i Język zapytań Search Ads 360.- Usługa w terenie
SearchAds360FieldService zwraca metadane zasobów, takie jak dostępne atrybuty zasobu i jego typ danych. Możesz poprosić o katalog zasobów, pól zasobów, kluczy segmentacji i danych dostępnych w metodach wyszukiwania SearchAds360Service. Aby dowiedzieć się więcej, zapoznaj się z artykułem Pobieranie metadanych zasobów.- Usługi dotyczące poszczególnych elementów
Te usługi udostępniają metodę żądania GET, która umożliwia pobranie pojedynczego wystąpienia zasobu. Jest to przydatne do sprawdzania struktury zasobu.
Przykłady usług związanych z konkretnymi podmiotami:
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-08-29 UTC.
[null,null,["Ostatnia aktualizacja: 2025-08-29 UTC."],[[["\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."]]
