أساسيات إعداد التقارير

باستخدام مهام التقارير، يمكنك بدء طلب غير متزامن يستغرق وقتًا طويلاً لإنشاء تقرير مخصّص لبيانات الأحداث في "إحصاءات 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 (مثل 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"
  }
}