Method: accounts.networkReport.generate

تُنشئ تقرير "شبكة AdMob" استنادًا إلى مواصفات التقرير المقدَّمة. لعرض نتيجة RPC للبث من جهة الخادم. ويتم عرض النتيجة في تسلسل من الردود.

طلب HTTP

POST https://admob.googleapis.com/v1/{parent=accounts/*}/networkReport:generate

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
parent

string

اسم مورد الحساب الذي سيتم إنشاء التقرير له. مثال: accounts/pub-9876543210987654

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "reportSpec": {
    object (NetworkReportSpec)
  }
}
الحقول
reportSpec

object (NetworkReportSpec)

مواصفات تقارير الشبكة.

نص الاستجابة

استجابة البث لتقرير "شبكة AdMob" حيث تحتوي الاستجابة الأولى على عنوان التقرير، ثم ساحة مشاركات الصفوف، وأخيرًا التذييل كرسالة الاستجابة الأخيرة.

مثال:

[{
  "header": {
    "dateRange": {
      "startDate": {"year": 2018, "month": 9, "day": 1},
      "endDate": {"year": 2018, "month": 9, "day": 1}
    },
    "localizationSettings": {
      "currencyCode": "USD",
      "languageCode": "en-US"
    }
  }
},
{
  "row": {
    "dimensionValues": {
      "DATE": {"value": "20180918"},
      "APP": {
        "value": "ca-app-pub-8123415297019784~1001342552",
         displayLabel: "My app name!"
      }
    },
    "metricValues": {
      "ESTIMATED_EARNINGS": {"microsValue": 6500000}
    }
  }
},
{
  "footer": {"matchingRowCount": 1}
}]

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{

  // Union field payload can be only one of the following:
  "header": {
    object (ReportHeader)
  },
  "row": {
    object (ReportRow)
  },
  "footer": {
    object (ReportFooter)
  }
  // End of list of possible types for union field payload.
}
الحقول
حقل الاتحاد payload تحتوي كل رسالة استجابة للتدفق على نوع واحد من الحمولة. يمكن أن تكون السمة "payload" واحدة فقط مما يلي:
header

object (ReportHeader)

إعدادات إنشاء التقارير التي تصف محتوى التقرير، مثل النطاق الزمني للتقرير وإعدادات الأقلمة
row

object (ReportRow)

بيانات التقرير الفعلية.
footer

object (ReportFooter)

معلومات إضافية عن التقرير الذي تم إنشاؤه، مثل التحذيرات المتعلّقة بالبيانات

نطاقات التفويض

يتطلب استخدام أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/admob.readonly
  • https://www.googleapis.com/auth/admob.report

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

NetworkReportSpec

مواصفات إنشاء تقرير شبكة AdMob. على سبيل المثال، يمكن أن تظهر مواصفات الحصول على النقرات والأرباح المقدَّرة للبلدان "الولايات المتحدة" و"الصين" فقط على النحو التالي:

{
  'dateRange': {
    'startDate': {'year': 2021, 'month': 9, 'day': 1},
    'endDate': {'year': 2021, 'month': 9, 'day': 30}
  },
  'dimensions': ['DATE', 'APP', 'COUNTRY'],
  'metrics': ['CLICKS', 'ESTIMATED_EARNINGS'],
  'dimensionFilters': [
    {
      'dimension': 'COUNTRY',
      'matchesAny': {'values': [{'value': 'US', 'value': 'CN'}]}
    }
  ],
  'sortConditions': [
    {'dimension':'APP', order: 'ASCENDING'},
    {'metric':'CLICKS', order: 'DESCENDING'}
  ],
  'localizationSettings': {
    'currencyCode': 'USD',
    'languageCode': 'en-US'
  }
}

لفهم الأمر بشكل أفضل، يمكنك معالجة المواصفات السابقة مثل لغة الاستعلامات البنيوية (SQL) الزائفة التالية:

SELECT DATE, APP, COUNTRY, CLICKS, ESTIMATED_EARNINGS
FROM NETWORK_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
    AND COUNTRY IN ('US', 'CN')
GROUP BY DATE, APP, COUNTRY
ORDER BY APP ASC, CLICKS DESC;
تمثيل JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "dimensions": [
    enum (Dimension)
  ],
  "metrics": [
    enum (Metric)
  ],
  "dimensionFilters": [
    {
      object (DimensionFilter)
    }
  ],
  "sortConditions": [
    {
      object (SortCondition)
    }
  ],
  "localizationSettings": {
    object (LocalizationSettings)
  },
  "maxReportRows": integer,
  "timeZone": string
}
الحقول
dateRange

object (DateRange)

النطاق الزمني الذي تم إنشاء التقرير له.
dimensions[]

enum (Dimension)

قائمة أبعاد التقرير وتحدِّد مجموعة قيم هذه السمات صف التقرير. وفي حال عدم تحديد أي سمات، يعرض التقرير صفًا واحدًا من المقاييس المطلوبة للحساب بالكامل.
metrics[]

enum (Metric)

قائمة مقاييس التقرير يجب أن يحدّد التقرير مقياسًا واحدًا على الأقل.
dimensionFilters[]

object (DimensionFilter)

تصف صفوف التقرير المطلوب مطابقتها استنادًا إلى قيم أبعادها.
sortConditions[]

object (SortCondition)

تصف طريقة ترتيب صفوف التقرير. يحدد ترتيب الشرط في القائمة أسبقية، فكلما كان الشرط مبكرًا، كانت أسبقية أعلى. إذا لم يتم تحديد شروط فرز، سيكون ترتيب الصفوف غير محدد.
localizationSettings

object (LocalizationSettings)

إعدادات الترجمة الخاصة بالتقرير.
maxReportRows

integer

الحد الأقصى لعدد صفوف بيانات التقرير المطلوب عرضها. في حال عدم ضبط القيمة، تعرِض واجهة برمجة التطبيقات أكبر عدد ممكن من الصفوف، بما يصل إلى 100000. القيم المقبولة هي 1-100000، ضمنًا. تعرض القيم الأكبر من 100000 خطأ.
timeZone

string

المنطقة الزمنية للتقرير. تقبل قيم اسم IANA TZ، مثل "America/Los_Angeles". في حال عدم تحديد أي منطقة زمنية، يسري الإعداد التلقائي للحساب. تحقّق من القيمة التلقائية من خلال إجراء "الحصول على الحساب".

تحذير: القيمة "America/Los_Angeles" هي القيمة الوحيدة المتاحة في الوقت الحالي.

السمة

أبعاد تقرير الشبكة. السمات هي سمات بيانات يتم تقسيمها أو تحسينها حسب سمات معيّنة، مثل شكل الإعلان أو وسيط عرض الإعلان الذي تمت مشاهدة الإعلان عليه.

عمليات التعداد
DIMENSION_UNSPECIFIED القيمة التلقائية لحقل لم يتم تحديده. يُرجى عدم الاستخدام.
DATE تاريخ بالتنسيق YYYYMMDD (على سبيل المثال، "20210701"). يمكن للطلبات تحديد بُعد لمرة واحدة على الأكثر.
MONTH شهر بالتنسيق YYYYMM (على سبيل المثال، "202107"). يمكن للطلبات تحديد بُعد لمرة واحدة على الأكثر.
WEEK تاريخ أول يوم من الأسبوع بالتنسيق YYYYMMDD (على سبيل المثال، "20210701"). يمكن للطلبات تحديد بُعد لمرة واحدة على الأكثر.
AD_UNIT المعرّف الفريد للوحدة الإعلانية (على سبيل المثال، "ca-app-pub-1234/1234"). إذا تم تحديد بُعد AD_UNIT، يتم تضمين APP تلقائيًا.
APP المعرّف الفريد لتطبيق متوافق مع الأجهزة الجوّالة (على سبيل المثال، "ca-app-pub-1234~1234").
AD_TYPE

نوع الإعلان (على سبيل المثال، "نص" أو "صورة")، إحدى سمات عرض الإعلان.

تحذير: السمة غير متوافقة مع مقاييس AD_REQUESTS وMATCH_RATE وIMPRESSION_RPM.
COUNTRY رمز بلد CLDR للمكان الذي تحدث فيه مشاهدات/نقرات الإعلان (على سبيل المثال، "US" أو "FR"). هذا أحد جوانب الموقع الجغرافي.
FORMAT شكل الوحدة الإعلانية (على سبيل المثال، "بانر"، "إعلان مدمج مع المحتوى")، سمة عرض الإعلان.
PLATFORM النظام الأساسي للتطبيق المتوافق مع الأجهزة الجوّالة (على سبيل المثال، "Android" أو "iOS").
MOBILE_OS_VERSION إصدار نظام تشغيل الأجهزة الجوّالة، مثل "iOS 13.5.1".
GMA_SDK_VERSION إصدار حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، مثل "iOS 7.62.0".
APP_VERSION_NAME بالنسبة إلى نظام التشغيل Android، يمكن العثور على اسم إصدار التطبيق في versionName في PackageInfo. في نظام التشغيل iOS، يمكن العثور على اسم إصدار التطبيق في CFBundleShortVersionString.
SERVING_RESTRICTION وضع التقييد لعرض الإعلانات (مثل "الإعلانات غير المخصّصة").

المقياس

مقاييس تقرير الشبكة. المقاييس عبارة عن قياسات كمّية تشير إلى مستوى أداء النشاط التجاري للناشر. ويتمّ تجميعها من أحداث الإعلانات الفردية وتجميعها حسب سمات التقرير. تكون قيمة المقياس إما عددًا صحيحًا أو عددًا عشريًا (بدون تقريب).

عمليات التعداد
METRIC_UNSPECIFIED القيمة التلقائية لحقل لم يتم تحديده. يُرجى عدم الاستخدام.
AD_REQUESTS

عدد طلبات الإعلان. يجب أن تكون القيمة عددًا صحيحًا.

تحذير: المقياس غير متوافق مع السمة AD_TYPE.
CLICKS عدد المرات التي ينقر فيها المستخدم على إعلان. يجب أن تكون القيمة عددًا صحيحًا.
ESTIMATED_EARNINGS الأرباح المقدّرة لناشر AdMob. يتم تحديد وحدة العملة (الدولار الأمريكي أو اليورو أو غير ذلك) الخاصة بمقاييس الأرباح من خلال إعدادات الأقلمة. المبلغ بالمايكرو. على سبيل المثال، سيتم تمثيل 6.50 دولار أمريكي على النحو التالي: 6500000.
IMPRESSIONS إجمالي عدد الإعلانات المعروضة للمستخدمين. يجب أن تكون القيمة عددًا صحيحًا.
IMPRESSION_CTR نسبة النقرات إلى مرات الظهور. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية).
IMPRESSION_RPM

الأرباح المقدَّرة لكل ألف مرة ظهور للإعلان. يجب أن تكون القيمة بالمايكرو. على سبيل المثال، سيتم تمثيل 1.03 دولار أمريكي على النحو التالي: 1030000. يعادل التكلفة الفعلية لكل ألف ظهور في واجهة مستخدم AdMob.

تحذير: المقياس غير متوافق مع السمة AD_TYPE.
MATCHED_REQUESTS عدد مرّات عرض الإعلانات استجابةً للطلب. يجب أن تكون القيمة عددًا صحيحًا.
MATCH_RATE

نسبة طلبات الإعلان المطابقة مقارنةً بإجمالي طلبات الإعلان. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية).

تحذير: المقياس غير متوافق مع السمة AD_TYPE.
SHOW_RATE نسبة الإعلانات المعروضة مقابل الإعلانات التي تم عرضها، وتُعرف باسم مرات الظهور / الطلبات المطابقة. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية).

DimensionFilter

تصف صفوف التقرير المطلوب مطابقتها استنادًا إلى قيم أبعادها.

تمثيل JSON 
{
  "dimension": enum (Dimension),

  // Union field operator can be only one of the following:
  "matchesAny": {
    object (StringList)
  }
  // End of list of possible types for union field operator.
}
الحقول
dimension

enum (Dimension)

يتيح هذا الخيار معيار الفلتر على السمة المحدّدة.
حقل الاتحاد operator عامل تشغيل الفلتر الذي سيتم تطبيقه. يمكن أن تكون السمة "operator" واحدة فقط مما يلي:
matchesAny

object (StringList)

يطابق صفًا إذا كانت قيمته للسمة المحدّدة تقع في إحدى القيم المحدّدة في هذا الشرط.

SortCondition

اتجاه الفرز الذي سيتم تطبيقه على سمة أو مقياس.

تمثيل JSON 
{
  "order": enum (SortOrder),

  // Union field sort_on can be only one of the following:
  "dimension": enum (Dimension),
  "metric": enum (Metric)
  // End of list of possible types for union field sort_on.
}
الحقول
order

enum (SortOrder)

ترتيب ترتيب السمة أو المقياس
حقل الاتحاد sort_on تحدد القيم التي يجب الترتيب عليها. يمكن أن تكون السمة "sort_on" واحدة فقط مما يلي:
dimension

enum (Dimension)

الترتيب حسب السمة المحدّدة
metric

enum (Metric)

الترتيب حسب المقياس المحدَّد.