باستخدام مهام التقارير، يمكنك بدء طلب غير متزامن طويل الأمد لإنشاء تقرير مخصّص لبيانات أحداث "إحصاءات 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
في الطلب. المَعلمات التالية مطلوبة:
reportDefinition
يصف تعريف التقرير المخصّص. ويشبه بنية هذه المعلَمة تعريف التقرير الذي تستخدمه طرق إعداد التقارير الأساسية.
مثال على طلب إنشاء مهمة إعداد تقرير:
طلب 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"
}
}