Reports: request

إدراج طلب تقرير في نظام إعداد التقارير تجربة ذلك الآن

الطلب

طلب 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 تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
  • "sold": تعرض مقاييس للمنتجات التي تم بيعها فقط
  • "advertised": تعرض مقاييس فقط للمنتجات التي تم الإعلان عنها في حملة Shopping والتي ربما تم بيعها أو لا
filters[].column.productReportPerspective string تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
  • "sold": تعرض مقاييس للمنتجات التي تم بيعها فقط
  • "advertised": تعرض مقاييس فقط للمنتجات التي تم الإعلان عنها في حملة Shopping والتي ربما تم بيعها أو لا
orderBy[].column.productReportPerspective string تعرض المقاييس لنوع معيّن من نشاط المنتج فقط. القيم المقبولة هي:
  • "sold": تعرض مقاييس للمنتجات التي تم بيعها فقط
  • "advertised": تعرض مقاييس فقط للمنتجات التي تم الإعلان عنها في حملة Shopping والتي ربما تم بيعها أو لا

الرد

في حال نجاح هذه الطريقة، سيتم عرض مورد التقارير في نص الاستجابة.

جرّب الآن

يمكنك استخدام "مستكشف واجهات برمجة التطبيقات" أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الردّ. ويمكنك بدلاً من ذلك تجربة مستقل Explorer (المستكشف):