--- id: "e0b1f5394d62599ea1f2" url: "https://www.xmcsl.cn/project/ocean-engine-api/%E8%87%AA%E5%AE%9A%E4%B9%89%E6%8A%A5%E8%A1%A8-1741387668314126.html" source_url: "https://open.oceanengine.com/labels/7/docs/1741387668314126?origin=left_nav" source_date: null checked_at: "2026-11-05T04:21:48.909937+00:00" status: "ready" check_scope: "structure_only; not a factual or human review" body_sha256: "0d0fdec5188f128f82180beae2ed80275bb2bd0f98801885632bd39e01abe7e6" --- # 自定义报表 — 巨量引擎 API # 自定义报表
关键信息详情
文档 ID1741387668314126
标签 ID7
原始文档[https://open.oceanengine.com/labels/7/docs/1741387668314126?origin=left_nav](https://open.oceanengine.com/labels/7/docs/1741387668314126?origin=left_nav)
接口标识report.custom.get
💡自定义报表是基于巨量引擎升级版对于数据报表提供新的接口能力，用户可以自由选择和组合指标和维度，以此定义数据报表的字段。相关指标和维度可通过 \[获取自定义报表可用维度和指标\](https://open.oceanengine.com/labels/7/docs/1755261744248832) 接口获取不同数据主题下的可用维度和指标。 自定义报表是基于巨量引擎升级版对于数据报表提供新的接口能力，您可以自由选择和组合指标和维度，以此定义数据报表的字段。 相关指标和维度可通过\[获取自定义报表可用维度和指标\](https://open.oceanengine.com/labels/7/docs/1755261744248832)接口获取不同数据主题下的可用维度和指标。例如，想要获取由起量带来的增量数据，需要在筛选项中上传 field=is\_boost &&values=1 GET \[https://api.oceanengine.com/open\_api/v3.0/report/custom/get/\](https://api.oceanengine.com/open\_api/v3.0/report/custom/get/) 🔍 可视化调试 📦 SDK下载 ## 接口说明 自定义报表是基于巨量引擎升级版对于数据报表提供新的接口能力，用户可以自由选择和组合指标和维度，以此定义数据报表的字段。相关指标和维度可通过 获取自定义报表可用维度和指标 接口获取不同数据主题下的可用维度和指标。 自定义报表是基于巨量引擎升级版对于数据报表提供新的接口能力，您可以自由选择和组合指标和维度，以此定义数据报表的字段。 相关指标和维度可通过获取自定义报表可用维度和指标接口获取不同数据主题下的可用维度和指标。例如，想要获取由起量带来的增量数据，需要在筛选项中上传 field=is\_boost &&values=1 #### 请求地址 https://api.oceanengine.com/open_api/v3.0/report/custom/get/可视化调试SDK下载MCP调用 #### 请求方法 GET #### Header 字段类型描述Access\-Token 必填string授权access\_token，可以通过【获取Access token】接口获取 #### 请求参数 字段类型描述advertiser\_id 必填number客户iddata\_topicstring数据主题，默认值：BASIC_DATA营销基础数据 枚举值： BASIC_DATA营销基础数据 QUERY_DATA搜索词数据 BIDWORD_DATA关键词数据 MATERIAL_DATA素材数据 PRODUCT_DATA产品数据 ONE_KEY_BOOST_DATA一键起量（巨量营销升级版） DMP_DATA人群包数据 VIDEO_DUARATION_DATA视频分秒数据 MATERIAL_BOOST_DATA 素材一键起量 STD_BASIC_DATA 标准投放\-基础报表 STD_MATERIAL_DATA 标准投放\-素材报表 STD_QUERY_DATA 标准投放\-搜索词数据 STD_BIDWORD_DATA 标准投放\-关键词数据 STD_DMP_DATA 标准投放\-人群包数据 STD_PRODUCT_DATA标准投放\-产品数据dimensions 必填string\[\]维度列表。 获取方式有2种：\- 调用API获取：可通过【获取自定义报表可用维度和指标】接口获取不同数据主题下的可用维度和指标 \- 通过营销平台直接生成参数：进入巨量营销升级版平台—>报表—>新建/编辑自定义报表—>API参数生成。获取到API参数生成后需在请求参数中手动添加对应的数据主题，否则将无法正确获取数据metrics 必填string\[\]指标列表 。 获取方式有2种：\- 调用API获取：可通过【获取自定义报表可用维度和指标】接口获取不同数据主题下的可用维度和指标 \- 通过营销平台直接生成参数：进入巨量营销升级版平台—>报表—>新建/编辑自定义报表—>API参数生成。该字段从前端自定义报表中获取，建议不要修改。获取到API参数生成后需在请求参数中手动添加对应的数据主题，否则将无法正确获取数据filtersobject\[\]过滤条件。 获取方式有2种：\- 调用API获取：可通过【获取自定义报表可用维度和指标】接口获取不同数据主题下的可用维度和指标 \- 通过营销平台直接生成参数：进入巨量营销升级版平台—>报表—>新建/编辑自定义报表—>API参数生成。该字段从前端自定义报表中获取，建议不要修改。获取到API参数生成后需在请求参数中手动添加对应的数据主题，否则将无法正确获取数据field 条件必填string过滤的消耗指标字段type 条件必填number字段类型。允许值：\- 1 \-固定枚举值 \- 2 \- 固定输入值 \- 3 \-数值类型operator 条件必填number处理方式。 允许值：\- 1 \-等于 \- 2 \-小于 \- 3\-小于等于 \- 4 \-大于 \- 5\-大于等于 \- 6\-不等于 \- 7\-包含 \- 8 \-不包含 \- 9\-范围查询 \- 10\-多个值匹配包含 \- 11 \-多个值匹配都要包含values 条件必填string\[\]过滤字段具体值start\_time 必填string开始时间。格式为：yyyy\-MM\-dd hh:mm:ss。例如：2025\-07\-07 00:00:00end\_time 必填string结束时间。格式为：yyyy\-MM\-dd hh:mm:ss。例如：2025\-07\-07 00:00:00order\_by 必填object\[\]排序fieldstring排序字段。字段必须在选中的metrics或dimensions中。其中metrics所有字段支持排序。dimensions是否排序请参考维度、指标说明。typestring排序类型 可选值:\- ASC: 升序 \- DESC: 降序 pagenumber页码。默认为1page\_sizenumber页面大小。默认为10，最大100 #### 请求示例 ### python ```python # coding=utf-8 import json import requests from six import string_types from six.moves.urllib.parse import urlencode, urlunparse # noqa ACCESS_TOKEN = "xxx" PATH = "/open_api/v3.0/report/custom/get/" def build_url(path, query=""): # type: (str, str) -> str """ Build request URL :param path: Request path :param query: Querystring :return: Request URL """ scheme, netloc = "https", "api.oceanengine.com" return urlunparse((scheme, netloc, path, "", query, "")) def get(json_str): # type: (str) -> dict """ Send GET request :param json_str: Args in JSON format :return: Response in JSON format """ args = json.loads(json_str) query_string = urlencode({k: v if isinstance(v, string_types) else json.dumps(v) for k, v in args.items()}) url = build_url(PATH, query_string) headers = { "Access-Token": ACCESS_TOKEN, } rsp = requests.get(url, headers=headers) return rsp.json() if __name__ == '__main__': dimensions_list = DIMENSIONS dimensions = json.dumps(dimensions_list) advertiser_id = ADVERTISER_ID metrics_list = METRICS metrics = json.dumps(metrics_list) field = FIELD type = TYPE operator = OPERATOR values_list = VALUES values = json.dumps(values_list) start_time = START_TIME end_time = END_TIME field = FIELD type = TYPE page = PAGE page_size = PAGE_SIZE # Args in JSON format my_args = "{\"dimensions\": %s, \"advertiser_id\": \"%s\", \"metrics\": %s, \"filters\": [{\"field\": \"%s\", \"type\": \"%s\", \"operator\": \"%s\", \"values\": %s}], \"start_time\": \"%s\", \"end_time\": \"%s\", \"order_by\": [{\"field\": \"%s\", \"type\": \"%s\"}], \"page\": \"%s\", \"page_size\": \"%s\"}" % (dimensions, advertiser_id, metrics, field, type, operator, values, start_time, end_time, field, type, page, page_size) print(get(my_args)) ``` ### java ```java import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; import okhttp3.*; import org.apache.http.client.utils.URIBuilder; import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; import java.net.URL; import java.util.List; import java.util.Map; import java.util.stream.Collectors; public class Demo { private static final String ACCESS_TOKEN = "xxx"; private static final String PATH = "/open_api/v3.0/report/custom/get/"; private static final ObjectMapper mapper = new ObjectMapper(); /** * Build request URL * * @param path Request path * @return Request URL */ private static String buildUrl(String path) throws URISyntaxException { URI uri = new URI("https", "api.oceanengine.com", path, "", ""); return uri.toString(); } /** * Send GET request * * @param jsonStr:Args in JSON format * @return Response in JSON format */ private static String get(String jsonStr) throws IOException, URISyntaxException { OkHttpClient client = new OkHttpClient().newBuilder().build(); URIBuilder ub = new URIBuilder(buildUrl(PATH)); Map< String, Object > map = mapper.readValue(jsonStr, Map.class); map.forEach((k, v) -> { try { ub.addParameter(k, v instanceof String ? (String) v : mapper.writeValueAsString(v)); } catch (JsonProcessingException e) { e.printStackTrace(); } }); URL url = ub.build().toURL(); Request request = new Request.Builder() .url(url) .method("GET", null) .addHeader("Access-Token", ACCESS_TOKEN) .build(); Response response = client.newCall(request).execute(); return response.body().string(); } public static void main(String[] args) throws IOException, URISyntaxException { List < String > dimensions_list = DIMENSIONS; String dimensions = mapper.writeValueAsString(dimensions_list); Long advertiser_id = ADVERTISER_ID; List < String > metrics_list = METRICS; String metrics = mapper.writeValueAsString(metrics_list); String field = FIELD; String type = TYPE; Long operator = OPERATOR; List < String > values_list = VALUES; String values = mapper.writeValueAsString(values_list); String start_time = START_TIME; String end_time = END_TIME; String field = FIELD; String type = TYPE; Long page = PAGE; Long page_size = PAGE_SIZE; // Args in JSON format String myArgs = String.format("{\"dimensions\": %s, \"advertiser_id\": \"%s\", \"metrics\": %s, \"filters\": [{\"field\": \"%s\", \"type\": \"%s\", \"operator\": \"%s\", \"values\": %s}], \"start_time\": \"%s\", \"end_time\": \"%s\", \"order_by\": [{\"field\": \"%s\", \"type\": \"%s\"}], \"page\": \"%s\", \"page_size\": \"%s\"}",dimensions, advertiser_id, metrics, field, type, operator, values, start_time, end_time, field, type, page, page_size); System.out.println(get(myArgs)); } } ``` ### php ```php $ACCESS_TOKEN = "xxx"; $PATH = "/open_api/v3.0/report/custom/get/"; /** * Build request URL * @param $path : Request path * @return string */ function build_url($path) { return "https://api.oceanengine.com" . $path; } /** * Send GET request * @param $json_str : Args in JSON format * @return bool|string : Response in JSON format */ function get($json_str) { global $ACCESS_TOKEN, $PATH; $curl = curl_init(); $args = json_decode($json_str, true); /* Values of querystring is also in JSON format */ foreach ($args as $key => $value) { $args[$key] = is_string($value) ? $value : json_encode($value); } $url = build_url($PATH) . "?" . http_build_query( $args ); curl_setopt_array($curl, array( CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Access-Token: " . $ACCESS_TOKEN, ), )); $response = curl_exec($curl); curl_close($curl); return $response; } $dimensions_list = DIMENSIONS; $dimensions = json_encode($dimensions_list); $advertiser_id = ADVERTISER_ID; $metrics_list = METRICS; $metrics = json_encode($metrics_list); $field = FIELD; $type = TYPE; $operator = OPERATOR; $values_list = VALUES; $values = json_encode($values_list); $start_time = START_TIME; $end_time = END_TIME; $field = FIELD; $type = TYPE; $page = PAGE; $page_size = PAGE_SIZE; /* Args in JSON format */ $my_args = sprintf("{\"dimensions\": %s, \"advertiser_id\": \"%s\", \"metrics\": %s, \"filters\": [{\"field\": \"%s\", \"type\": \"%s\", \"operator\": \"%s\", \"values\": %s}], \"start_time\": \"%s\", \"end_time\": \"%s\", \"order_by\": [{\"field\": \"%s\", \"type\": \"%s\"}], \"page\": \"%s\", \"page_size\": \"%s\"}", $dimensions, $advertiser_id, $metrics, $field, $type, $operator, $values, $start_time, $end_time, $field, $type, $page, $page_size); echo get($my_args); ``` ### curl ```curl curl --get -H "Access-Token:xxx" \ --data-urlencode "dimensions=[\"DIMENSIONS\"]" \ --data-urlencode "advertiser_id=ADVERTISER_ID" \ --data-urlencode "metrics=[\"METRICS\"]" \ --data-urlencode "filters=[{\"field\": \"FIELD\", \"type\": \"TYPE\", \"operator\": \"OPERATOR\", \"values\": [\"VALUES\"]}]" \ --data-urlencode "start_time=START_TIME" \ --data-urlencode "end_time=END_TIME" \ --data-urlencode "order_by=[{\"field\": \"FIELD\", \"type\": \"TYPE\"}]" \ --data-urlencode "page=PAGE" \ --data-urlencode "page_size=PAGE_SIZE" \ https://api.oceanengine.com/open_api/v3.0/report/custom/get/ ``` #### 应答字段 字段类型描述codenumber返回码,详见【附录-返回码】messagestring返回信息,详见【附录-返回码】dataobject返回数据rowsobject\[\]metricsdict\[string\]指标数据dimensionsdict\[string\]维度数据total\_metricsdict\[string\]指标汇总数据page\_infoobject分页信息pagenumber页码page\_sizenumber页面大小，即每页展示的数据量total\_numbernumber总数total\_pagenumber总页数request\_idstring请求的日志id，唯一标识一个请求 #### 应答示例 ```json HTTPS/1.1 200 OK { "code":0, "message":"OK", "request_id":"21312jklasjdlkajl312dasdas", "data":{ "page_info":{ "page":1, "page_size":10, "total_number":7, "total_page":1 }, "rows":[ { "dimensions":{ "cdp_project_id":"44444", "stat_time_hour":"2022-08-02 14:00 - 14:59" }, "metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } }, { "dimensions":{ "cdp_project_id":"33333", "stat_time_hour":"2022-08-02 15:00 - 15:59" }, "metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } }, { "dimensions":{ "cdp_project_id":"2222", "stat_time_hour":"2022-08-02 21:00 - 21:59" }, "metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } }, { "dimensions":{ "cdp_project_id":"2222", "stat_time_hour":"2022-08-02 21:00 - 21:59" }, "metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } }, { "dimensions":{ "cdp_project_id":"1111", "stat_time_hour":"2022-08-02 22:00 - 22:59" }, "metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } } ], "total_metrics":{ "click_cnt":"0", "conversion_cost":"0.00", "conversion_rate":"0.00", "convert_cnt":"0", "cpc_platform":"0.00", "cpm_platform":"0.00", "ctr":"0.00", "deep_convert_cnt":"0", "deep_convert_cost":"0.00", "deep_convert_rate":"0.00", "show_cnt":"0", "stat_cost":"0.00" } } } ``` ## 业务错误码 仅披露当前接口高频的参数校验报错，更多常见报错详见「返回码」文档