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

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

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

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

یک کار گزارش ایجاد کنید

Google Analytics Data API v1 از یک رویکرد ناهمزمان برای ایجاد گزارش وظایف استفاده می کند. ابتدا یک درخواست به متد reportTasks.create برای ایجاد یک Report Task ضروری است. سپس از روش reportTasks.query برای بازیابی گزارش سفارشی تولید شده استفاده می شود.

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

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

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

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

گزارش بر اساس داده‌های رویداد Google Analytics جمع‌آوری‌شده در ویژگی Google Analytics مشخص شده ایجاد می‌شود.

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

ایجاد گزارش کار را درخواست کنید

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

  • قسمت 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 حاوی نام 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 وضعیت آمادگی برای یک کار گزارش را بدست آورید.

از نام Report Task (مانند 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"
  }
}