التقارير المقسّمة
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
لا تعرض Search Ads 360 API سوى بيانات مجمّعة ما لم تطلب بيانات أكثر تفصيلاً وتقسيمًا.
البيانات. على سبيل المثال، عمود النقرات في إحدى الكلمات الرئيسية
إجمالي عدد النقرات على كلمة رئيسية معيّنة خلال النطاق الزمني الذي تحدِّده.
| keywordText |
keywordLandingPage |
النقرات |
| بريمجات |
http://www.example.com |
6000 |
ولكن إذا طلبت تقريرًا عن الكلمات الرئيسية يتم تقسيمه حسب ربع السنة، فستحصل كل كلمة رئيسية
رؤية صف واحد لكل ربع سنة، وسيسرد عمود النقرات الإجماليات ربع السنوية.
| keywordText |
keywordLandingPage |
quarterStart |
quarterEnd |
النقرات |
| بريمجات |
http://www.example.com |
2012-01-01 |
2012-03-31 |
1000 |
| بريمجات |
http://www.example.com |
2012-04-01 |
2012-06-30 |
1000 |
| بريمجات |
http://www.example.com |
2012-07-01 |
2012-09-30 |
1000 |
| بريمجات |
http://www.example.com |
2012-10-01 |
2012-12-31 |
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
}
ملاحظة: يُرجى التعامل بحذر مع التواريخ. إذا كنت تطلب تقريرًا ربع سنوي، يُرجى التأكد من
timeRange للتقرير
على مدار ربع السنة بأكمله. وإلا ستحصل على نتائج جزئية فقط، مما قد يجعل
الأشخاص الذين يعتقدون أنّ هناك انخفاضًا كبيرًا في النقرات والأرباح وما إلى ذلك.
جارٍ طلب شرائح متعددة
يمكنك تضمين أكثر من عمود شريحة في أي طلب. يُرجى ملاحظة ما يلي:
-
في حال التقسيم حسب الأسبوع أو الشهر أو ربع السنة، نقترح تضمين كلٍّ من
عمودي البداية والنهاية في طلبك. على سبيل المثال، في التقرير ربع السنوي، قم بتضمين كليهما
وquarterStart وquarterEnd. بما في ذلك
ب يُخرج تاريخي البدء والانتهاء للفترة، مما سيساعد على التأكد من أنك
البيانات المضمنة لكل فترة كاملة.
-
لا يمكنك تضمين أنواع مختلفة من الشرائح المرتبطة بالوقت في الطلب نفسه.
على سبيل المثال، لا يمكنك التقسيم حسب ربع السنة والشهر في الطلب نفسه.
-
يمكن أن يزداد عدد الصفوف بشكل كبير مع كل مقطع إضافي.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة 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."]]
