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

يوضّح هذا المستند قوائم شرائح الجمهور المتكرّرة، وهي ميزة متقدّمة في الإصدار 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 لسرد جميع قوائم المستخدِمين المتكرّرة لموقع.

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

بدلاً من الاستطلاع بشكل دوري عن البيانات الوصفية الخاصة بإعدادات قائمة مستخدمين متكرّرة محدّدة باستخدام طريقة 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
}