Search Ads 360 Reporting API 구조
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Search Ads 360 Reporting API의 기본 구성요소는 리소스와 서비스입니다. 리소스는 Search Ads 360 항목을 나타내며 서비스를 사용하여 Search Ads 360 항목을 검색합니다.
객체 계층 구조
Search Ads 360 계정은 객체의 계층 구조입니다.
계정의 최상위 리소스는 고객입니다.
각 계정에는 운영 중인 캠페인이 하나 이상 포함되어 있습니다.
각 Campaign에는 광고를 논리적 컬렉션으로 그룹화하는 하나 이상의 광고 그룹이 포함됩니다.
각 AdGroup에는 하나 이상의 광고 그룹 광고가 포함됩니다.
하나 이상의 AdGroupCriterion 또는 CampaignCriterion를 광고 그룹 또는 캠페인에 연결할 수 있습니다. 기준은 광고가 트리거되는 방식을 정의합니다.
- 키워드, 연령대, 위치와 같은 다양한 기준 유형이 있습니다. 캠페인 수준에서 정의된 기준은 캠페인 내의 다른 모든 리소스에 영향을 미칩니다. 캠페인 전체의 예산과 기간을 지정할 수도 있습니다.
리소스
리소스는 Search Ads 360 계정의 항목을 나타냅니다. 리소스의 예로는 Customer, Campaign, AdGroup가 있습니다.
객체 ID
Search Ads 360의 모든 객체는 자체 ID로 식별됩니다. 일부 ID는 전 세계적으로 고유합니다(즉, 모든 Search Ads 360 계정에서 고유함). 반면 일부 ID는 제한된 범위 내에서만 고유합니다.
| 객체 ID 고유성 범위 |
| 예산 ID |
전역 |
| 캠페인 ID |
전역 |
| 광고그룹 ID |
전역 |
| 광고 ID |
광고그룹각 AdGroupId / AdId 쌍은 전 세계적으로 고유합니다. |
| AdGroupCriterion ID |
광고그룹각 AdGroupId / CriterionId 쌍은 전 세계적으로 고유합니다. |
| CampaignCriterion ID |
캠페인각 CampaignId / CriterionId 쌍은 전 세계적으로 고유합니다. |
| 광고 확장 |
캠페인각 CampaignId / AdExtensionId 쌍은 전 세계적으로 고유합니다. |
| 피드 ID |
전역 |
| Feed Item ID |
전역 |
| Feed Attribute ID |
피드 |
| Feed Mapping ID |
전역 |
| 라벨 ID |
전역 |
| UserList ID |
전역 |
이러한 ID 규칙은 Search Ads 360 객체의 로컬 저장소를 설계할 때 유용할 수 있습니다.
객체 유형
일부 객체는 여러 항목 유형에 사용할 수 있습니다. 이 경우 객체에는 콘텐츠를 설명하는 type 필드가 포함됩니다. 예를 들어
AdGroupAd는 텍스트 광고, 호텔 광고, 지역 광고를 나타낼 수 있습니다.
AdGroupAd.ad.type 필드를 통해 유형 값에 액세스할 수 있습니다. 값은 AdType enum으로 반환됩니다.
리소스 이름
각 리소스는 리소스와 상위 요소를 경로로 연결하는 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 요청 메서드를 제공합니다. 이는 리소스의 구조를 검사하는 데 유용합니다.
항목별 서비스의 예는 다음과 같습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 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."]]
