بيانات تقرير طلب البحث

توفّر طريقة reportData.query طريقة متزامنة لاسترداد بيانات التقارير. على عكس خدمة Reports العادية التي تنشئ تقارير مستندة إلى ملفات (CSV أو Excel)، تعرض هذه الطريقة بيانات JSON منظَّمة مباشرةً في الردّ. فهو يغنيك عن الحاجة إلى تحديد وإنشاء وحفظ مورد Report مسبقًا، ما يجعله مثاليًا لاسترداد البيانات واستكشافها في الوقت الفعلي.

نظرة عامة

يمكنك الاطّلاع على هذا الدليل للتعرّف على كيفية استخدام نقطة النهاية هذه للاستعلام عن بيانات تقارير "مدير الحملة 360".

إعداد الطلب

أنشئ ReportDataQueryRequest تحدّد فيه السمات والمقاييس والنطاق الزمني والفلاتر ومعايير الترتيب.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

عنصر DateRange يحدّد الفترة الزمنية للاستعلام. يمكن أن يكون ذلك نطاقًا زمنيًا مخصّصًا أو نطاقًا زمنيًا نسبيًا.

dimensionNames

قائمة بأسماء السمات العادية التي سيتم التجميع حسبها

metricNames

مطلوب. قائمة بأسماء المقاييس العادية المطلوب تضمينها

dimensionFilters

قائمة بكائنات DimensionValue المستخدَمة لفلترة بيانات التقرير. استخدِم هذا الخيار لحصر نتائج طلب البحث على قيم معيّنة لأحد المقاييس.

sortBys

إعدادات الترتيب للسمات أو المقاييس: يتضمّن كل إعداد اسم الحقل وترتيب الفرز.

maxResults

الحد الأقصى لعدد الصفوف المطلوب عرضها في كل صفحة (القيمة التلقائية: 100، الحد الأقصى: 1000).

تقسيم النتائج على عدّة صفحات

يتحكّم الحقل maxResults في عدد النتائج التي يتم عرضها في ردّ واحد. على سبيل المثال، إذا ضبطت maxResults على 10، ستعرض واجهة برمجة التطبيقات 10 نتائج كحد أقصى. من المحتمل أن تعرض واجهة برمجة التطبيقات أقل من 10 نتائج إذا كان عدد النتائج التي تتطابق مع طلبك أقل من 10.

إذا كانت تتوفّر نتائج إضافية، ستتضمّن الاستجابة nextPageToken. لاسترداد الصفحة التالية من النتائج، أرسِل الطلب نفسه مرة أخرى مع ضبط الحقل pageToken على هذا الرمز المميز. احتفِظ بجميع مَعلمات الطلب الأخرى كما هي.

إرسال الطلب

أرسِل طلب HTTP POST إلى نقطة النهاية reportdata/query:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

تأكَّد من مصادقة طلبك باستخدام بيانات اعتماد OAuth 2.0 العادية والنطاقات اللازمة. يمكنك الاطّلاع على تفاصيل حول طلبات التفويض للحصول على مزيد من المعلومات.

ردّ ناجح

يعرض طلب البحث الناجح استجابة HTTP 200 OK مع حِمل JSON يتضمّن columnHeaders وrows وtotalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

اسم وأنواع الحقول التي تم إرجاعها (DIMENSION أو METRIC)

rows

قائمة بعناصر ReportDataRow تحتوي على نتائج البحث. تتطابق قيم السلسلة في كل صف حسب الموضع مع columnHeaders.

totalRow

صف تجميعي واحد يمثّل مجموع كل المقاييس المطابقة. تكون حقول السمات والمقاييس التي لا يمكن جمعها (على سبيل المثال، مقاييس مدى الوصول مثل uniqueReachTotalReach) فارغة ("") في هذا الصف.

nextPageToken

رمز مميّز يُستخدَم في طلب لاحق لاسترداد الصفحة التالية إذا كانت هناك صفوف إضافية.

وقت الاستجابة والمهلات

بما أنّ هذه نقطة نهاية متزامنة، يتم تنفيذ طلبات البحث على الفور ويتم عرض البيانات مباشرةً في الرد (بما يصل إلى حدّ التقسيم على صفحات maxResults). يبلغ الحدّ الأقصى لوقت تنفيذ طلبات البحث 60 ثانية. إذا تجاوز استعلام هذا الحدّ، ستوقف واجهة برمجة التطبيقات العملية وتعرض الخطأ HTTP 503 Service Unavailable.

إذا ظهرت لك رسالة الخطأ هذه، حاوِل تضييق النطاق الزمني أو الفلاتر (مثل الفلترة حسب معلِنين أو حملات معيّنة) أو تقليل عدد السمات والمقاييس المطلوبة. بدلاً من ذلك، يمكنك تنفيذ Report باستخدام reports.run لإنشاء ملف تقرير قابل للتنزيل بشكل غير متزامن.

الحدود والقيود المفروضة على طلبات البحث

يفرض نقطة النهاية reportdata.query عدة قيود لضمان الحصول على ردود موثوقة. ويتم رفض الطلبات التي تنتهك هذه القيود مع الرد HTTP 400 Bad Request.

الحدود القصوى للنطاق الزمني

• بالنسبة إلى النطاقات الزمنية المخصّصة، يجب أن يكون startDate ضمن فترة توفّر البيانات لنوع بيانات التقرير المطلوب. لمعرفة التفاصيل، يُرجى الاطّلاع على مدى توفّر البيانات.

قيود المقاييس والسمات

• يجب تقديم مقياس واحد على الأقل في metricNames.
• يجب أن تكون المقاييس والسمات في القائمتَين metricNames وdimensionNames فريدة.
• لا يمكن استخدام المقاييس والسمات التي تحمل التصنيف تنزيل فقط في هذه الطلبات.

سقف الحصص

تستهلك الطلبات المُرسَلة إلى نقطة النهاية هذه الحصص التالية:

• الحد الأقصى لعدد الطلبات لكل مستخدم: 120 طلبًا في الدقيقة لكل مستخدم (طلبَين في الثانية)
• الحدّ الأقصى اليومي لكل مشروع: 10,000 طلب في اليوم لكل مشروع

ستتعذّر الطلبات التي تتجاوز هذه الحدود القصوى وسيتم عرض رسالة الخطأ HTTP 429 Too Many Requests. في حال تصفّح النتائج على صفحات، يتم احتساب كل طلب لصفحة جديدة (باستخدام المَعلمة pageToken) كطلب بحث منفصل ويتم استخدامه من هذه الحصة.