Die neue Search Ads 360 Reporting API ist jetzt verfügbar. Treten Sie der Google-Gruppe
searchads-api-announcements bei, um über kommende Verbesserungen und Releases auf dem Laufenden zu bleiben.
Struktur der Search Ads 360 Reporting API
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Die Hauptkomponenten der Search Ads 360 Reporting API sind Ressourcen und Dienste. Eine Ressource stellt eine Search Ads 360-Entität dar und Sie verwenden einen Dienst, um Search Ads 360-Entitäten abzurufen.
Objekthierarchie
Ein Search Ads 360-Konto ist eine Hierarchie von Objekten.
Die oberste Ressource eines Kontos ist der Kunde.
Jedes Konto enthält eine oder mehrere aktive Kampagnen.
Jede Campaign enthält eine oder mehrere Anzeigengruppen, in denen Ihre Anzeigen in logische Sammlungen gruppiert werden.
Jede AdGroup enthält eine oder mehrere Anzeigen in Anzeigengruppen.
Sie können einer Anzeigengruppe oder Kampagne eine oder mehrere AdGroupCriterion oder CampaignCriterion hinzufügen. Mit Kriterien wird festgelegt, wie Anzeigen ausgelöst werden.
- Es gibt viele Kriterienstypen, z. B. Keywords, Altersgruppen und Standorte. Auf Kampagnenebene definierte Kriterien wirken sich auf alle anderen Ressourcen innerhalb der Kampagne aus. Außerdem können Sie für die gesamte Kampagne geltende Budgets und Termine angeben.
Ressourcen
Ressourcen repräsentieren die Entitäten in Ihrem Search Ads 360-Konto. Beispiele für Ressourcen sind Customer, Campaign und AdGroup.
Objekt-IDs
Jedes Objekt in Search Ads 360 wird durch eine eigene ID identifiziert. Einige IDs sind global eindeutig, d. h. für alle Search Ads 360-Konten, während andere nur in einem begrenzten Umfang eindeutig sind.
| Gültigkeitsbereich der Eindeutigkeit der Objekt-ID |
| Budget-ID |
Global |
| Kampagnen-ID |
Global |
| Anzeigengruppen-ID |
Global |
| Anzeigen-ID |
AnzeigengruppeJedes AdGroupId / AdId-Paar ist weltweit eindeutig. |
| ID des Anzeigengruppenkriteriums |
AnzeigengruppeJedes AdGroupId / CriterionId-Paar ist global eindeutig. |
| ID des Kampagnenkriteriums |
KampagneJedes CampaignId / CriterionId-Paar ist global eindeutig. |
| Anzeigenerweiterungen |
KampagneJedes CampaignId / AdExtensionId-Paar ist global eindeutig. |
| Feed-ID |
Global |
| ID des Feedelements |
Global |
| Feed-Attribut-ID |
Feed |
| Feed-Mapping-ID |
Global |
| Label-ID |
Global |
| UserList-ID |
Global |
Diese ID-Regeln können beim Entwerfen des lokalen Speichers für Ihre Search Ads 360-Objekte hilfreich sein.
Objekttypen
Einige Objekte können für mehrere Entitätstypen verwendet werden. In diesem Fall enthält das Objekt ein type-Feld, das den Inhalt beschreibt.
AdGroupAd kann beispielsweise auf eine Textanzeige, eine Hotelanzeige oder eine lokale Anzeige verweisen.
Sie können über das Feld AdGroupAd.ad.type auf den Typwert zugreifen. Der Wert wird im Enum AdType zurückgegeben.
Ressourcennamen
Jede Ressource wird durch einen eindeutigen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad zusammenfasst.
Ressourcennamen von Kampagnen haben beispielsweise das Format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Eine Kampagne mit der ID 987654 im Search Ads 360-Konto mit der Kundennummer 1234567 hat folgende resource_name:
customers/1234567/campaigns/987654
Dienste
Mit Diensten können Sie Ihre Search Ads 360-Entitäten und -Metadaten abrufen. Es gibt drei Diensttypen:
- Suchdienst
SearchAds360Service ist der einzige einheitliche Dienst zum Abrufen aller Ressourcenobjekte und Leistungsstatistiken. Es bietet zwei Methoden: Search und SearchStream. Für beide Methoden ist eine Abfrage erforderlich, in der die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte, die zum Filtern der Anfrage verwendeten Prädikate und die Segmente für eine weitere Aufschlüsselung der Leistungsstatistiken angegeben werden. Weitere Informationen finden Sie unter Suchberichte erstellen und Such Ads 360-Abfragesprache.- Außendienst
SearchAds360FieldService ruft Metadaten zu Ressourcen ab, z. B. die verfügbaren Attribute für eine Ressource und deren Datentyp. Sie können den Katalog für Ressourcen, Ressourcenfelder, Segmentierungsschlüssel und Messwerte anfordern, die in den SearchAds360Service-Suchmethoden verfügbar sind. Weitere Informationen finden Sie unter Ressourcenmetadaten abrufen.- Entitätsspezifische Dienste
Diese Dienste bieten eine GET-Anfragemethode, mit der eine einzelne Ressourceninstanz abgerufen wird. Das ist nützlich, um die Struktur einer Ressource zu untersuchen.
Beispiele für entitätsspezifische Dienste:
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-29 (UTC).
[null,null,["Zuletzt aktualisiert: 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."]]
