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

مخاطبان در Google Analytics به شما امکان می‌دهند کاربران خود را به روش‌هایی که برای کسب‌وکارتان مهم است تقسیم‌بندی کنید. با مخاطبان، می‌توانید کاربران سایت یا برنامه‌تان را براساس مشخصه‌های مشترک گروه‌بندی کنید.

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

برای کسب اطلاعات مهم درباره داده‌هایی که در صادر کردن مخاطبان می‌بینید، به راهنمای انتظارات داده‌های صادر کردن مخاطبان مراجعه کنید.

نمای کلی

برای ایجاد و پُرسمان کردن برون‌برد مخاطب، درخواست‌های زیر را به «میانای برنامه‌سازی کاربردی داده» ارسال کنید:

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

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

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

همه روش‌های «میانای برنامه‌سازی کاربردی داده» نیازمند این هستند که شناسه دارایی Google Analytics در مسیر درخواست نشانی وب، به‌صورت properties/GA_PROPERTY_ID، مشخص شود. مثالی در اینجا ارائه شده است:

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

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

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

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

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

  • نام مخاطب معتبری در فیلد 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 برای پُرسمان کردن کاربران از برون‌برد مخاطب استفاده کنید.

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

ممکن است پس‌از تماس 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
}