أساسيات إعداد التقارير عن "مهام Google"

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

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

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

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

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

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

اختيار جهة إعداد التقارير

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

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

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

إذا كنت تستخدم إحدى مكتبات عميل Data API، ليس عليك تعديل مسار عنوان URL للطلب يدويًا. توفّر معظم برامج API 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 اسم ReportTask في الحقل name (مثل properties/1234567/reportTasks/123)، والذي يمكن استخدامه في الاستعلامات اللاحقة للحصول على حالة ReportTask واسترداد التقرير الناتج.

استجابة 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"
  }
}