إدراج طلب تقرير في نظام إعداد التقارير تجربة ذلك الآن
الطلب
طلب HTTP
POST https://www.googleapis.com/doubleclicksearch/v2/reports
التفويض
يتطلب هذا الطلب تفويضًا بالنطاق التالي:
النطاق |
---|
https://www.googleapis.com/auth/doubleclicksearch |
لمزيد من المعلومات، يُرجى الاطّلاع على صفحة المصادقة والتفويض.
نص الطلب
في نص الطلب، وفِّر البيانات بالبنية التالية:
{ "reportScope": { "agencyId": long, "advertiserId": long, "engineAccountId": long, "campaignId": long, "adGroupId": long, "keywordId": long, "adId": long }, "reportType": string, "columns": [ { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string } ], "timeRange": { "startDate": string, "endDate": string, "changedMetricsSinceTimestamp": datetime, "changedAttributesSinceTimestamp": datetime }, "filters": [ { "column": { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string }, "operator": string, "values": [ (value) ] } ], "orderBy": [ { "column": { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string }, "sortOrder": string } ], "includeDeletedEntities": boolean, "includeRemovedEntities": boolean, "verifySingleTimeZone": boolean, "downloadFormat": string, "statisticsCurrency": string, "startRow": integer, "rowCount": integer, "maxRowsPerFile": integer }
اسم الموقع | القيمة | الوصف | ملاحظات |
---|---|---|---|
reportScope |
object |
تقرير "النطاق" هو مجموعة من أرقام التعريف المستخدمة لتحديد أي مجموعة فرعية من الكيانات سيتم عرضها في التقرير. يجب إدخال سلسلة أرقام التعريف الكاملة من أدنى مستوى نطاق مطلوب من خلال الوكالة. | |
reportScope.agencyId |
long |
رقم تعريف وكالة DS. | |
reportScope.advertiserId |
long |
الرقم التعريفي للمعلِن في DS. | |
reportScope.engineAccountId |
long |
رقم تعريف حساب محرك البحث في DS. | |
reportScope.campaignId |
long |
رقم تعريف الحملة في DS. | |
reportScope.adGroupId |
long |
رقم تعريف المجموعة الإعلانية في DS. | |
reportScope.keywordId |
long |
رقم تعريف الكلمة الرئيسية في DS. | |
reportScope.adId |
long |
رقم تعريف الإعلان في DS. | |
reportType |
string |
تُحدِّد نوع الصفوف التي يتم عرضها في التقرير. على سبيل المثال، إذا حدّدت reportType: keyword ، سيحتوي كلّ صفّ في التقرير على بيانات عن كلمة رئيسية. يمكنك الاطّلاع على مرجع أنواع التقارير للأعمدة المتوفرة لكل نوع. |
|
columns[] |
list |
الأعمدة المراد تضمينها في التقرير. ويشمل ذلك كلاً من أعمدة DoubleClick Search والأعمدة المحفوظة. بالنسبة إلى أعمدة DoubleClick Search، يجب استخدام مَعلمة columnName فقط. أما بالنسبة إلى الأعمدة المحفوظة، فيجب استخدام المعلمة savedColumnName فقط. لا يمكن ضبط كلّ من columnName وsavedColumnName في الصف نفسه. الحد الأقصى لعدد الأعمدة في كل طلب هو 300 عمود. |
|
columns[].columnName |
string |
اسم عمود DoubleClick Search المراد تضمينه في التقرير | |
columns[].savedColumnName |
string |
اسم عمود محفوظ لتضمينه في التقرير. يجب أن يكون التقرير على مستوى المعلن أو على مستوى أقل، ويجب أن يكون هذا العمود المحفوظ قد سبق إنشاؤه في واجهة مستخدم DoubleClick Search. | |
columns[].headerText |
string |
النص المستخدَم لتحديد هذا العمود في ناتج التقرير يتم ضبطها تلقائيًا على columnName أو savedColumnName عند عدم تحديدها. ويمكن استخدامه لمنع التضارب بين أعمدة DoubleClick Search والأعمدة المحفوظة التي تحمل الاسم نفسه. |
|
columns[].startDate |
string |
التاريخ الشامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع endDate . |
|
columns[].endDate |
string |
يوم شامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع startDate . |
|
columns[].groupByColumn |
boolean |
التقرير المتزامن فقط. اضبط القيمة على "true " للتجميع حسب هذا العمود. وتكون القيمة التلقائية هي false . |
|
timeRange |
object |
إذا تم طلب المقاييس في أحد التقارير، سيتم استخدام هذه الوسيطة لتقييد المقاييس على نطاق زمني محدّد. | |
timeRange.startDate |
string |
التاريخ الشامل بتنسيق YYYY-MM-DD | |
timeRange.endDate |
string |
التاريخ الشامل بتنسيق YYYY-MM-DD | |
timeRange.changedMetricsSinceTimestamp |
datetime |
الطابع الزمني للتوقيت العالمي المنسَّق (UTC) الشامل بتنسيق RFC، على سبيل المثال 2013-07-16T10:16:23.555Z . اطّلِع على مراجع إضافية حول آلية عمل تقارير المقاييس التي تمّ تغييرها. |
|
timeRange.changedAttributesSinceTimestamp |
datetime |
الطابع الزمني للتوقيت العالمي المنسَّق (UTC) الشامل بتنسيق RFC، على سبيل المثال 2013-07-16T10:16:23.555Z . يمكنك الاطّلاع على مراجع إضافية حول آلية عمل تقارير السمات التي تم تغييرها. |
|
filters[] |
list |
قائمة بالفلاتر المطلوب تطبيقها على التقرير الحد الأقصى لعدد الفلاتر لكل طلب هو 300 فلتر. |
|
filters[].column |
nested object |
العمود المطلوب تنفيذ الفلتر عليه يمكن أن يكون عمود DoubleClick Search أو عمودًا محفوظًا. | |
filters[].column.columnName |
string |
اسم عمود DoubleClick Search المراد تضمينه في التقرير | |
filters[].column.savedColumnName |
string |
اسم عمود محفوظ لتضمينه في التقرير. يجب أن يكون التقرير على مستوى المعلِن أو نطاقه الأدنى، ويجب أن يكون هذا العمود المحفوظ قد سبق إنشاؤه في واجهة مستخدِم DoubleClick Search. | |
filters[].operator |
string |
عامل التشغيل المطلوب استخدامه في الفلتر. اطّلِع على مرجع الفلتر للحصول على قائمة بعوامل التشغيل المتاحة. | |
filters[].values[] |
list |
قائمة بالقيم المطلوب فلترة قيمة العمود وفقًا لها الحد الأقصى لعدد قيم الفلاتر لكل طلب هو 300. |
|
orderBy[] |
list |
التقرير المتزامن فقط. قائمة بالأعمدة والاتجاهات التي تحدّد الترتيب المطلوب تنفيذه في صفوف التقرير. الحدّ الأقصى لعدد الطلبات لكلّ طلب هو 300. |
|
orderBy[].column |
nested object |
العمود المطلوب إجراء الفرز عليه. يمكن أن يكون هذا عمودًا محددًا لـ DoubleClick Search أو عمودًا محفوظًا. | |
orderBy[].column.columnName |
string |
اسم عمود DoubleClick Search المراد تضمينه في التقرير | |
orderBy[].column.savedColumnName |
string |
اسم عمود محفوظ لتضمينه في التقرير. يجب أن يكون التقرير على مستوى المعلِن أو نطاقه الأدنى، ويجب أن يكون هذا العمود المحفوظ قد سبق إنشاؤه في واجهة مستخدِم DoubleClick Search. | |
orderBy[].sortOrder |
string |
اتجاه الترتيب، وهو إما ascending أو descending . |
|
includeDeletedEntities |
boolean |
يحدد ما إذا كان يجب تضمين الكيانات التي تمت إزالتها في التقرير. وتكون القيمة التلقائية هي false . متوقّفة نهائيًا، يُرجى استخدام includeRemovedEntities بدلاً منها. |
|
verifySingleTimeZone |
boolean |
في حال تحديد true ، لن يتم إنشاء التقرير إلّا إذا تم الحصول على جميع بيانات الإحصاءات المطلوبة من منطقة زمنية واحدة. وتكون القيمة التلقائية هي false . |
|
downloadFormat |
string |
التنسيق الذي يجب عرض التقرير فيه تتوفّر الميزة حاليًا csv أو tsv . |
|
statisticsCurrency |
string |
تحدّد هذه السمة العملة التي سيتم إرجاع الأموال بها. القيم المحتملة هي: usd أو agency (صالحة إذا كان التقرير على مستوى الوكالة أو مستوى أقل)، أو advertiser (صالحة إذا كان نطاق التقرير * للمعلِن أو أقل)، أو account (صالحة إذا كان التقرير على مستوى حساب محرّك البحث أو على مستوى أقل). |
|
startRow |
integer |
التقرير المتزامن فقط. فهرس الصف الأول المطلوب عرضه صفر. تتراوح القيم المقبولة بين 0 و50000 بشكل شامل. وتكون القيمة التلقائية هي 0 . |
|
rowCount |
integer |
التقرير المتزامن فقط. الحد الأقصى لعدد الصفوف المراد عرضها سيتم إسقاط صفوف إضافية. تتراوح القيم المقبولة بين 0 و10000 بشكل شامل. وتكون القيمة التلقائية هي 10000 . |
|
maxRowsPerFile |
integer |
التقرير غير المتزامن فقط الحد الأقصى لعدد الصفوف في كل ملف تقرير. يتم تقسيم التقرير الكبير إلى العديد من الملفات استنادًا إلى هذا الحقل. تتراوح القيم المقبولة بين 1000000 و100000000 بشكل شامل. |
|
includeRemovedEntities |
boolean |
يحدد ما إذا كان يجب تضمين الكيانات التي تمت إزالتها في التقرير. وتكون القيمة التلقائية هي false . |
|
columns[].customDimensionName |
string |
يعمل هذا الخيار على تقسيم التقرير حسب سمة مخصّصة. يجب أن يقع التقرير على نطاق معلن أو أقل، ويجب أن تكون السمة المخصّصة قد سبق إعدادها في DoubleClick Search. يكون اسم السمة المخصّصة، الذي يظهر في DoubleClick Search، حسّاسًا لحالة الأحرف. وإذا تم استخدامها في تقرير إحالات ناجحة، يتم عرض قيمة السمة المخصّصة المحدّدة للإحالة الناجحة المحدّدة، في حال ضبطها. لا يقسّم هذا العمود تقرير الإحالات الناجحة. |
|
columns[].platformSource |
string |
النظام الأساسي المستخدَم لتقديم بيانات للسمة المخصّصة. القيم المقبولة هي "Floodlight". | |
filters[].column.customDimensionName |
string |
يعمل هذا الخيار على تقسيم التقرير حسب سمة مخصّصة. يجب أن يقع التقرير على نطاق معلن أو أقل، ويجب أن تكون السمة المخصّصة قد سبق إعدادها في DoubleClick Search. يكون اسم السمة المخصّصة، الذي يظهر في DoubleClick Search، حسّاسًا لحالة الأحرف. وإذا تم استخدامها في تقرير إحالات ناجحة، يتم عرض قيمة السمة المخصّصة المحدّدة للإحالة الناجحة المحدّدة، في حال ضبطها. لا يقسّم هذا العمود تقرير الإحالات الناجحة. |
|
filters[].column.headerText |
string |
النص المستخدَم لتحديد هذا العمود في إخراج التقرير يتم ضبطها تلقائيًا على columnName أو savedColumnName عند عدم تحديدها. ويمكن استخدامه لمنع التعارضات بين أعمدة DoubleClick Search والأعمدة المحفوظة التي تحمل الاسم نفسه. |
|
filters[].column.startDate |
string |
التاريخ الشامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع endDate . |
|
filters[].column.endDate |
string |
يوم شامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع startDate . |
|
filters[].column.groupByColumn |
boolean |
التقرير المتزامن فقط. اضبط القيمة على true للتجميع حسب هذا العمود. وتكون القيمة التلقائية هي false . |
|
filters[].column.platformSource |
string |
النظام الأساسي المستخدَم لتقديم بيانات للسمة المخصّصة. القيم المقبولة هي "Floodlight". | |
orderBy[].column.customDimensionName |
string |
يعمل هذا الخيار على تقسيم التقرير حسب سمة مخصّصة. يجب أن يقع التقرير على نطاق معلن أو أقل، ويجب أن تكون السمة المخصّصة قد سبق إعدادها في DoubleClick Search. يكون اسم السمة المخصّصة، الذي يظهر في DoubleClick Search، حسّاسًا لحالة الأحرف. وإذا تم استخدامها في تقرير إحالات ناجحة، يتم عرض قيمة السمة المخصّصة المحدّدة للإحالة الناجحة المحدّدة، في حال ضبطها. لا يقسّم هذا العمود تقرير الإحالات الناجحة. |
|
orderBy[].column.headerText |
string |
النص المستخدَم لتحديد هذا العمود في إخراج التقرير يتم ضبطها تلقائيًا على columnName أو savedColumnName عند عدم تحديدها. ويمكن استخدامه لمنع التعارضات بين أعمدة DoubleClick Search والأعمدة المحفوظة التي تحمل الاسم نفسه. |
|
orderBy[].column.startDate |
string |
التاريخ الشامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع endDate . |
|
orderBy[].column.endDate |
string |
يوم شامل بتنسيق YYYY-MM-DD ويؤدي توفير هذا الحقل إلى إلغاء النطاق الزمني الإجمالي للتقرير لهذا العمود فقط. يجب تقديمها مع startDate . |
|
orderBy[].column.groupByColumn |
boolean |
التقرير المتزامن فقط. اضبط القيمة على true للتجميع حسب هذا العمود. وتكون القيمة التلقائية هي false . |
|
orderBy[].column.platformSource |
string |
النظام الأساسي المستخدَم لتقديم بيانات للسمة المخصّصة. القيم المقبولة هي "Floodlight". | |
columns[].customMetricName |
string |
اسم المقياس المخصّص المطلوب تضمينه في التقرير يجب أن يكون التقرير محصورًا بمعلن أو أقل، ويجب أن يكون قد سبق إعداد المقياس المخصّص في DoubleClick Search. يكون اسم المقياس المخصّص الذي يظهر في DoubleClick Search حسّاسًا لحالة الأحرف. | |
filters[].column.customMetricName |
string |
اسم المقياس المخصّص المطلوب تضمينه في التقرير يجب أن يكون التقرير محصورًا بمعلن أو أقل، ويجب أن يكون قد سبق إعداد المقياس المخصّص في DoubleClick Search. يكون اسم المقياس المخصّص الذي يظهر في DoubleClick Search حسّاسًا لحالة الأحرف. | |
orderBy[].column.customMetricName |
string |
اسم المقياس المخصّص المطلوب تضمينه في التقرير يجب أن يكون التقرير محصورًا بمعلن أو أقل، ويجب أن يكون قد سبق إعداد المقياس المخصّص في DoubleClick Search. يكون اسم المقياس المخصّص الذي يظهر في DoubleClick Search حسّاسًا لحالة الأحرف. | |
columns[].productReportPerspective |
string |
تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
|
|
filters[].column.productReportPerspective |
string |
تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
|
|
orderBy[].column.productReportPerspective |
string |
تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
|
الرد
في حال نجاح هذه الطريقة، سيتم عرض مورد التقارير في نص الاستجابة.
جرّب الآن
يمكنك استخدام "مستكشف واجهات برمجة التطبيقات" أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الردّ. ويمكنك بدلاً من ذلك تجربة مستقل Explorer (المستكشف):