مبانی وظایف را گزارش دهید

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

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

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

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

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

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

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

تمام متدهای 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 را دریافت می‌کند. برای مثال‌هایی از استفاده از کتابخانه‌های کلاینت، به راهنمای شروع سریع مراجعه کنید.

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

برای ایجاد یک Report Task، متد 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 )، که می‌تواند در پرس‌وجوهای بعدی برای به دست آوردن وضعیت یک Report Task و بازیابی گزارش حاصل استفاده شود.

پاسخ 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 ، وضعیت آمادگی برای یک Report Task را بدست آورید.

از نام Report Task (مانند properties/1234567/reportTasks/123 ) که از پاسخ reportTasks.create دریافت کرده‌اید، برای تعیین Report Task استفاده کنید.

مثال:

درخواست HTTP 

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

وضعیت آمادگی برای یک Report Task در فیلد state پاسخ برگردانده می‌شود. پس از تکمیل تولید گزارش، وضعیت Report Task از 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
  }
}

شما می‌توانید وضعیت تمام وظایف گزارش (Report Tasks) را با فراخوانی متد reportTasks.list به دست آورید.

بازیابی گزارش تولید شده

پس از ایجاد Report Task ایجاد شده با استفاده از متد reportTasks.create ، متد reportTasks.query را فراخوانی کرده و نام Report Task را مشخص کنید (مانند 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"
  }
}