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

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

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

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

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

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

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

اختيار كيان إعداد التقارير

تتطلّب جميع طرق Data API v1 تحديد معرّف موقع على "إحصاءات 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"
  }
}