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

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

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

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

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

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

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

اختيار كيان قائم بالإبلاغ

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

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

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

إذا كنت تستخدم إحدى مكتبات برامج واجهة برمجة التطبيقات للبيانات، ليست هناك حاجة إلى معالجة مسار عنوان URL للطلب يدويًا. توفِّر معظم برامج واجهة برمجة التطبيقات مَعلمة property تتوقع سلسلة في شكل properties/GA_PROPERTY_ID. الاطّلاع على دليل البدء السريع للحصول على أمثلة استخدام مكتبات العملاء.

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

لإنشاء مهمة تقرير، اتصل reportTasks.create باستخدام ReportTask كائن في الطلب. المعلمات التالية مطلوبة:

• reportDefinition الذي يصف تعريف التقرير المخصّص. هذه المعلمة بنية التقرير تشبه تعريف التقرير الذي تستخدمه الطرق الأساسية لإعداد التقارير.

مثال على طلب إنشاء "مهمة الإبلاغ":

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)، والتي يمكن استخدامها في الاستعلامات اللاحقة للحصول على حالة مهمة إعداد التقارير واسترداد والتقرير الناتج.

{
  "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 لتحديد الإبلاغ عن مهمة.

مثال:

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

يتم إرجاع حالة جاهزية مهمة تقرير في state حقل الاستجابة. بعد اكتمال عملية إنشاء التقرير تتغير حالة مهمة إعداد التقارير من CREATING إلى ACTIVE.

reportMetadata على معلومات عالية المستوى حول التقرير الذي تم إنشاؤه، مثل عدد الصفوف ومقدار رموز الحصة المميزة المحصَّلة.

{
  "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).

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

إذا كانت مهمة التقرير جاهزة، يتم عرض ردّ يحتوي على التقرير الذي تم إنشاؤه:

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}