گزارش های بخش بندی شده
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
API جدید Search Ads 360 Reporting اکنون در دسترس است. API جدید انعطاف‌پذیری بیشتری برای ایجاد گزارش‌های سفارشی و ادغام داده‌ها در برنامه‌ها و فرآیندهای گزارش‌دهی شما فراهم می‌کند. درباره انتقال و استفاده از
Search Ads 360 Reporting API جدید بیشتر بیاموزید.
Search Ads 360 API فقط داده‌های جمع‌آوری شده را برمی‌گرداند، مگر اینکه داده‌های دقیق‌تر و بخش‌بندی شده را درخواست کنید. برای مثال، ستون کلیک‌ها در گزارش کلمه کلیدی ، تعداد کل کلیک‌های روی یک کلمه کلیدی را در بازه زمانی که شما مشخص کرده‌اید، فهرست می‌کند.
| کلمه کلیدی متن | کلمه کلیدی LandingPage | کلیک می کند |
|---|
| ویجت ها | http://www.example.com | 6000 |
اما اگر یک گزارش کلمه کلیدی را درخواست کنید که به سه ماه تقسیم شود، برای هر کلمه کلیدی یک ردیف برای هر سه ماهه خواهید دید و ستون کلیک ها مجموع سه ماهه را فهرست می کند.
| کلمه کلیدی متن | کلمه کلیدی LandingPage | یک چهارم شروع | پایان سه ماهه | کلیک می کند |
|---|
| ویجت ها | http://www.example.com | 01-01-2012 | 31/03/2012 | 1000 |
| ویجت ها | http://www.example.com | 01/04/2012 | 30/06/2012 | 1000 |
| ویجت ها | http://www.example.com | 01/07/2012 | 30/09/2012 | 1000 |
| ویجت ها | http://www.example.com | 01-10-2012 | 31-12-2012 | 3000 |
توجه داشته باشید که یک گزارش بخش‌بندی شده تنها در صورتی یک ردیف را برمی‌گرداند که داده‌های یک بخش در دسترس باشد. به عنوان مثال، در گزارش کلمه کلیدی با ستون floodlightActivity ، اگر هیچ معیاری برای محدوده تاریخ گزارش به آن نسبت داده نشود، یک جفت فعالیت کلمه کلیدی و Floodlight در گزارش ظاهر نمی شود.
برخی از بخش ها با ستون های خاص ناسازگار هستند
برخی از بخش ها ممکن است باعث شوند که ستون های خاصی داده های نامعتبر را برگردانند. به عنوان مثال، تقسیم بندی بر اساس floodlightActivity تنها در صورتی معنادار است که ستون هایی را که داده های Floodlight را گزارش می کنند، مانند dfaActions ، dfaRevenue ، dfaTransactions و dfaWeightedActions اضافه کنید. انواع دیگر ستون‌های تبدیل (مانند adWordsConversions )، یا ستون‌هایی که معیارهای موتور را گزارش می‌کنند (مانند کلیک‌ها و نمایش‌ها)، حاوی داده‌های گزارش‌شده توسط Floodlight نیستند، بنابراین اگر گزارشی را بر اساس floodlightActivity تقسیم‌بندی کنید، مقادیر نامعتبر را برمی‌گردانند.
نحوه درخواست گزارش بخش بندی شده
برای درخواست یک گزارش بخش‌بندی شده، ستونی را وارد کنید که segment به عنوان رفتار آن در مرجع انواع گزارش‌ها فهرست می‌کند.
درخواست ناهمزمان زیر برای یک گزارش کلمه کلیدی است که بر اساس سه ماهه تقسیم شده است. ستون کلیک‌ها در هر سطر شامل تعداد کل کلیک‌های فصل است:
{
"reportScope": {
"agencyId": "20700000000000123", // Replace with your IDs
"advertiserId": "2170000012345" // Replace with your IDs
},
"reportType": "keyword",
"columns": [
{ "columnName": "campaignId" },
{ "columnName": "keywordText" },
{ "columnName": "keywordLandingPage" },
{ "columnName": "quarterStart" },
{ "columnName": "quarterEnd" },
{ "columnName": "clicks" },
]
"timeRange" : {
"startDate" : "2012-01-01",
"endDate" : "2012-12-31"
},
"downloadFormat": "csv",
"maxRowsPerFile": 5000000,
"statisticsCurrency": "agency",
"verifySingleTimeZone": false,
"includeRemovedEntities": false
}
توجه : مراقب خرما باشید. اگر درخواست گزارش سه ماهه دارید، مطمئن شوید که
محدوده زمانی گزارش شامل کل سه ماهه باشد. در غیر این صورت، فقط نتایج جزئی دریافت خواهید کرد، که ممکن است باعث شود مردم فکر کنند کلیک ها، درآمد و غیره به شدت کاهش یافته است.
درخواست چندین بخش
شما می توانید بیش از یک ستون بخش را در یک درخواست قرار دهید. به موارد زیر توجه کنید:
اگر بر اساس هفته، ماه یا سه ماهه تقسیم بندی می کنید، توصیه می کنیم هر دو ستون شروع و پایان را در درخواست خود قرار دهید. به عنوان مثال، در یک گزارش فصلی، هر دو ستون quarterStart و quarterEnd را در نظر بگیرید. گنجاندن هر دوی این ستون‌ها، تاریخ شروع و پایان دوره را نشان می‌دهد، که به تأیید اینکه داده‌های هر دوره کامل را وارد کرده‌اید، کمک می‌کند.
شما نمی توانید انواع مختلف بخش های مربوط به زمان را در یک درخواست قرار دهید. به عنوان مثال، شما نمی توانید در یک درخواست واحد بر اساس سه ماهه و ماه تقسیم بندی کنید.
تعداد سطرها می تواند با هر بخش اضافی به صورت تصاعدی افزایش یابد.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe new Search Ads 360 Reporting API offers greater flexibility for creating custom reports and integrating data into your workflows.\u003c/p\u003e\n"],["\u003cp\u003eThe API provides aggregated data by default, but you can request segmented data for a more granular view, such as segmenting by quarter to see quarterly click totals.\u003c/p\u003e\n"],["\u003cp\u003eSome segments are incompatible with certain columns, and including multiple segments can significantly increase the number of rows in your reports.\u003c/p\u003e\n"],["\u003cp\u003eWhen requesting segmented reports, ensure the time range covers the entire segment period for accurate results, and be mindful of potential data inconsistencies when combining segments with specific columns.\u003c/p\u003e\n"],["\u003cp\u003eYou can request segmented reports by including columns with "segment" behavior, as demonstrated in the provided code example for a keyword report segmented by quarter.\u003c/p\u003e\n"]]],["The new Search Ads 360 Reporting API allows for building custom reports and integrating data. Segmented reports show detailed data, with each segment (e.g., quarter) receiving its own row and totals. Rows appear only if data exists for the segment. Certain segments are incompatible with specific columns, yielding invalid data. To request a segmented report include a column listing `segment` as it's behavior, and when requesting time-related segments, ensure that the date range encompasses the full period. The use of multiple segments in a report is possible but they can not be time related.\n"],null,["# Segmented Reports\n\nThe new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the [new Search Ads 360 Reporting\nAPI](https://developers.google.com/search-ads/reporting/overview).\n\n\nThe Search Ads 360 API returns only aggregated data unless you request more detailed, segmented\ndata. For example, the clicks column in a [keyword\nreport](/search-ads/v2/report-types/keyword) lists the total number of clicks on a keyword during the time range you specify.\n\n| keywordText | keywordLandingPage | clicks |\n|-------------|------------------------|--------|\n| widgets | http://www.example.com | 6000 |\n\nBut if you request a keyword report that segments by quarter, for each keyword you'll\nsee one row for each quarter, and the clicks column will list the quarterly totals. \n\n| keywordText | keywordLandingPage | quarterStart | quarterEnd | clicks |\n|-------------|------------------------|--------------|------------|--------|\n| widgets | http://www.example.com | 2012-01-01 | 2012-03-31 | 1000 |\n| widgets | http://www.example.com | 2012-04-01 | 2012-06-30 | 1000 |\n| widgets | http://www.example.com | 2012-07-01 | 2012-09-30 | 1000 |\n| widgets | http://www.example.com | 2012-10-01 | 2012-12-31 | 3000 |\n\nNote that a segmented report returns a row only if data is available for a segment.\nFor example, in a keyword report with the `floodlightActivity` column, a keyword and\nFloodlight activity pair will not appear in the report if there are no metrics attributed\nto it for the report date range.\n\n### Some segments are incompatible with specific columns\n\nSome segments may cause specific columns to return invalid data. For example, segmenting by\n`floodlightActivity` is meaningful only if you include columns that report Floodlight\ndata, such as `dfaActions`, `dfaRevenue`, `dfaTransactions`,\nand `dfaWeightedActions`. Other types of conversion columns (such as\n`adWordsConversions`), or columns that report engine metrics (such as clicks and\nimpressions), don't contain data reported by Floodlight, so they return invalid values if you\nsegment a report by `floodlightActivity`.\n\n### How to request a segmented report\n\nTo request a segmented report, include a column that lists `segment` as its behavior in the [Types of Reports](/search-ads/v2/report-types) reference.\n\nThe following asynchronous request is for a keyword report segmented by quarter. The\nclicks column in each row will contain the total number of clicks for the quarter: \n\n```\n{\n \"reportScope\": {\n \"agencyId\": \"20700000000000123\", // Replace with your IDs\n \"advertiserId\": \"2170000012345\" // Replace with your IDs\n },\n \"reportType\": \"keyword\",\n\n \"columns\": [\n { \"columnName\": \"campaignId\" },\n { \"columnName\": \"keywordText\" },\n { \"columnName\": \"keywordLandingPage\" },\n\n { \"columnName\": \"quarterStart\" },\n { \"columnName\": \"quarterEnd\" },\n { \"columnName\": \"clicks\" },\n ]\n \"timeRange\" : {\n \"startDate\" : \"2012-01-01\",\n \"endDate\" : \"2012-12-31\"\n },\n \"downloadFormat\": \"csv\",\n \"maxRowsPerFile\": 5000000,\n \"statisticsCurrency\": \"agency\",\n \"verifySingleTimeZone\": false,\n \"includeRemovedEntities\": false\n}\n \n``` \n**Note** : Be careful with dates. If you're requesting a quarterly report, make sure that the report's [timeRange](/search-ads/v2/reference/reports#request.timeRange) includes the entire quarter. Otherwise you'll get only partial results, which might make people think there's been a drastic reduction in clicks, revenue, and so on.\n\nRequesting multiple segments\n----------------------------\n\nYou can include more than one segment column in a request. Note the following:\n\n- If you segment by week, month, or quarter, we recommend that you include both the\n start and end columns in your request. For example, in a quarterly report, include both\n the `quarterStart` and `quarterEnd` columns. Including both of these\n columns will output the period's start and end dates, which will help confirm that you've\n included data for each full period.\n\n- You cannot include different types of time-related segments in the same request.\n For example, you cannot segment by quarter and month in the same request.\n\n- The number of rows could increase exponentially with each additional segment."]]
