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

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

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

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

نظرة عامة

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

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

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

اختيار كيان إعداد التقارير

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

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

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

إذا كنت تستخدم إحدى مكتبات برامج عميل Data API، لن تحتاج إلى تغيير مسار عنوان URL للطلب. توفّر معظم برامج عميل واجهة برمجة التطبيقات مَعلمة 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 للاستعلام عن المستخدِمين من عملية تصدير شريحة الجمهور.

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

قد يستغرق إنشاء عملية تصدير شريحة الجمهور عدة دقائق بعد استدعاء 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
}