أساسيات إعداد التقارير عن "مهام 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"
  }
}