객체 검색
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
GoogleAdsService는 Google Ads API의 통합 객체 검색 및 보고 서비스입니다. 서비스에는 다음을 수행하는 메서드가 있습니다.
- 객체의 특정 속성을 가져옵니다.
- 기간을 기준으로 객체의 실적 측정항목을 가져옵니다.
- 속성을 기준으로 객체를 정렬합니다.
- 조건을 사용하여 응답에서 반환할 객체를 나타냅니다.
- 반환되는 객체 수를 제한합니다.
GoogleAdsService는 다음 두 가지 방법으로 결과를 반환할 수 있습니다.
페이징과 스트리밍의 차이에 대해 자세히 알아보세요.
요청하기
검색 메서드에는 다음 속성으로 구성된 SearchGoogleAdsRequest이 필요합니다.
customer_id- 쿼리할 리소스, 검색할 속성, 세그먼트, 측정항목, 반환되는 객체를 제한하는 데 사용할 조건을 나타내는 Google Ads 쿼리 언어
query
- (
GoogleAdsService.Search만 해당) 페이징을 사용할 때 다음 결과 일괄 처리를 가져오는 선택적 page_token입니다.
Google Ads 쿼리 언어에 대한 자세한 내용은 Google Ads 쿼리 언어 가이드를 참고하세요.
응답 처리
GoogleAdsService은 GoogleAdsRow 객체 목록을 반환합니다.
각 GoogleAdsRow는 쿼리에서 반환된 객체를 나타내며 SELECT 절에서 요청된 필드에 따라 채워지는 속성 집합으로 구성됩니다. SELECT 절에 포함되지 않은 속성은 응답의 GoogleAdsRow 객체에 채워지지 않습니다.
예를 들어 ad_group_criterion에 status 속성이 있지만 SELECT 절에 ad_group_criterion.status이 포함되지 않은 쿼리의 응답에서는 행의 ad_group_criterion 속성의 status 필드가 채워지지 않습니다. 마찬가지로 SELECT 절에 campaign 리소스의 필드가 포함되지 않으면 행의 campaign 속성이 채워지지 않습니다.
각 GoogleAdsRow에는 동일한 결과 집합의 다른 행과 다른 속성과 측정항목이 있을 수 있으므로 행은 테이블의 고정된 행이 아닌 객체로 간주해야 합니다.
알 수 없는 enum 유형
UNKNOWN 유형으로 반환되는 리소스는 해당 API 버전에서 완전히 지원되지 않습니다. 이러한 리소스는 Google Ads UI와 같은 다른 인터페이스를 통해 만들어졌을 수 있습니다. 리소스의 유형이 UNKNOWN인 경우 측정항목을 선택할 수 있지만 API를 통해 리소스를 변경할 수는 없습니다. 예를 들어 UI에 새 캠페인 또는 광고가 도입되었지만 쿼리하는 API 버전에서는 지원되지 않는 경우가 있습니다.
다음과 같은 몇 가지 사항에 유의해야 합니다.
UNKNOWN 유형의 리소스는 나중에 지원되거나 무기한 UNKNOWN 상태로 유지될 수 있습니다.UNKNOWN 유형의 새 객체는 언제든지 표시될 수 있습니다. 열거형 값을 이미 사용할 수 있으므로 이러한 객체는 이전 버전과 호환됩니다. 이 변경사항을 통해 리소스가 도입됩니다. 리소스는 계정을 정확하게 파악할 수 있도록 제공됩니다. UNKNOWN 리소스는 다른 인터페이스를 통해 계정에서 새 활동이 발생하거나 리소스가 더 이상 지원되지 않는 경우에 표시될 수 있습니다.UNKNOWN 리소스에는 쿼리할 수 있는 세부 측정항목이 연결될 수 있습니다.UNKNOWN 리소스는 일반적으로 Google Ads UI에 완전히 표시됩니다.UNKNOWN 리소스는 일반적으로 변경할 수 없습니다.
세분화
응답에는 다음의 각 조합에 대한 GoogleAdsRow이 하나씩 포함됩니다.
FROM 절에 지정된 기본 리소스의 인스턴스- 선택한 각
segment 필드의 값
예를 들어 FROM campaign을 선택하고 SELECT 절에 segments.ad_network_type 및 segments.date가 있는 쿼리의 응답에는 다음 조합마다 하나의 행이 포함됩니다.
campaignsegments.ad_network_typesegments.date
결과는 선택한 개별 필드의 값이 아닌 기본 리소스의 각 인스턴스별로 암시적으로 분류됩니다. 예를 들면 다음과 같습니다.
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
campaign.status 필드의 고유한 값당 하나의 행이 아닌 캠페인당 하나의 행이 표시됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-09-05(UTC)
[null,null,["최종 업데이트: 2025-09-05(UTC)"],[[["\u003cp\u003eGoogle Ads API's \u003ccode\u003eGoogleAdsService\u003c/code\u003e enables retrieval of object attributes, performance stats, and implements ordering, conditions, and limits for streamlined data access.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService\u003c/code\u003e offers two response methods: \u003ccode\u003eSearchStream\u003c/code\u003e for efficient handling of large datasets and \u003ccode\u003eSearch\u003c/code\u003e for manageable, paginated results.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService.Search\u003c/code\u003e requests require \u003ccode\u003ecustomer_id\u003c/code\u003e, Google Ads Query Language \u003ccode\u003equery\u003c/code\u003e, and optional pagination parameters (\u003ccode\u003epage_size\u003c/code\u003e, \u003ccode\u003epage_token\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003eResponses comprise \u003ccode\u003eGoogleAdsRow\u003c/code\u003e objects, reflecting queried object attributes and metrics as specified in the \u003ccode\u003eSELECT\u003c/code\u003e clause.\u003c/p\u003e\n"],["\u003cp\u003eResources returned with an \u003ccode\u003eUNKNOWN\u003c/code\u003e type are not fully supported in that API version, might have been created through other interfaces, and are generally not mutable.\u003c/p\u003e\n"]]],[],null,["# Retrieving objects\n\n| **Objective:** Understand how to retrieve objects and performance stats using [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService). For reporting concepts, see the [reporting guides](/google-ads/api/docs/reporting/overview).\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) is the unified object\nretrieval and reporting service of the Google Ads API. The service has methods that:\n\n- Retrieve specific attributes of objects.\n- Retrieve performance metrics for objects based on a date range.\n- Order objects based on their attributes.\n- Use conditions to indicate which objects you want returned in the response.\n- Limit the number of objects returned.\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) can return results in\ntwo ways:\n\n- [`GoogleAdsService.SearchStream`](/google-ads/api/reference/rpc/v21/GoogleAdsService/SearchStream) returns all rows in a single streaming response which is more efficient for large (greater than 10,000 rows) result sets. This might be more appropriate if your batch application wants to download as much data as fast as possible.\n- [`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) breaks up large responses into manageable pages of results. This could be more appropriate if your interactive application displays a page of results at a time.\n\nLearn more about [paging versus streaming](/google-ads/api/docs/reporting/streaming).\n\nMake a request\n--------------\n\nThe search method requires a\n[`SearchGoogleAdsRequest`](/google-ads/api/reference/rpc/v21/SearchGoogleAdsRequest), which consists\nof the following attributes:\n\n- A `customer_id`\n- A Google Ads Query Language `query` that indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned\n- ([`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) only) An optional `page_token` to retrieve the next batch of results when using [paging](/google-ads/api/docs/reporting/paging).\n\nFor more information on the Google Ads Query Language, check out the [Google Ads Query Language\nguide](/google-ads/api/docs/query/overview).\n\nProcess a response\n------------------\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) returns a list of\n[`GoogleAdsRow`](/google-ads/api/reference/rpc/v21/GoogleAdsRow) objects.\n\nEach `GoogleAdsRow` represents an object returned by a query, and consists of a\nset of attributes that are populated based on the fields requested in the\n`SELECT` clause. Attributes not included in the `SELECT` clause are not\npopulated on the `GoogleAdsRow` objects in the response.\n\nFor example, although an `ad_group_criterion` has a `status` attribute, the\n`status` field of the row's `ad_group_criterion` attribute is not populated in a\nresponse for a query where the `SELECT` clause does not include\n`ad_group_criterion.status`. Similarly, the `campaign` attribute of the row is\nnot populated if the `SELECT` clause does not include any fields from the\n`campaign` resource.\n\nEach `GoogleAdsRow` can have different attributes and metrics from another row\nin the same result set; so the rows should be viewed as objects rather than\nfixed rows of a table.\n\nUNKNOWN enum types\n------------------\n\nResources that are returned with a type of `UNKNOWN` are not fully supported in\nthat API version. These resources could have been created through other\ninterfaces such as the Google Ads UI. You can select metrics when a resource has a\ntype of `UNKNOWN`, but you cannot mutate the resource through the API. An\nexample of this would be a new campaign or ad being introduced in the UI, but\nnot supported in the API version you are querying.\n\nHere are some considerations to keep in mind:\n\n- A resource with an `UNKNOWN` type can be supported later or stay `UNKNOWN` indefinitely.\n- New objects with type `UNKNOWN` can appear at any time. These objects are backward compatible because the enum value is already available. Resources are introduced with this change as they're available so that you have an accurate view of your account. The `UNKNOWN` resource can appear due to new activities in your account through other interfaces, or when a resource is no longer supported.\n- `UNKNOWN` resources can have detailed metrics attached to them that are queryable.\n- `UNKNOWN` resources are typically fully visible in the Google Ads UI.\n- `UNKNOWN` resources generally cannot be mutated.\n\nSegmentation\n------------\n\nThe response would contain one `GoogleAdsRow` for each combination of the\nfollowing:\n\n- Instance of the main resource specified in the `FROM` clause\n- Value of each selected `segment` field\n\nFor example, the response for a query that selects `FROM campaign` and has\n`segments.ad_network_type` and `segments.date` in the `SELECT` clause would\ncontain one row for each combination of the following:\n\n- `campaign`\n- `segments.ad_network_type`\n- `segments.date`\n\nResults are implicitly segmented by each instance of the main resource, not by\nthe values of the individual fields selected. For example, \n\n SELECT campaign.status, metrics.impressions\n FROM campaign\n WHERE segments.date DURING LAST_14_DAYS\n\nresults in one row per **campaign** , not one row per distinct value of the\n`campaign.status` field."]]
