صادرات مخاطب ایجاد کنید

مخاطبان در گوگل آنالیتیکس به شما این امکان را می‌دهند که کاربران خود را بر اساس اهمیت کسب و کارتان دسته‌بندی کنید. با مخاطبان، می‌توانید کاربران سایت یا اپلیکیشن خود را بر اساس ویژگی‌های مشترک گروه‌بندی کنید.

شما می‌توانید مخاطبان خود، از جمله تصویری از کاربرانشان، را با استفاده از Data API استخراج کنید.

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

نمای کلی

برای ایجاد و پرس و جو از خروجی مخاطبان، درخواست‌های API داده زیر را انجام دهید:

  1. برای ایجاد خروجی از مخاطبان، متد audienceExports.create را فراخوانی کنید.
  2. فراخوانی متد audienceExports.query برای بازیابی کاربران در audience استفاده می‌شود.

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

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

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

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

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

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

ایجاد خروجی مخاطب

برای ایجاد خروجی مخاطب، متد audienceExports.create را با استفاده از شیء AudienceExport در درخواست خود فراخوانی کنید. پارامترهای زیر الزامی هستند:

  • یک نام مخاطب معتبر در فیلد audience ، که به صورت properties/{propertyId}/audiences/{audienceId} قالب‌بندی شده است. می‌توانید از متد audiences.list از Google Analytics Admin API v1 برای به دست آوردن این مقدار استفاده کنید. فیلد Audience.name از پاسخ audiences.list حاوی نام مخاطب است.
  • فهرست معتبری از ابعاد در فیلد dimensions . فهرست ابعاد پشتیبانی شده توسط این روش را می‌توان در مستندات طرحواره خروجی مخاطب یافت. فقط داده‌های مربوط به ابعاد ذکر شده در این فیلد در خروجی مخاطب گنجانده می‌شود.

در اینجا یک نمونه درخواست برای ایجاد خروجی مخاطبان آورده شده است:

درخواست HTTP 

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

پاسخی از متد audienceExports.create شامل نام خروجی مخاطب در فیلد name است، برای مثال properties/1234567/audienceExports/123 . در اینجا یک نمونه پاسخ آورده شده است:

پاسخ HTTP 

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

شما می‌توانید از این name برای جستجوی کاربران از خروجی مخاطبان استفاده کنید.

وضعیت آمادگی خروجی مخاطب را بررسی کنید

ممکن است تولید خروجی audience پس از فراخوانی audienceExports.create چند دقیقه طول بکشد.

شما می‌توانید وضعیت آمادگی خروجی یک مخاطب را با فراخوانی متد audienceExports.get بررسی کنید.

از نام خروجی مخاطب از پاسخ audienceExports.create برای مشخص کردن خروجی مخاطب در درخواست خود استفاده کنید.

در اینجا یک نمونه درخواست آمده است:

درخواست HTTP 

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

وضعیت آمادگی برای خروجی گرفتن از مخاطب در فیلد state پاسخ برگردانده می‌شود. پس از اتمام تولید خروجی مخاطب، وضعیت آن از CREATING به ACTIVE تغییر می‌کند.

در اینجا یک نمونه پاسخ آمده است:

پاسخ HTTP 

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

شما می‌توانید وضعیت تمام خروجی‌های مخاطبان را با فراخوانی متد audienceExports.list به دست آورید.

بازیابی کاربران از خروجی مخاطبان

پس از ایجاد خروجی مخاطب، متد audienceExports.query را فراخوانی کنید و name خروجی مخاطب را در درخواست مشخص کنید.

در اینجا یک نمونه درخواست آمده است:

درخواست HTTP 

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

اگر خروجی مخاطب آماده باشد، این فراخوانی لیست کاربران موجود در مخاطب را برمی‌گرداند.

در اینجا یک نمونه پاسخ آمده است:

پاسخ HTTP 

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}