أساسيات إعداد التقارير

باستخدام مهام التقارير، يمكنك بدء طلب غير متزامن طويل الأمد لإنشاء تقرير مخصّص لبيانات الأحداث في "إحصاءات Google".

يمكن استخدام مورد مهمة التقرير الذي تم إنشاؤه من هذا الطلب للوصول إلى التقارير المخصّصة من قِبل جميع المستخدمين الذين لديهم إذن بالوصول للقراءة إلى موقعك على "إحصاءات Google".

سيتوفّر التقرير المخصّص لمدة 72 ساعة بعد أن يصبح جاهزًا. وبعد هذه الفترة، سيتم تلقائيًا حذف مورد مهمة التقرير المعني ومحتواه.

إنشاء مهمة تقرير

يستخدم الإصدار 1 من Google Analytics Data API نهجًا غير متزامن لإنشاء مهام التقارير. أولاً، يجب إرسال طلب إلى طريقة reportTasks.create لإنشاء مهمة تقرير. بعد ذلك، يتم استخدام طريقة reportTasks.query لاسترداد التقرير المخصّص الذي تم إنشاؤه.

بالإضافة إلى ذلك، يمكنك استخدام reportTasks.get لاسترداد البيانات الوصفية للإعدادات حول مهمة تقرير معيّنة و reportTasks.list لإدراج جميع مهام التقارير لموقع معيّن.

اختيار جهة إبلاغ

تتطلّب جميع طرق الإصدار الأول من Data API تحديد معرّف الموقع على "إحصاءات Google" داخل مسار طلب عنوان URL على شكل properties/GA_PROPERTY_ID، مثل:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

يتم إنشاء التقرير استنادًا إلى بيانات أحداث "إحصاءات Google" التي تم جمعها في الموقع المحدّد على "إحصاءات Google".

إذا كنت تستخدم إحدى مكتبات عملاء Data API، لن تحتاج إلى معالجة مسار عنوان URL للطلب يدويًا. توفّر معظم عملاء واجهة برمجة التطبيقات مَعلمة property تتوقّع سلسلة على شكل properties/GA_PROPERTY_ID. يمكنك الاطّلاع على دليل البدء السريع للحصول على أمثلة على استخدام مكتبات العملاء.

طلب إنشاء مهمة التقرير

لإنشاء مهمة تقرير، استخدِم طريقة reportTasks.create مع عنصر ReportTask في الطلب. يجب توفير المَعلمات التالية:

مثال على طلب إنشاء مهمة تقرير:

طلب HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

يحتوي ردّ طريقة reportTasks.create على اسم مهمة التقرير في حقل name (مثل properties/1234567/reportTasks/123)، والذي يمكن استخدامه في طلبات البحث اللاحقة للحصول على حالة مهمة التقرير واسترداد التقرير الناتج.

استجابة HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

الحصول على حالة استعداد مهمة التقرير

قد يستغرق إنشاء تقرير بعد طلب reportTasks.create عدة دقائق. يمكنك الحصول على حالة الاستعداد لمهمة تقرير من خلال طلب طريقة reportTasks.get.

استخدِم اسم مهمة التقرير (مثل properties/1234567/reportTasks/123) الذي تلقّيته من استجابة reportTasks.create لتحديد مهمة التقرير.

مثال:

طلب HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

يتم عرض حالة الاستعداد لمهمة إعداد تقرير في الحقل state ضمن الردّ. بعد اكتمال إنشاء التقرير، تتغيّر حالة مهمة التقرير من CREATING إلى ACTIVE.

يحتوي الحقل reportMetadata على معلومات عالية المستوى حول التقرير الذي تم إنشاؤه، مثل عدد الصفوف ومقدار الرموز المميّزة للحصة التي تم تحصيل رسوم مقابلها.

استجابة HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

يمكنك الحصول على حالة جميع مهام التقارير من خلال استدعاء الطريقة reportTasks.list.

استرداد التقرير الذي تم إنشاؤه

عند إنشاء مهمة التقرير باستخدام طريقة reportTasks.create، استدعِ طريقة reportTasks.query وحدِّد اسم مهمة التقرير (مثل properties/1234567/reportTasks/123).

طلب HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

إذا كانت مهمة التقرير جاهزة، يتم عرض ردّ يحتوي على التقرير الذي تم إنشاؤه:

استجابة HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}

الخطوات التالية