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

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

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

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

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

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

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

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

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

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

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

وإذا كنت تستخدم إحدى مكتبات عملاء واجهة برمجة التطبيقات للبيانات، لن تكون هناك حاجة لمعالجة مسار عنوان URL للطلب يدويًا. توفّر معظم برامج واجهة برمجة التطبيقات معلَمة property التي تتوقع سلسلة في شكل properties/GA4_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"
  }
}