将结果分页
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Search Ads 360 Reporting API 支持通过 Search
方法对查询结果进行分页,方法是在请求中指定 page_size
。这会将查询的结果集分为多个响应,其中每个响应最多可包含 page_size
个对象。如果未指定 page_size
,系统会自动将其设置为页面大小上限(10,000 行)。
例如,使用以下查询:
SELECT
ad_group.id,
ad_group_criterion.type,
ad_group_criterion.criterion_id,
ad_group_criterion.keyword.text,
ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE ad_group_criterion.type = KEYWORD
如果您的账号包含 5 万个关键字,且 page_size
设置为 1,000
,则结果集中第一个响应中将包含 1,000 个 SearchAdsRow
对象,以及一个 next_page_token
。要检索下一批 1,000 行,只需使用相同的页面大小设置再发送一次请求即可,不过要将请求中的 page_token
更新为前一响应的 next_page_token
。在后续的每次请求中,page_size
的值可能都会不同。
我们的客户端库会自动处理分页。您只需遍历响应的行即可。在返回当前页面中的所有行后,客户端库会代表您自动获取新的行页面,直到检索了整个数据集为止。如果使用 REST 而非 gRPC,则必须为每个新页面明确发出请求。
Search Ads 360 Reporting API 在内部缓存整个数据集,因此后续请求的速度会比第一个请求快。根据您的用例,您可以将 page_size
设置为 1 到 10,000 之间的任何值。一般来说,为了加快整体的性能速度,您应该使用较大的 page_size
,因为可减少响应中的往返次数。
Java
// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package sample;
import com.beust.jcommander.Parameter;
import com.google.ads.searchads360.v0.lib.SearchAds360Client;
import com.google.ads.searchads360.v0.services.SearchAds360Row;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse;
import com.google.ads.searchads360.v0.services.SearchSearchAds360Request;
/** Get campaign details. */
public class GetCampaigns {
private static final int PAGE_SIZE = 200;
private static class GetCampaignsParams extends CodeSampleParams {
@Parameter(names = "--customerId", required = true)
private String customerId;
@Parameter(names = "--loginCustomerId")
private String loginCustomerId;
}
public static void main(String[] args) {
GetCampaignsParams params = new GetCampaignsParams();
if (!params.parseArguments(args)) {
// Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId
// here (10 digits, no dashes). If neither are set, customerId will be used as
// loginCustomerId.
// params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE");
}
final String loginCustomerId = params.loginCustomerId;
final String customerId = params.customerId;
try {
// Creates a SearchAds360Client with the specified loginCustomerId. If there's
// no loginCustomerId, customerId will be used instead.
final SearchAds360Client searchAds360Client =
SearchAds360Client.newBuilder()
.setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)
.fromPropertiesFile()
.build();
// Creates the Search Ads 360 Service client.
SearchAds360ServiceClient client = searchAds360Client.create();
new GetCampaigns().runExample(client, customerId);
} catch (Exception exception) {
System.err.printf("Failed with exception: %s%n", exception);
exception.printStackTrace();
System.exit(1);
}
}
private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {
// Creates a query that retrieves all campaigns under the customerId.
String query =
"""
SELECT campaign.name, campaign.id, campaign.status FROM campaign
""";
SearchSearchAds360Request request =
SearchSearchAds360Request.newBuilder()
.setCustomerId(customerId)
.setQuery(query)
.setPageSize(PAGE_SIZE)
.build();
// Issues a search request.
final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request);
for (SearchAds360Row element : searchPagedResponse.iterateAll()) {
System.out.printf(
"Campaign found with name '%s', ID %d, and status: %s.%n",
element.getCampaign().getName(),
element.getCampaign().getId(),
element.getCampaign().getStatus());
}
}
}
下载 GetCampaigns.java
Python
#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Retrieves campaigns for a customer using a pagination search request."""
import argparse
import traceback
from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request
from util_searchads360 import SearchAds360Client
_DEFAULT_PAGE_SIZE = 10000
def main(client, customer_id, page_size) -> None:
search_ads_360_service = client.get_service()
query = """
SELECT
campaign.name,
campaign.id,
campaign.status
FROM campaign"""
request = SearchSearchAds360Request()
request.customer_id = customer_id
request.query = query
request.page_size = page_size
# Issues a search request.
results = search_ads_360_service.search(request=request)
for row in results:
campaign = row.campaign
print(
f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}'
)
if __name__ == "__main__":
# SearchAds360Client will read the search-ads-360.yaml configuration file in
# the home directory if none is specified.
search_ads_360_client = SearchAds360Client.load_from_file()
parser = argparse.ArgumentParser(
description=("Retrieves campaigns for a customer."))
# Arguments to provide to run the example.
parser.add_argument(
"-c",
"--customer_id",
type=str,
required=True,
help="The Search Ads 360 customer ID (10 digits, no dashes).",
)
parser.add_argument(
"-l",
"--login_customer_id",
type=str,
required=False,
help="The Search Ads 360 login customer ID (10 digits, no dashes).",
)
args = parser.parse_args()
search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)
try:
main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE)
except Exception: # pylint: disable=broad-except
traceback.print_exc()
下载 get_campaigns.py
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[[["\u003cp\u003eThe Search Ads 360 Reporting API allows you to paginate query results using the \u003ccode\u003epage_size\u003c/code\u003e parameter in the \u003ccode\u003eSearch\u003c/code\u003e method, breaking large result sets into smaller, manageable responses.\u003c/p\u003e\n"],["\u003cp\u003eIf \u003ccode\u003epage_size\u003c/code\u003e is not specified, it defaults to a maximum of 10,000 rows per page.\u003c/p\u003e\n"],["\u003cp\u003eTo retrieve subsequent pages, use the \u003ccode\u003enext_page_token\u003c/code\u003e provided in the response of the previous page.\u003c/p\u003e\n"],["\u003cp\u003eThe provided client libraries automatically handle pagination for gRPC requests, while REST requests require manual page retrieval.\u003c/p\u003e\n"],["\u003cp\u003eUsing a larger \u003ccode\u003epage_size\u003c/code\u003e generally improves overall performance due to reduced round trips.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API uses the `Search` method and `page_size` to paginate results. Specifying `page_size` divides results into multiple responses, each with up to the defined `page_size` objects (default is 10,000). Each response, except the last, provides a `next_page_token` to request the subsequent page of data. Client libraries handle paging automatically, while REST requires explicit page requests. A larger `page_size` generally improves performance by reducing round trips.\n"],null,["# Paging through results\n\nThe Search Ads 360 Reporting API supports pagination of query results through the [`Search`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchAds360Service.Search) method by specifying [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) in your request. This will break up the result set of the query into multiple responses that each contains\nup to [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) objects. If [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) is not specified, it is automatically set to the maximum page size of 10,000 rows.\n\nFor example, with the following query: \n\n SELECT\n ad_group.id,\n ad_group_criterion.type,\n ad_group_criterion.criterion_id,\n ad_group_criterion.keyword.text,\n ad_group_criterion.keyword.match_type\n FROM ad_group_criterion\n WHERE ad_group_criterion.type = KEYWORD\n\nIf your account contains 50,000 keywords and [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) is set to `1,000`, the\nresult set will contain 1,000 [`SearchAdsRow`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchAds360Row)\nobjects in the first response,\nalong with a [`next_page_token`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchsearchads360response). To retrieve the next one thousand rows, simply\nsend the request again with the same page size, but update the request's\n`page_token` to the response's [`next_page_token`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchsearchads360response). The value of [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) in\nthe subsequent requests can be different each time.\n| **Note:** The [`next_page_token`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchsearchads360response) will not be populated on the response that contains the last batch of rows.\n\nOur [client libraries](/search-ads/reporting/client-libraries/client-libraries) handle paging automatically. You only have to iterate\nthrough the rows of the response. When all the rows in the current page have\nbeen returned, the client library will fetch a new page of rows automatically on\nyour behalf until the entire data set has been retrieved. If using REST instead\nof gRPC, you must explicitly make a request for each new page.\n\nSearch Ads 360 Reporting API internally caches the entire data set, so subsequent requests are faster\nthan the first request. Depending on your use case, you can set [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) to\nany value between 1 and 10,000. In general, for faster overall performance, you\nshould use a larger [`page_size`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#google.ads.searchads360.v0.services.SearchSearchAds360Request) due to fewer round trips in your responses.\n\nPagination example\n------------------\n\n### Java\n\n\n```java\n// Copyright 2022 Google LLC\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sample;\n\nimport com.beust.jcommander.Parameter;\nimport com.google.ads.searchads360.v0.lib.SearchAds360Client;\nimport com.google.ads.searchads360.v0.services.SearchAds360Row;\nimport com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;\nimport com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse;\nimport com.google.ads.searchads360.v0.services.SearchSearchAds360Request;\n\n/** Get campaign details. */\npublic class GetCampaigns {\n private static final int PAGE_SIZE = 200;\n\n private static class GetCampaignsParams extends CodeSampleParams {\n\n @Parameter(names = \"--customerId\", required = true)\n private String customerId;\n\n @Parameter(names = \"--loginCustomerId\")\n private String loginCustomerId;\n }\n\n public static void main(String[] args) {\n GetCampaignsParams params = new GetCampaignsParams();\n if (!params.parseArguments(args)) {\n // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId\n // here (10 digits, no dashes). If neither are set, customerId will be used as\n // loginCustomerId.\n // params.loginCustomerId = Long.parseLong(\"INSERT_LOGIN_CUSTOMER_ID_HERE\");\n }\n final String loginCustomerId = params.loginCustomerId;\n final String customerId = params.customerId;\n\n try {\n // Creates a SearchAds360Client with the specified loginCustomerId. If there's\n // no loginCustomerId, customerId will be used instead.\n final SearchAds360Client searchAds360Client =\n SearchAds360Client.newBuilder()\n .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)\n .fromPropertiesFile()\n .build();\n // Creates the Search Ads 360 Service client.\n SearchAds360ServiceClient client = searchAds360Client.create();\n new GetCampaigns().runExample(client, customerId);\n } catch (Exception exception) {\n System.err.printf(\"Failed with exception: %s%n\", exception);\n exception.printStackTrace();\n System.exit(1);\n }\n }\n\n private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {\n // Creates a query that retrieves all campaigns under the customerId.\n String query =\n \"\"\"\n SELECT campaign.name, campaign.id, campaign.status FROM campaign\n \"\"\";\n SearchSearchAds360Request request =\n SearchSearchAds360Request.newBuilder()\n .setCustomerId(customerId)\n .setQuery(query)\n .setPageSize(PAGE_SIZE)\n .build();\n\n // Issues a search request.\n final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request);\n for (SearchAds360Row element : searchPagedResponse.iterateAll()) {\n System.out.printf(\n \"Campaign found with name '%s', ID %d, and status: %s.%n\",\n element.getCampaign().getName(),\n element.getCampaign().getId(),\n element.getCampaign().getStatus());\n }\n }\n}\n```\n\n\u003cbr /\u003e\n\n[Download GetCampaigns.java](https://developers.google.com/search-ads/reporting/sample-code/GetCampaigns.java)\n\n### Python\n\n\n```python\n#!/usr/bin/env python\n# Copyright 2022 Google LLC\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# https://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Retrieves campaigns for a customer using a pagination search request.\"\"\"\n\nimport argparse\nimport traceback\nfrom google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request\nfrom util_searchads360 import SearchAds360Client\n\n_DEFAULT_PAGE_SIZE = 10000\n\n\ndef main(client, customer_id, page_size) -\u003e None:\n search_ads_360_service = client.get_service()\n\n query = \"\"\"\n SELECT\n campaign.name,\n campaign.id,\n campaign.status\n FROM campaign\"\"\"\n\n request = SearchSearchAds360Request()\n request.customer_id = customer_id\n request.query = query\n request.page_size = page_size\n\n # Issues a search request.\n results = search_ads_360_service.search(request=request)\n\n for row in results:\n campaign = row.campaign\n print(\n f'campaign \"{campaign.name}\" has id {campaign.id} and status {campaign.status.name}'\n )\n\n\nif __name__ == \"__main__\":\n # SearchAds360Client will read the search-ads-360.yaml configuration file in\n # the home directory if none is specified.\n search_ads_360_client = SearchAds360Client.load_from_file()\n\n parser = argparse.ArgumentParser(\n description=(\"Retrieves campaigns for a customer.\"))\n # Arguments to provide to run the example.\n parser.add_argument(\n \"-c\",\n \"--customer_id\",\n type=str,\n required=True,\n help=\"The Search Ads 360 customer ID (10 digits, no dashes).\",\n )\n\n parser.add_argument(\n \"-l\",\n \"--login_customer_id\",\n type=str,\n required=False,\n help=\"The Search Ads 360 login customer ID (10 digits, no dashes).\",\n )\n\n args = parser.parse_args()\n\n search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)\n\n try:\n main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE)\n except Exception: # pylint: disable=broad-except\n traceback.print_exc()\n```\n\n\u003cbr /\u003e\n\n[Download get_campaigns.py](https://developers.google.com/search-ads/reporting/sample-code/get_campaigns.py)"]]