创建查询
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Bid Manager API Query
资源代表您在界面中作为 Display & Video 360 报告看到的内容。运行以下查询以生成 Report
资源。如果成功,Report
资源会提供其中
您可以下载生成的报告
本页介绍了如何构建和创建 Query
资源。
选择过滤条件、维度和指标
在每个 Query
中,在 params
字段中提供以下 Parameters
,以优化报告中返回的数据:
如需详细了解 Query
结构,请参阅参考文档
文档。
选择这些值时,请考虑在 type
字段中设置的 ReportType
。您选择的指标和过滤条件值必须与报告类型兼容,系统才能成功生成报告。
创建查询
确定报告的核心结构后,您就可以创建查询了。
以下是创建包含过去七天数据的临时报告的方法:
Java
// Display name of the query to create.
String displayName = display-name;
// The report type.
String reportType = report-type;
// The advertisers and campaigns by which to filter report data.
List<String> advertiserIdFilters =
Arrays.asList(advertiser-id,...);
List<String> campaignIdFilters =
Arrays.asList(campaign-id,...);
// The dimensions and metrics for the report.
List<String> dimensions = Arrays.asList(dimension,...);
List<String> metrics = Arrays.asList(metric,...);
// Build a list of filter pairs from given IDs.
List<FilterPair> filters = new ArrayList<FilterPair>();
if (advertiserIdFilters != null) {
for (String advertiserId : advertiserIdFilters) {
filters.add(
new FilterPair().setType("FILTER_ADVERTISER").setValue(advertiserId));
}
}
if (campaignIdFilters != null) {
for (String campaignId : campaignIdFilters) {
filters.add(
new FilterPair().setType("FILTER_MEDIA_PLAN").setValue(campaignId));
}
}
// Create the query structure.
Query query = new Query();
// Build and set the metadata object.
QueryMetadata metadata = new QueryMetadata();
metadata.setTitle(displayName);
metadata.setDataRange(new DataRange().setRange("LAST_7_DAYS"));
metadata.setFormat("CSV");
query.setMetadata(metadata);
// Build the parameters object.
Parameters parameters = new Parameters();
parameters.setType(reportType);
parameters.setGroupBys(dimensions);
parameters.setFilters(filters);
parameters.setMetrics(metrics);
// Set parameters object in query.
query.setParams(parameters);
// Build and set the schedule object.
QuerySchedule schedule = new QuerySchedule();
schedule.setFrequency("ONE_TIME");
query.setSchedule(schedule);
// Create the query.
Query queryResponse = service.queries().create(query).execute();
// Log query creation.
System.out.printf("Query %s was created.%n", queryResponse.getQueryId());
Python
# Display name of the query to create.
display_name = display-name
# The report type.
report_type = report-type
# The advertisers and campaigns by which to filter report data.
filtered_advertiser_ids = [advertiser-id,...]
filtered_campaign_ids = [campaign-id,...]
# The dimensions and metrics for the report.
dimensions = [dimension,...]
metrics = [metric,...]
# Build list of FilterPair objects.
filters = []
if filtered_campaign_ids != None:
filters.extend([
{"type": "FILTER_MEDIA_PLAN", "value": id}
for id in filtered_campaign_ids
])
if filtered_advertiser_ids != None:
filters.extend([
{"type": "FILTER_ADVERTISER", "value": id}
for id in filtered_advertiser_ids
])
# Build query object.
query_obj = {
"metadata": {
"title": display_name,
"dataRange": {"range": "LAST_7_DAYS"},
"format": "CSV",
},
"params": {
"type": report_type,
"groupBys": dimensions,
"filters": filters,
"metrics": metrics,
},
"schedule": {"frequency": "ONE_TIME"}
}
# Create query object.
query_response = service.queries().create(body=query_obj).execute()
# Print new query ID.
print(f'Query {query_response["queryId"]} was created.')
PHP
// Display name of the query to create.
$displayName = display-name;
// The report type.
$reportType = report-type;
// Advertiser ID and campaign ID by which to filter data.
$advertiserIdFilters = array(advertiser-id,...);
$campaignIdFilters = array(campaign-id,...);
// The dimensions and metrics for the report.
$dimensions = array(dimension,...);
$metrics = array(metric,...);
// Build a list of filter pairs from given IDs.
$filters = array();
foreach ($advertiserIdFilters as $advertiserId) {
$filterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$filterPair->setType("FILTER_ADVERTISER");
$filterPair->setValue($advertiserId);
array_push($filters, $filterPair);
}
foreach ($campaignIdFilters as $campaignId) {
$filterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$filterPair->setType("FILTER_MEDIA_PLAN");
$filterPair->setValue($campaignId);
array_push($filters, $filterPair);
}
// Create the query structure.
$query = new Google_Service_DoubleClickBidManager_Query();
// Build and set the metadata object.
$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();
$metadata->setTitle($displayName);
$metadata->setFormat("CSV");
$dataRange = new Google_Service_DoubleClickBidManager_DataRange();
$dataRange->setRange("LAST_7_DAYS");
$metadata->setDataRange($dataRange);
$query->setMetadata($metadata);
// Build and set the parameters object.
$parameters = new Google_Service_DoubleClickBidManager_Parameters();
$parameters->setType($reportType);
$parameters->setGroupBys($dimensions);
$parameters->setFilters($filters);
$parameters->setMetrics($metrics);
$query->setParams($parameters);
// Build and set the schedule object.
$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();
$schedule->setFrequency("ONE_TIME");
$query->setSchedule($schedule);
// Call the API, creating the query.
$queryResult = $this->service->queries->create($query);
printf('Query %s was created.<br>', $queryResult->getQueryId());
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-31。
[null,null,["最后更新时间 (UTC):2025-08-31。"],[[["\u003cp\u003eThe Bid Manager API \u003ccode\u003eQuery\u003c/code\u003e resource allows you to generate reports similar to those in the Display & Video 360 UI.\u003c/p\u003e\n"],["\u003cp\u003eReports are generated by running a \u003ccode\u003eQuery\u003c/code\u003e that defines filters, dimensions, and metrics using \u003ccode\u003eParameters\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eYou can refine report data by specifying \u003ccode\u003efilters\u003c/code\u003e, \u003ccode\u003egroupBys\u003c/code\u003e (dimensions), and \u003ccode\u003emetrics\u003c/code\u003e within the \u003ccode\u003eQuery\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eReportType\u003c/code\u003e determines which metrics and filters are compatible with your query, and it's crucial to ensure their compatibility for successful report generation.\u003c/p\u003e\n"],["\u003cp\u003eThe provided code examples demonstrate how to create an ad hoc report for the last seven days using Java, Python, and PHP.\u003c/p\u003e\n"]]],[],null,["# Create query\n\nThe Bid Manager API [`Query`](/bid-manager/reference/rest/current/queries#Query) resource represents what you see in the UI as\na Display \\& Video 360 report. Run this query to generate a [`Report`](/bid-manager/reference/rest/current/queries.reports#Report)\nresource. If successful, the [`Report`](/bid-manager/reference/rest/current/queries.reports#Report) resource provides the URL where\nyou can download the resulting report.\n\nThis page explains how to structure and create a [`Query`](/bid-manager/reference/rest/current/queries#Query) resource.\n\nChoose filters, dimensions, and metrics\n---------------------------------------\n\nIn each [`Query`](/bid-manager/reference/rest/current/queries#Query), provide the following [`Parameters`](/bid-manager/reference/rest/current/Parameters) in the\n[`params`](/bid-manager/reference/rest/current/queries#Query.FIELDS.params) field to refine the data that's returned in the report:\n\n- [`filters`](/bid-manager/reference/rest/current/Parameters#FIELDS.filters) limit the scope of the data. filters takes a list of [`FilterPair`](/bid-manager/reference/rest/current/Parameters#FilterPair) objects, where the [`type`](/bid-manager/reference/rest/current/Parameters#FilterPair.FIELDS.type) is a [Filter](/bid-manager/reference/rest/current/filters-metrics#filters) enum, and the [`value`](/bid-manager/reference/rest/current/Parameters#FilterPair.FIELDS.value) is an identifying string, such as the relevant resource ID.\n- [`groupBys`](/bid-manager/reference/rest/current/Parameters#FIELDS.group_bys) define the dimensions for the report, represented by a list of [Filter](/bid-manager/reference/rest/current/filters-metrics#filters) enums.\n- [`metrics`](/bid-manager/reference/rest/current/Parameters#FIELDS.metrics) define the data populating the report, represented by a list of [Metric](/bid-manager/reference/rest/current/filters-metrics#metrics) enums.\n\nFor more details on [`Query`](/bid-manager/reference/rest/current/queries#Query) structure, see the [reference\ndocumentation](/bid-manager/reference/rest).\n| **Tip:** If you are building a brand new report, [use the Display \\& Video 360 UI to\n| build the report structure](/bid-manager/guides/general/best-practices#build_new_reports_in_the_ui_first). In the UI, restrictions on filters, dimensions, and metrics combinations are automatically enforced.\n\nWhen choosing these values, consider your [`ReportType`](/bid-manager/reference/rest/current/Parameters#ReportType),\nthat's set in the [`type`](/bid-manager/reference/rest/current/Parameters#FIELDS.type) field. [Your selected metrics and filters\nvalues must be compatible with the report type](/bid-manager/guides/general/best-practices#use_metrics_and_filters_specific_to_the_report_type) for the report\nto successfully generate.\n\nCreate a query\n--------------\n\nOnce you determine the core structure of your report, you can create your query.\n\nHere's how to create an ad hoc report consisting of data from the last seven\ndays: \n\n### Java\n\n```java\n// Display name of the query to create.\nString displayName = display-name;\n\n// The report type.\nString reportType = report-type;\n\n// The advertisers and campaigns by which to filter report data.\nList\u003cString\u003e advertiserIdFilters =\n Arrays.asList(advertiser-id,...);\nList\u003cString\u003e campaignIdFilters =\n Arrays.asList(campaign-id,...);\n\n// The dimensions and metrics for the report.\nList\u003cString\u003e dimensions = Arrays.asList(dimension,...);\nList\u003cString\u003e metrics = Arrays.asList(metric,...);\n\n// Build a list of filter pairs from given IDs.\nList\u003cFilterPair\u003e filters = new ArrayList\u003cFilterPair\u003e();\nif (advertiserIdFilters != null) {\n for (String advertiserId : advertiserIdFilters) {\n filters.add(\n new FilterPair().setType(\"FILTER_ADVERTISER\").setValue(advertiserId));\n }\n}\nif (campaignIdFilters != null) {\n for (String campaignId : campaignIdFilters) {\n filters.add(\n new FilterPair().setType(\"FILTER_MEDIA_PLAN\").setValue(campaignId));\n }\n}\n\n// Create the query structure.\nQuery query = new Query();\n\n// Build and set the metadata object.\nQueryMetadata metadata = new QueryMetadata();\nmetadata.setTitle(displayName);\nmetadata.setDataRange(new DataRange().setRange(\"LAST_7_DAYS\"));\nmetadata.setFormat(\"CSV\");\nquery.setMetadata(metadata);\n\n// Build the parameters object.\nParameters parameters = new Parameters();\nparameters.setType(reportType);\nparameters.setGroupBys(dimensions);\nparameters.setFilters(filters);\nparameters.setMetrics(metrics);\n\n// Set parameters object in query.\nquery.setParams(parameters);\n\n// Build and set the schedule object.\nQuerySchedule schedule = new QuerySchedule();\nschedule.setFrequency(\"ONE_TIME\");\nquery.setSchedule(schedule);\n\n// Create the query.\nQuery queryResponse = service.queries().create(query).execute();\n\n// Log query creation.\nSystem.out.printf(\"Query %s was created.%n\", queryResponse.getQueryId());\n```\n\n### Python\n\n```python\n# Display name of the query to create.\ndisplay_name = display-name\n\n# The report type.\nreport_type = report-type\n\n# The advertisers and campaigns by which to filter report data.\nfiltered_advertiser_ids = [advertiser-id,...]\nfiltered_campaign_ids = [campaign-id,...]\n\n# The dimensions and metrics for the report.\ndimensions = [dimension,...]\nmetrics = [metric,...]\n\n# Build list of FilterPair objects.\nfilters = []\nif filtered_campaign_ids != None:\n filters.extend([\n {\"type\": \"FILTER_MEDIA_PLAN\", \"value\": id}\n for id in filtered_campaign_ids\n ])\nif filtered_advertiser_ids != None:\n filters.extend([\n {\"type\": \"FILTER_ADVERTISER\", \"value\": id}\n for id in filtered_advertiser_ids\n ])\n\n# Build query object.\nquery_obj = {\n \"metadata\": {\n \"title\": display_name,\n \"dataRange\": {\"range\": \"LAST_7_DAYS\"},\n \"format\": \"CSV\",\n },\n \"params\": {\n \"type\": report_type,\n \"groupBys\": dimensions,\n \"filters\": filters,\n \"metrics\": metrics,\n },\n \"schedule\": {\"frequency\": \"ONE_TIME\"}\n}\n\n# Create query object.\nquery_response = service.queries().create(body=query_obj).execute()\n\n# Print new query ID.\nprint(f'Query {query_response[\"queryId\"]} was created.')\n```\n\n### PHP\n\n```php\n// Display name of the query to create.\n$displayName = \u003cvar translate=\"no\"\u003edisplay-name\u003c/var\u003e;\n\n// The report type.\n$reportType = \u003cvar translate=\"no\"\u003ereport-type\u003c/var\u003e;\n\n // Advertiser ID and campaign ID by which to filter data.\n$advertiserIdFilters = array(\u003cvar translate=\"no\"\u003eadvertiser-id,...\u003c/var\u003e);\n$campaignIdFilters = array(\u003cvar translate=\"no\"\u003ecampaign-id,...\u003c/var\u003e);\n\n// The dimensions and metrics for the report.\n$dimensions = array(\u003cvar translate=\"no\"\u003edimension,...\u003c/var\u003e);\n$metrics = array(\u003cvar translate=\"no\"\u003emetric,...\u003c/var\u003e);\n\n// Build a list of filter pairs from given IDs.\n$filters = array();\nforeach ($advertiserIdFilters as $advertiserId) {\n $filterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n $filterPair-\u003esetType(\"FILTER_ADVERTISER\");\n $filterPair-\u003esetValue($advertiserId);\n array_push($filters, $filterPair);\n}\nforeach ($campaignIdFilters as $campaignId) {\n $filterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n $filterPair-\u003esetType(\"FILTER_MEDIA_PLAN\");\n $filterPair-\u003esetValue($campaignId);\n array_push($filters, $filterPair);\n}\n\n // Create the query structure.\n$query = new Google_Service_DoubleClickBidManager_Query();\n\n // Build and set the metadata object.\n$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();\n$metadata-\u003esetTitle($displayName);\n$metadata-\u003esetFormat(\"CSV\");\n\n$dataRange = new Google_Service_DoubleClickBidManager_DataRange();\n$dataRange-\u003esetRange(\"LAST_7_DAYS\");\n$metadata-\u003esetDataRange($dataRange);\n\n$query-\u003esetMetadata($metadata);\n\n // Build and set the parameters object.\n$parameters = new Google_Service_DoubleClickBidManager_Parameters();\n$parameters-\u003esetType($reportType);\n$parameters-\u003esetGroupBys($dimensions);\n$parameters-\u003esetFilters($filters);\n$parameters-\u003esetMetrics($metrics);\n$query-\u003esetParams($parameters);\n\n // Build and set the schedule object.\n$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();\n$schedule-\u003esetFrequency(\"ONE_TIME\");\n$query-\u003esetSchedule($schedule);\n\n// Call the API, creating the query.\n$queryResult = $this-\u003eservice-\u003equeries-\u003ecreate($query);\n\nprintf('Query %s was created.\u003cbr\u003e', $queryResult-\u003egetQueryId());\n```"]]