La nouvelle API Search Ads 360 Reporting est désormais disponible. Rejoignez le groupe Google
searchads-api-announcements pour vous tenir informé des améliorations et versions à venir.
Structure de l'API de création de rapports Search Ads 360
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Les principaux composants de l'API Search Ads 360 Reporting sont les ressources et les services. Une ressource représente une entité Search Ads 360, et vous utilisez un service pour récupérer des entités Search Ads 360.
Hiérarchie des objets
Un compte Search Ads 360 est une hiérarchie d'objets.
La ressource de niveau supérieur d'un compte est le client.
Chaque compte contient une ou plusieurs campagnes actives.
Chaque Campaign contient un ou plusieurs groupes d'annonces qui regroupent vos annonces en collections logiques.
Chaque AdGroup contient une ou plusieurs annonces de groupe d'annonces.
Vous pouvez associer une ou plusieurs AdGroupCriterion ou CampaignCriterion à un groupe d'annonces ou à une campagne. Les critères définissent la manière dont les annonces sont déclenchées.
- Il existe de nombreux types de critères, comme les mots clés, les tranches d'âge et les zones géographiques. Les critères définis au niveau de la campagne affectent toutes les autres ressources de la campagne. Vous pouvez également définir des dates et des budgets pour l'ensemble de la campagne.
Ressources
Les ressources représentent les entités de votre compte Search Ads 360. Customer, Campaign et AdGroup sont des exemples de ressources.
ID des objets
Chaque objet de Search Ads 360 est identifié par son propre ID. Certains ID sont uniques au niveau mondial, c'est-à-dire pour tous les comptes Search Ads 360, tandis que d'autres ne sont uniques que dans un champ d'application limité.
| Champ d'application de l'unicité des ID d'objet |
| ID du budget |
Monde |
| ID de la campagne |
Monde |
| ID groupe d'annonces |
Monde |
| Identifiant d'annonce |
Groupe d'annoncesChaque paire AdGroupId / AdId est globalement unique. |
| ID du critère de groupe d'annonces |
Groupe d'annoncesChaque paire AdGroupId / CriterionId est globalement unique. |
| ID du critère de campagne |
CampagneChaque paire CampaignId / CriterionId est globalement unique. |
| Extensions d'annonce |
CampagneChaque paire CampaignId / AdExtensionId est globalement unique. |
| ID du flux |
Monde |
| ID de l'élément de flux |
Monde |
| ID de l'attribut du flux |
Flux |
| ID de correspondance de flux |
Monde |
| ID du libellé |
Monde |
| ID de la liste d'utilisateurs |
Monde |
Ces règles d'ID peuvent être utiles lorsque vous concevez un stockage local pour vos objets Search Ads 360.
Types d'objet
Certains objets peuvent être utilisés pour plusieurs types d'entités. Dans ce cas, l'objet contient un champ type qui décrit son contenu. Par exemple, AdGroupAd peut faire référence à une annonce textuelle, à une annonce d'hôtel ou à une annonce locale.
Vous pouvez accéder à la valeur du type via le champ AdGroupAd.ad.type. Sa valeur est renvoyée dans l'énumération AdType.
Noms de ressources
Chaque ressource est identifiée de manière unique par une chaîne resource_name qui concatène la ressource et ses parents dans un chemin d'accès.
Par exemple, les noms de ressources "Campagne" se présentent comme suit:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Une campagne avec l'ID 987654 dans le compte Search Ads 360 avec le numéro client 1234567 a les resource_name suivantes:
customers/1234567/campaigns/987654
Services
Les services vous permettent de récupérer vos entités et métadonnées Search Ads 360. Il existe trois types de services:
- Service de recherche
SearchAds360Service est le service unique et unifié permettant de récupérer tous les objets de ressources et les statistiques de performances. Il fournit deux méthodes: Search et SearchStream. Les deux méthodes nécessitent une requête qui spécifie la ressource à interroger, les attributs de ressource et les métriques de performances à récupérer, les prédicats à utiliser pour filtrer la requête et les segments à utiliser pour approfondir les statistiques de performances. Pour en savoir plus, consultez Créer des rapports sur les recherches et Langage de requête Search Ads 360.- Service sur le terrain
SearchAds360FieldService récupère les métadonnées sur les ressources, telles que les attributs disponibles pour une ressource et son type de données. Vous pouvez demander le catalogue des ressources, des champs de ressources, des clés de segmentation et des métriques disponibles dans les méthodes de recherche SearchAds360Service. Pour en savoir plus, consultez la section Récupérer les métadonnées de ressource.- Services spécifiques à l'entité
Ces services fournissent une méthode de requête GET qui récupère une seule instance de ressource. Cela est utile pour examiner la structure d'une ressource.
Voici quelques exemples de services spécifiques à une entité:
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/29 (UTC).
[null,null,["Dernière mise à jour le 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."]]
