Google Ads API에는 Google Ads 쿼리 언어를 사용하여 쿼리를 만들 수 있는 통합 속성 검색 및 측정항목 보고 메커니즘이 있습니다. 따라서 개별 Google Ads 계정에 대한 많은 양의 데이터를 반환할 수 있는 복잡한 쿼리를 사용할 수 있습니다.
Search 또는 SearchStream 메서드 중 하나를 사용하여 쿼리를 만들 수 있습니다.
두 메서드 모두 동일한 쿼리를 지원하고 동일한 결과를 반환합니다. Search 메서드는 맞춤설정 가능한 페이지 크기로 데이터를 반환하므로 페이지로 나누기를 사용하여 결과 집합을 반복할 수 있습니다. 이는 대역폭이 낮거나 불안정한 네트워크 조건에서 유용할 수 있습니다. 예를 들어 대규모 결과 집합을 작은 응답으로 세분화하여 연결이 끊어졌을 때 다시 가져올 수 있습니다. 반면 SearchStream 메서드는 전체 결과 집합을 단일 응답으로 다시 스트리밍하므로 일괄 데이터를 가져오는 데 더 효율적일 수 있습니다.
Search와 SearchStream는 모두 동일한 기본 URL을 사용합니다.
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds
페이지 기반 검색 메서드에는 단일 API 응답으로 반환되는 결과 수를 제한하는 pageSize 매개변수가 선택사항으로 사용됩니다.
POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}
결과에 pageSize보다 많은 행이 있으면 응답에 nextPageToken가 반환됩니다.
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
위의 값과 함께 pageToken를 추가하여 동일한 쿼리를 반복하면 다음 결과 페이지를 가져옵니다.
POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}
스트리밍된 단일 응답으로 모든 결과를 반환하는 SearchStream 메서드를 사용하려면 URL의 서비스 메서드를 searchStream로 변경하기만 하면 됩니다(SearchStream에서는 pageSize 및 pageToken가 필요하지 않음).
POST /v16/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}