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

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

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

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

إنشاء مهمة الإبلاغ

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

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

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

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

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