اصول گزارش وظایف

با استفاده از وظایف گزارش، می‌توانید یک درخواست ناهمزمان طولانی مدت را برای ایجاد یک گزارش سفارشی از داده‌های رویداد Google Analytics خود شروع کنید.

منبع وظیفه گزارش تولید شده از این درخواست می‌تواند برای دسترسی به گزارش‌های سفارشی توسط همه کاربرانی که دسترسی خواندن به ویژگی Google Analytics شما را دارند، استفاده شود.

یک گزارش سفارشی‌سازی‌شده به مدت ۷۲ ساعت پس از آماده شدن در دسترس خواهد بود. پس از این مدت، منبع وظیفه گزارش مربوطه و محتوای آن به طور خودکار حذف می‌شوند.

ایجاد یک وظیفه گزارش

رابط برنامه‌نویسی کاربردی داده گوگل آنالیتیکس نسخه ۱ از یک رویکرد ناهمزمان برای ایجاد وظایف گزارش استفاده می‌کند. ابتدا، برای ایجاد یک وظیفه گزارش، درخواستی به متد reportTasks.create ضروری است. سپس، از متد reportTasks.query برای بازیابی گزارش سفارشی تولید شده استفاده می‌شود.

علاوه بر این، می‌توانید reportTasks.get برای بازیابی ابرداده‌های پیکربندی مربوط به یک وظیفه گزارش خاص و reportTasks.list برای فهرست کردن تمام وظایف گزارش برای یک ویژگی استفاده کنید.

انتخاب نهاد گزارشگر

تمام متدهای Data API نسخه ۱ نیاز دارند که شناسه ویژگی Google Analytics در مسیر درخواست URL به شکل properties/GA_PROPERTY_ID مشخص شود، مانند:

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

این گزارش بر اساس داده‌های رویداد گوگل آنالیتیکس که در ویژگی مشخص‌شده‌ی گوگل آنالیتیکس جمع‌آوری شده‌اند، تولید می‌شود.

اگر از یکی از کتابخانه‌های کلاینت Data API استفاده می‌کنید، نیازی به دستکاری دستی مسیر URL درخواست نیست. اکثر کلاینت‌های API یک پارامتر property ارائه می‌دهند که رشته‌ای به شکل properties/GA_PROPERTY_ID را دریافت می‌کند. برای مثال‌هایی از استفاده از کتابخانه‌های کلاینت، به راهنمای شروع سریع مراجعه کنید.

درخواست ایجاد وظیفه گزارش

برای ایجاد یک وظیفه گزارش، متد reportTasks.create را با استفاده از شیء ReportTask در یک درخواست فراخوانی کنید. پارامترهای زیر مورد نیاز هستند:

  • فیلد reportDefinition که تعریف یک گزارش سفارشی را شرح می‌دهد. ساختار این پارامتر مشابه تعریف گزارش مورد استفاده توسط روش‌های Core Reporting است.

نمونه درخواست ایجاد وظیفه گزارش:

درخواست 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 شامل نام Report Task در فیلد 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"
  }
}