قوائم المستخدِمين المتكرّرة

يوضّح هذا المستند قوائم شرائح الجمهور المتكرّرة، وهي ميزة متقدّمة في الإصدار 1 من Google Analytics Data API. للحصول على مقدّمة عن ميزة تصدير قوائم المستخدِمين، اطّلِع على دليل أساسيات تصدير شرائح الجمهور.

تنتج قوائم المستخدمين المتكرّرة قوائم مستخدمين يوميًا مع تغيُّر عضويات المستخدمين، وذلك لضمان استخدام أحدث البيانات.

قوائم المستخدِمين العادية (غير المتكرّرة) هي قوائم ثابتة بالمستخدِمين في شريحة الجمهور في وقت إنشاء القائمة.

إنشاء قائمة مستخدمين جديدة يوميًا

تستغرق معالجة بيانات المستخدمين ليوم واحد وتعديل حالة العضوية مدة زمنية متغيرة. ما مِن طريقة للتأكّد من تعديل بيانات قائمة المستخدمين خلال 24 ساعة.

على سبيل المثال، حتى إذا طلبت قائمة مستخدمين في الوقت نفسه كل يوم، ستكون قائمة المستخدمين في بعض الأيام هي نفسها كما في اليوم السابق، وفي أيام أخرى، ستكون قائمة المستخدمين مختلفة وستتضمّن يومًا إضافيًا من تغييرات العضوية.

تستند قوائم المستخدمين إلى بيانات الأحداث من اليوم السابق لآخر تغييرات في العضوية. في حال إنشاء قائمة مستخدمين قبل حدوث تعديلات يومية على العضوية، سيتم استخدام البيانات من اليومين السابقين. في حال إنشاء قائمة مستخدمين بعد إجراء تعديلات يومية على العضوية، سيتم استخدام بيانات من اليوم السابق.

إجراء استطلاع بشكل دوري لقائمة مستخدمين متكرّرة

لا تُنشئ قوائم المستخدمين المتكرّرة قوائم مستخدمين إلا عند توفّر بيانات يوم إضافي. ويزيل هذا الإجراء الحاجة إلى التخمين عند تحديد الوقت المناسب لإنشاء قوائم مستخدمين جديدة. بدلاً من ذلك، يمكنك إجراء استطلاع رخيص التكلفة لقائمة المستخدمين المتكرّرين على مدار اليوم لمعرفة ما إذا كانت تتوفّر بيانات إضافية.

إنشاء قائمة مستخدمين متكرّرة

لإنشاء قائمة مستخدمين متكرّرة، استخدِم طريقة recurringAudienceLists.create مع العنصر RecurringAudienceList في الطلب. يجب توفير المَعلمات التالية:

• اسم صالح لشريحة الجمهور في حقل audience، بالتنسيق properties/{propertyId}/audiences/{audienceId} يمكنك استخدام طريقة audiences.list في الإصدار 1 من Google Analytics Admin API للحصول على هذه القيمة. يحتوي حقل Audience.name في الردّ audiences.list على اسم الجمهور.
• قائمة صالحة بالسمات في الحقل dimensions يمكنك الاطّلاع على قائمة السمات المتوافقة مع هذه الطريقة في مستندات مخطط تصدير شرائح الجمهور. يتم تضمين بيانات السمات المذكورة في هذا الحقل فقط في قائمة مستخدمين.

في ما يلي نموذج لطلب إنشاء قائمة مستخدمين متكرّرة:

طلب HTTP

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

تحتوي استجابة الطريقة recurringAudienceLists.create على الاسم في الحقل name (مثل properties/1234567/recurringAudienceLists/123)، والذي يمكن استخدامه في طلبات البحث اللاحقة لاسترداد البيانات الوصفية لإعدادات قائمة المستخدمين المتكرّرة هذه. بالإضافة إلى ذلك، تحتوي البيانات الوصفية للإعداد على أسماء موارد لنسخ من قوائم المستخدِمين تم إنشاؤها لقائمة المستخدِمين المتكرّرة هذه.

استجابة HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

البيانات الوصفية لإعدادات الاستطلاع

استخدِم طريقة recurringAudienceLists.get لاسترداد بيانات التعريف الخاصة بالإعدادات حول قائمة مستخدمين متكرّرة محدّدة. تحتوي البيانات الوصفية للإعداد على أسماء موارد لنسخ من قوائم المستخدِمين تم إنشاؤها لقائمة المستخدِمين المتكرّرة هذه.

وفي ما يلي مثال لذلك:

طلب HTTP

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

يتم عرض مثيل من RecurringAudienceList في الردّ. يحتوي على البيانات الوصفية للإعدادات، بما في ذلك أسماء الموارد لنسخ قوائم المستخدمين التي تم إنشاؤها لقائمة المستخدمين المتكرّرة هذه.

استجابة HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

يمكنك استخدام recurringAudienceLists.list لعرض جميع قوائم المستخدِمين المتكرّرة لموقع معيّن.

استخدام خطافات الويب لتلقّي إشعارات غير متزامنة بشأن قوائم المستخدمين الجديدة

بدلاً من إجراء استطلاع بشكل دوري للبيانات الوصفية الخاصة بإعدادات قائمة مستخدمين متكرّرة معيّنة باستخدام طريقة recurringAudienceLists.get، يمكنك تلقّي إشعارات Webhook بشكل غير متزامن عندما تصبح قائمة مستخدمين متاحة.

لضبط إعدادات إشعارات Webhook، حدِّد الحقل webhookNotification عند إنشاء قائمة مستخدمين متكرّرة جديدة.

اتّبِع دليل Async audience lists with webhooks للحصول على مزيد من المعلومات عن استخدام Webhooks في الإصدار 1 من Google Analytics Data API.

استرداد المستخدمين في عملية تصدير شريحة جمهور

لاسترداد المستخدمين في عملية تصدير شرائح الجمهور، استدعِ طريقة audienceExports.query وحدِّد اسم عملية تصدير شرائح الجمهور الذي تم استرداده من البيانات الوصفية للإعدادات التي يقدّمها recurringAudienceLists.get أو recurringAudienceLists.list.

طلب 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
}