Members

يمثّل مورد member عضوًا في قناة على YouTube. تقدّم العضوية دعمًا ماليًا متكررًا لصانع المحتوى مقابل الحصول على مزايا خاصة. على سبيل المثال، يمكن للأعضاء الدردشة عندما يفعّل صانع المحتوى وضع المحادثة الحصرية للأعضاء.

تنطبق قيود الوصول التالية:

  • تقتصر إمكانية الوصول إلى نقطتَي النهاية members وmembershipsLevels على صنّاع المحتوى في YouTube الذين لديهم برنامج مدير الشركاء في YouTube مخصّص لهم.
  • يتم منح الإذن بالوصول على مستوى القناة. بسبب هذه القائمة المسموح بها على مستوى القناة، لا يخضع نطاق OAuth‏ youtube.channel-memberships.creator لعملية التحقّق العادية من Google Cloud OAuth.

الطُرق

تتيح واجهة برمجة التطبيقات الطرق التالية لموارد member:

list
تعرض هذه السمة قائمة بالأعضاء (المعروفين سابقًا باسم "الجهات الراعية") في قناة معيّنة. يجب أن يوافق مالك القناة على طلب البيانات من واجهة برمجة التطبيقات.

تمثيل الموارد

تعرض بنية JSON التالية تنسيق مورد member:

{
  "kind": "youtube#member",
  "etag": etag,
  "snippet": {
    "creatorChannelId": string,
    "memberDetails": {
      "channelId": string,
      "channelUrl": string,
      "displayName": string,
      "profileImageUrl": string
    },
    "membershipsDetails": {
      "highestAccessibleLevel": string,
      "highestAccessibleLevelDisplayName": string,
      "accessibleLevels": [
        string
      ],
      "membershipsDuration": {
        "memberSince": datetime,
        "memberTotalDurationMonths": integer,
      },
      "membershipsDurationAtLevel": [
        {
          "level": string,
          "memberSince": datetime,
          "memberTotalDurationMonths": integer,
        }
      ]
    }
  }
}

الخصائص

يحدّد الجدول التالي السمات التي تظهر في هذا المرجع:

الخصائص
kind string
تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#member.
etag etag
تمثّل هذه السمة علامة Etag لهذا المورد.
snippet object
يحتوي العنصر snippet على تفاصيل حول العضو.
snippet.creatorChannelId string
معرّف قناة على YouTube الخاصة بصانع المحتوى الذي يقدّم العضويات.
snippet.memberDetails object
يحتوي هذا العنصر على بيانات الملف الشخصي للقناة على YouTube التي تدفع مقابل العضوية.

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

تتضمّن الردود من واجهة برمجة التطبيقات موارد لهؤلاء الأعضاء لضمان دقة الأعداد، على الرغم من عدم ضبط تفاصيل الملف الشخصي داخل الكائن memberDetails. وستظلّ membershipsDetails متاحة لهؤلاء الأعضاء.
snippet.memberDetails.channelId string
معرّف القناة على YouTube للقناة العضو في حال ضبط هذا الخيار، يمكن أيضًا اعتبار معرّف القناة معرّفًا فريدًا للعضو. في حال عدم ضبطها، لا يمكن التعرّف على العضو بشكل فريد، ولكن يظل المرجع ينقل تفاصيل العضوية، مثل المستويات التي يمكن للعضو الوصول إليها ومدة عضويته.
snippet.memberDetails.channelUrl string
عنوان URL الخاص بالقناة
snippet.memberDetails.displayName string
الاسم المعروض للقناة
snippet.memberDetails.profileImageUrl string
عنوان URL الخاص بأفاتار القناة
snippet.membershipsDetails object
يحتوي هذا العنصر على تفاصيل العضوية في القناة العضو.
snippet.membershipsDetails.highestAccessibleLevel string
معرّف أعلى مستوى عضوية يمكن للقناة العضو الوصول إليه حاليًا. تتطابق القيمة مع قيمة السمة id في مرجع membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
اسم أعلى مستوى عضوية يمكن للقناة العضو الوصول إليه حاليًا. تتوافق القيمة مع قيمة السمة displayName في مورد membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
قائمة بمعرّفات جميع مستويات العضوية التي يمكن للمستخدم الوصول إليها حاليًا. وتتضمّن القائمة المستوى النشط حاليًا وجميع المستويات الأدنى منه.
snippet.membershipsDuration object
يحتوي هذا العنصر على معلومات حول المدة الإجمالية لاشتراك العضو الحالي بغض النظر عن مستويات الأسعار. بعد ذلك، تحتوي السمة snippet.membershipsDetails.membershipsDurationAtLevel[] على قائمة بالعناصر التي تتضمّن تفاصيل حول فترة العضوية التي تمكّن خلالها العضو من الوصول إلى مستوى عضوية معيّن.

يوضّح المثال التالي طريقة عمل هذه السمات: يشتري أحد المشتركين اشتراكًا جديدًا في كانون الثاني (يناير) بمستوى العضوية 1 ويستمرّ هذا الاشتراك حتى آذار (مارس). في أبريل ومايو، لا يكون لدى العضو اشتراك. في يونيو، يعيد العضو تفعيل عضويته، مجددًا في المستوى 1. بعد ذلك، في شهر أغسطس، يرقّي العضو عضويته إلى المستوى 2. لذلك، إذا تم إجراء طلب بيانات من واجهة برمجة التطبيقات في شهر أكتوبر، سيتضمّن المورد member ما يلي: 
"membershipsDetails": {
  "membershipsDuration": {
    "memberSince": "2020-06-01T12:00:00",
    "memberTotalDurationMonths": 7,
  },
  "membershipsDurationAtLevel": [
    {
      "level": "level_1_ID",
      "memberSince": "2020-06-01T12:00:00",
      "memberTotalDurationMonths": 7
    },
    {
      "level": "level_2_ID",
      "memberSince": "2020-08-01T12:00:00",
      "memberTotalDurationMonths": 2
    },
  ]
}
snippet.membershipsDuration.memberSince datetime
تاريخ ووقت بدء اشتراك العضو الحالي بعبارة أخرى، كان لدى العضو اشتراك مستمر منذ هذا التاريخ والوقت. يُرجى العِلم أنّ فترات مختلفة من العضوية قد تكون في مستويات عضوية مختلفة.
snippet.membershipsDuration.memberTotalDurationMonths integer
عدد الأشهر التي كان فيها المستخدم مشتركًا، ويتم التقريب إلى أقرب عدد صحيح. تعكس القيمة عدد الأشهر الكاملة التي كان فيها المستخدم عضوًا في القناة، ولكنّها لا تعني أنّ العضوية كانت مستمرة طوال هذه الأشهر.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
قائمة بالعناصر، حيث يحتوي كل عنصر على تفاصيل حول فترة العضوية التي كان بإمكان العضو خلالها الوصول إلى مستوى عضوية معيّن. وتتضمّن القائمة عنصرًا واحدًا لكل مستوى عضوية يمكن للعضو الوصول إليه حاليًا.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
تمثّل هذه السمة معرّف مستوى العضوية. تتوافق القيمة مع قيمة السمة id في مورد membershipsLevel.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
تاريخ ووقت حصول العضو على مستوى العضوية المحدّد بعبارة أخرى، كان بإمكان العضو الوصول إلى المستوى بشكل مستمر منذ هذا التاريخ والوقت. يُرجى العِلم أنّ فترات مختلفة من العضوية قد تكون في مستويات عضوية أعلى.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
عدد الأشهر التي تمكّن فيها المستخدم من الوصول إلى المستوى المحدّد، ويتم تقريب العدد إلى أقرب عدد صحيح أصغر. تعكس القيمة عدد الأشهر الكاملة التي تمكّن فيها العضو من الاستفادة من المستوى، ولكنّها لا تعني أنّ العضوية كانت متاحة له بشكل متواصل طوال هذه الأشهر.