إنشاء عملية تصدير لشرائح جمهور

تتيح لك شرائح الجمهور في "إحصاءات Google 4" تقسيم المستخدِمين بالطرق المهمة لنشاطك التجاري. باستخدام ميزة "شرائح الجمهور"، يمكنك تجميع مستخدمي موقعك الإلكتروني أو تطبيقك استنادًا إلى السمات المشتركة.

يمكنك تصدير شرائح الجمهور، بما في ذلك نبذة عن المستخدمين، باستخدام Data API.

يُرجى الرجوع إلى دليل توقّعات بيانات تصدير الجمهور للاطّلاع على معلومات مهمة عن البيانات التي تظهر لك في عمليات تصدير شرائح الجمهور.

نظرة عامة

أرسِل الطلبات التالية من Data API لإنشاء عملية تصدير شرائح جمهور وإجراء طلب بحث عنها:

  1. استدعِ الطريقة audienceExports.create لإنشاء عملية تصدير شرائح جمهور.
  2. يتم استخدام طريقة audienceExports.query لاسترداد بيانات المستخدِمين المُدرَجين في شريحة الجمهور.

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

اختيار كيان قائم بالإبلاغ

تتطلّب جميع طرق Data API تحديد معرّف الموقع على "إحصاءات Google 4" داخل مسار طلب عنوان URL، على شكل properties/GA4_PROPERTY_ID. وفي ما يلي مثال لذلك:

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

يستند التقرير إلى بيانات أحداث "إحصاءات Google" التي تم جمعها في موقع "إحصاءات Google 4" المحدّد.

إذا كنت تستخدم إحدى مكتبات برامج واجهة برمجة التطبيقات للبيانات، لن تحتاج إلى تغيير مسار عنوان URL للطلب. توفِّر معظم برامج واجهة برمجة التطبيقات مَعلمة property تتوقع وجود سلسلة في شكل properties/GA4_PROPERTY_ID. راجِع دليل البدء السريع للحصول على أمثلة على استخدام مكتبات البرامج.

إنشاء عملية تصدير لشرائح جمهور

لإنشاء عملية تصدير لشرائح الجمهور، استدعِ الطريقة audienceExports.create باستخدام الكائن AudienceExport في طلبك. المعلمات التالية مطلوبة:

  • اسم شريحة جمهور صالح في الحقل audience، ويكون بالتنسيق properties/{propertyId}/audiences/{audienceId} يمكنك استخدام الطريقة audiences.list في الإصدار 1 من Google Analytics Admin API للحصول على هذه القيمة. يحتوي الحقل 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
}