Method: properties.audienceLists.query

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

اطّلِع على إنشاء قائمة مستخدمين للحصول على مقدّمة عن قوائم المستخدمين مع أمثلة.

تتيح لك شرائح الجمهور في "إحصاءات Google‏ 4" تقسيم المستخدِمين بالطرق التي تمثّل أهمية بالنسبة إلى نشاطك التجاري. لمزيد من المعلومات، يُرجى الاطّلاع على https://support.google.com/analytics/answer/9267572.

تتوفّر هذه الطريقة في الإصدار التجريبي المستقر في audienceExports.query. لتقديم ملاحظاتك وآرائك حول واجهة برمجة التطبيقات هذه، يُرجى ملء نموذج ملاحظات وآراء عن Audience Export API في "إحصاءات Google".

طلب HTTP

POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}:query

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المعلمات
name

string

مطلوب. اسم قائمة الجمهور لاسترداد المستخدِمين منها. التنسيق: properties/{property}/audienceLists/{audienceList}

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "offset": string,
  "limit": string
}
الحقول
offset

string (int64 format)

اختيارية: عدد الصفوف في صف البدء. يتم احتساب الصف الأول على أنّه الصف 0.

عند استخدام ميزة تقسيم الصفحات، لا يحدّد الطلب الأول القيمة المرجعية، أو يضبط القيمة المرجعية على 0، ويعرض الطلب الأول أول limit صفًا. يضبط الطلب الثاني البادئة على limit من الطلب الأول، ويعرض الطلب الثاني limit الثاني من الصفوف.

لمزيد من المعلومات عن مَعلمة تقسيم الصفحات هذه، اطّلِع على مقالة تقسيم الصفحات.
limit

string (int64 format)

اختيارية: عدد الصفوف المطلوب عرضها. إذا لم يتم تحديد عدد، يتم عرض 10,000 صف. تعرض واجهة برمجة التطبيقات 250,000 صف كحد أقصى لكل طلب، بغض النظر عن عدد الصفوف التي تطلبها. يجب أن تكون limit موجبة.

يمكن أن تعرِض واجهة برمجة التطبيقات أيضًا عدد صفوف أقل من limit المطلوبة، إذا لم تكن هناك قيم سمات بعدد limit.

لمزيد من المعلومات عن مَعلمة تقسيم الصفحات هذه، اطّلِع على مقالة تقسيم الصفحات.

نص الاستجابة

قائمة بالمستخدمين في قائمة جمهور

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "audienceRows": [
    {
      object (AudienceRow)
    }
  ],
  "audienceList": {
    object (AudienceList)
  },
  "rowCount": integer
}
الحقول
audienceRows[]

object (AudienceRow)

صفوف لكل مستخدم في قائمة جمهور سيكون عدد الصفوف في هذا الردّ أقل من أو يساوي حجم صفحة الطلب.
audienceList

object (AudienceList)

بيانات الإعداد عن AudienceList التي يتم الاستعلام عنها يتم عرضها للمساعدة في تفسير صفوف الجمهور في هذا الردّ. على سبيل المثال، تتطابق السمات في AudienceList هذه مع الأعمدة في AudienceRows.
rowCount

integer

إجمالي عدد الصفوف في نتيجة AudienceList لا تعتمد rowCount على عدد الصفوف التي يتم عرضها في الاستجابة ومَعلمة الطلب limit ومَعلمة الطلب offset. على سبيل المثال، إذا كان طلب البحث يعرض 175 صفًا ويتضمن limit من 50 في طلب بيانات واجهة برمجة التطبيقات، سيحتوي الردّ على rowCount من 175 صفًا ولكن 50 صفًا فقط.

لمزيد من المعلومات عن مَعلمة تقسيم الصفحات هذه، اطّلِع على مقالة تقسيم الصفحات.

نطاقات التفويض

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

AudienceRow

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

تمثيل JSON 
{
  "dimensionValues": [
    {
      object (AudienceDimensionValue)
    }
  ]
}
الحقول
dimensionValues[]

object (AudienceDimensionValue)

كل سمة قيمة سمة لمستخدم جمهور ستتم إضافة قيمة سمة واحدة لكل عمود سمة مطلوب.

AudienceDimensionValue

قيمة سمة.

تمثيل JSON 
{

  // Union field one_value can be only one of the following:
  "value": string
  // End of list of possible types for union field one_value.
}
الحقول
حقل الربط one_value نوع واحد من قيم السمات يمكن أن يكون one_value واحدًا فقط مما يلي:
value

string

القيمة كسلسلة إذا كان نوع السمة سلسلة.